Skip to content

robotdad/amplifier-module-tool-mcp-old

BranchesTags

Repository files navigation

Amplifier MCP Tool Module

Modular capability that adds Model Context Protocol (MCP) server integration to Amplifier bundles.

Overview

This module enables Amplifier to connect to MCP servers and expose their capabilities (Tools, Resources, Prompts) to LLM agents. Connect to any MCP-compatible server and make its tools available to your AI agents.

What You Get:

  • 🔌 Multi-server orchestration - Connect to multiple MCP servers simultaneously
  • 🚀 Dual transport support - stdio and Streamable HTTP (2025-03-26 MCP spec)
  • 🔄 Auto-reconnection - Exponential backoff with circuit breaker for resilience
  • 🛡️ Content protection - Automatic truncation to prevent context exhaustion
  • 📊 Health monitoring - Track server status and connection health
  • 🔇 Clean console - Server logs saved to files, not cluttering output

Production Proven: 60 capabilities from 5 MCP servers (41 tools + 19 prompts)

Status: ✅ Production Ready | Version: 0.2.2 | Tests: 52/52 passing

Installation

Recommended: Always-Available MCP Support

Add MCP capabilities to all your Amplifier sessions with a single command:

amplifier bundle add git+https://github.com/microsoft/amplifier-module-tool-mcp@main#subdirectory=behaviors/mcp.yaml --app

The --app flag registers MCP as an "app bundle" that automatically composes with every session, regardless of which primary bundle you use. Configure your servers in ~/.amplifier/mcp.json and they'll be available everywhere.

Quick Demo with Example Servers

Try MCP immediately with pre-configured servers (repomix, context7, deepwiki):

amplifier bundle add git+https://github.com/microsoft/amplifier-module-tool-mcp@main#subdirectory=examples/bundle.md
amplifier bundle use mcp-example

This example bundle includes foundation and comes with repomix, context7, and deepwiki servers pre-configured.

Prerequisites

  • Python 3.11+
  • UV - Fast Python package manager

Installing UV

# macOS/Linux/WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

Recommended: Include the Behavior

Add MCP capability to your bundle by including the behavior:

---
bundle:
  name: my-bundle
  version: 1.0.0
  description: My custom bundle with MCP support

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
  - bundle: git+https://github.com/microsoft/amplifier-module-tool-mcp@main#subdirectory=behaviors/mcp.yaml
---

# Your bundle instructions...

What this gives you:

  • ✅ MCP tool module configured with production defaults
  • ✅ Content size protection enabled (50k char limit)
  • ✅ Clean console output (server logs saved to files)
  • ✅ Automatic server discovery from .amplifier/mcp.json
  • ✅ Clean dependency chain (no redundant includes)

Why this pattern?

  • You control your foundation version
  • Explicit about what capabilities you're adding
  • Production-ready defaults out of the box
  • Easy to customize configuration if needed

Alternative: Direct Module Integration

You can also add the module directly with custom configuration:

---
bundle:
  name: my-bundle
  version: 1.0.0

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main

tools:
  - module: tool-mcp
    source: git+https://github.com/microsoft/amplifier-module-tool-mcp@main
    config:
      verbose_servers: true  # Custom: show server output
      max_content_size: 100000  # Custom: larger content limit
---

# Your bundle instructions...

For Module Development

If you're developing the tool-mcp module itself:

cd amplifier-module-tool-mcp
uv sync

Quick Start

1. Add MCP to Your Bundle

# your-bundle.md
includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
  - bundle: git+https://github.com/microsoft/amplifier-module-tool-mcp@main#subdirectory=behaviors/mcp.yaml

2. Configure MCP Servers

Create .amplifier/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Popular MCP Servers:

  • @modelcontextprotocol/server-postgres - PostgreSQL database operations
  • @modelcontextprotocol/server-puppeteer - Web automation and scraping
  • @modelcontextprotocol/server-sqlite - SQLite database operations
  • @modelcontextprotocol/server-brave-search - Web search via Brave API
  • See MCP Server Registry for more

Note: Amplifier's built-in filesystem and bash tools are recommended for file operations and shell commands rather than MCP filesystem servers.

3. Use Your Bundle

amplifier bundle use your-bundle.md
amplifier run "What MCP tools are available?"

The agent will automatically discover and use tools from your configured MCP servers!

Complete Example

See examples/mcp-example.md for a complete working bundle showing:

  • How to include the MCP behavior in your bundle
  • Server configuration examples
  • Usage instructions
  • Customization options

Configuration

Module Configuration Options

The module can be configured via bundle behavior or direct module inclusion:

# In your bundle.md
tools:
  - module: tool-mcp
    source: git+https://github.com/microsoft/amplifier-module-tool-mcp@main
    config:
      # Server output control
      verbose_servers: false  # Default: suppress MCP server debug output
      server_log_dir: ~/.amplifier/logs/mcp-servers/  # Where logs are saved when suppressed
      
      # Content size protection (prevents context exhaustion)
      max_content_size: 50000  # Default: 50k chars (~12k tokens)

      # Optional inline server config (overrides .amplifier/mcp.json)
      servers:
        my-server:
          command: npx
          args: ["-y", "my-mcp-server"]

Configuration options:

Option Default Description
verbose_servers false Show MCP server stderr output in console
server_log_dir ~/.amplifier/logs/mcp-servers/ Directory for server logs when suppressed
max_content_size 50000 Maximum content size in characters. Content exceeding this limit is automatically truncated with a notice to prevent context window exhaustion
servers (optional) Inline server configuration (overrides .amplifier/mcp.json)

Environment variable override:

# Enable verbose output without changing bundle config
AMPLIFIER_MCP_VERBOSE=true amplifier run "test"

When to use verbose mode:

  • Debugging MCP server connection issues
  • Diagnosing tool execution failures
  • Understanding server initialization

Default behavior (quiet):

  • Clean console output
  • Server logs saved to ~/.amplifier/logs/mcp-servers/{server-name}.log
  • Check logs if server connection fails

Configuration Priority

  1. Inline config (servers in bundle config) - highest priority
  2. Project config (.amplifier/mcp.json) - recommended
  3. User config (~/.amplifier/mcp.json) - fallback
  4. Environment variable (AMPLIFIER_MCP_CONFIG) - override

Usage

How MCP Tools Appear to Agents

Once configured, MCP server tools become available like any other Amplifier tool:

User: "List files in the project"

Agent: [Uses mcp_filesystem_list_directory tool from MCP server]
Response: [Directory listing from MCP filesystem server]

All MCP tools are prefixed with mcp_{server}_{tool} to avoid naming conflicts.

Example: Using Multiple MCP Servers

---
bundle:
  name: data-assistant
  version: 1.0.0

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
  - bundle: git+https://github.com/microsoft/amplifier-module-tool-mcp@main#subdirectory=behaviors/mcp.yaml
---

You are a data assistant with access to databases and web automation via MCP.

Use postgres tools for database operations.
Use puppeteer tools for web scraping and automation.

With .amplifier/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Agent gets tools like:

  • mcp_postgres_query - Execute SQL queries
  • mcp_postgres_list_tables - List database tables
  • mcp_puppeteer_navigate - Navigate to URLs
  • mcp_puppeteer_screenshot - Capture screenshots

Development

Local Development Setup

When developing the module locally, use the file:// protocol to test changes without pushing to GitHub:

# 1. Clone and set up the module
cd ~/your-workspace
git clone https://github.com/microsoft/amplifier-module-tool-mcp.git
cd amplifier-module-tool-mcp
uv sync

# 2. Run tests
uv run pytest tests/ -v

# 3. Create a local development bundle
# See examples/bundle-local-dev.md for a template

# 4. Add your local bundle
amplifier bundle add file://$(pwd)/examples/bundle-local-dev.md

# 5. Use the bundle
amplifier bundle use mcp-local-dev

# 6. Test your changes
amplifier run "list your tools"

Important: Cache Management

Amplifier caches bundles on first load. When you make changes to your local module, you must clear the cache:

# Clear MCP module cache
find ~/.amplifier/cache -type d -name "amplifier-module-tool-mcp-*" -exec rm -r {} +

# Then reload your bundle
amplifier run "test command"

Local Bundle Example (examples/bundle-local-dev.md):

---
bundle:
  name: mcp-local-dev
  version: 1.0.0
  description: Local development bundle for testing MCP changes

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main

tools:
  - module: tool-mcp
    source: file:///absolute/path/to/amplifier-module-tool-mcp
    config:
      servers:
        repomix:
          command: npx
          args: ["-y", "repomix", "--mcp"]
---

You are an AI assistant with MCP server capabilities enabled (LOCAL DEV VERSION).

Running Tests

# Run all tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_integration.py -v

# Run with coverage
uv run pytest tests/ --cov=amplifier_module_tool_mcp --cov-report=html

Documentation

See complete documentation in:

  • EXECUTIVE_SUMMARY.md - Overview and status
  • SDK_CAPABILITIES.md - What the SDK provides
  • GAP_ANALYSIS.md - Feature analysis
  • PHASE4_SUMMARY.md - Latest features

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages