Agent Master MCP Server

Model Context Protocol server that exposes agent-master functionality to AI assistants, enabling programmatic control over MCP server configurations across multiple development tools.

Features

• Engine Control: Manage MCP server configurations (add, remove, enable/disable)
• Discovery: Find MCP servers via blockchain discovery and project scanning
• Synchronization: Sync configurations across development tools (Claude Code, VS Code, Cursor, etc.)
• Daemon Management: Monitor and control the agent-master daemon
• Auto-sync: Automatic configuration synchronization

Quick Start

Installation & Usage

The easiest way to get started:

# Install the package
npm install -g agent-master-mcp

# Add to Claude Code configuration
claude mcp add agent-master "agent-master-mcp"

Or use directly with npx:

# Test the server
npx @modelcontextprotocol/inspector npx agent-master-mcp

Installation

Option 1: NPM Package (Recommended)

# Install globally
npm install -g agent-master-mcp

# Or install locally in your project
npm install agent-master-mcp

Option 2: Development/Source

# Clone the repository
git clone <repository-url>
cd agent-master-mcp

# Install dependencies
bun install

# Copy environment configuration
cp .env.example .env

Development

# Start with hot reload
bun run dev

# Start with MCP Inspector for interactive testing
bun run dev:inspector

# Run automated tests
bun run test:mcp

# Type check
bun run typecheck

Production

# Build the server
bun run build

# Start the server
bun run start

Tools

Engine Control

• engine_list_servers - List all configured MCP servers
• engine_add_server - Add a new MCP server
• engine_remove_server - Remove an MCP server
• engine_enable_server - Enable a server for syncing
• engine_disable_server - Disable a server
• engine_get_server - Get detailed server information

Discovery

• discovery_discover_servers - Find servers via blockchain discovery
• discovery_scan_projects - Scan directories for MCP projects
• discovery_add_project - Register a project for tracking

Synchronization

• sync_to_all - Sync configurations to all development tools
• sync_preview - Preview sync changes
• autosync_status - Check auto-sync status
• autosync_enable - Enable automatic syncing
• autosync_disable - Disable automatic syncing

Daemon Management

• daemon_status - Check daemon status
• daemon_logs - View recent daemon logs

Development Workflow

1. Interactive Development with MCP Inspector

# Start the development environment with Inspector
bun run dev:inspector

This starts:

• The MCP server with hot reload
• MCP Inspector UI at http://localhost:6274
• Interactive testing environment

Use the Inspector to:

• Test tools interactively
• View server logs and notifications
• Explore available resources
• Debug tool calls

2. Automated Testing

# Run comprehensive test suite
bun run test:mcp

Tests verify:

• Tool availability and functionality
• Error handling
• Response formats
• Integration with daemon

3. Manual Testing

# Quick tool testing
npx @modelcontextprotocol/inspector bun run src/index.ts

# Test specific tool
npx @modelcontextprotocol/inspector bun run src/index.ts -- tools call daemon_status

Configuration

Environment Variables

# Logging
LOG_LEVEL=DEBUG  # DEBUG, INFO, WARN, ERROR

# Daemon Connection
DAEMON_HOST=localhost
DAEMON_PORT=50051

# Development
NODE_ENV=development
MCP_DEVELOPMENT=true

Claude Code Integration

Option 1: Using NPM Package

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "agent-master": {
      "command": "npx",
      "args": ["agent-master-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Option 2: Using Global Installation

If installed globally:

{
  "mcpServers": {
    "agent-master": {
      "command": "agent-master-mcp",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Option 3: Development/Source

For development or source installation:

{
  "mcpServers": {
    "agent-master": {
      "command": "bun",
      "args": ["run", "/path/to/agent-master-mcp/src/index.ts"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Architecture

gRPC Client Integration

• Connects to agent-master daemon via gRPC (port 50051)
• Uses shared daemon for consistency with desktop app and CLI
• Handles connection failures gracefully

Blockchain Discovery

• Integrates with existing discovery system from agent-master app
• Finds published MCP servers on BSV blockchain
• Enables community server sharing

Comprehensive Logging

• Structured logging with different levels
• Tool call tracking and performance metrics
• Development and production log modes
• Integration with MCP Inspector notifications

Security

Authentication

• Uses bitcoin-auth for secure operations
• Integrates with existing agent-master authentication
• No plaintext key transmission

Authorization

• Respects daemon's permission system
• Validates all inputs with Zod schemas
• Sandboxed tool execution

Troubleshooting

Common Issues

Daemon Connection Failed

Error: Failed to connect to agent-master daemon

• Ensure agent-master daemon is running
• Check DAEMON_HOST and DAEMON_PORT configuration
• Verify gRPC connectivity

Tool Calls Timing Out

• Check daemon logs: daemon_logs
• Verify daemon status: daemon_status
• Increase timeout in configuration

Discovery Not Working

• Blockchain discovery may take time
• Check network connectivity
• Verify BSV node availability

Development Debugging

1. Enable Debug Logging

   LOG_LEVEL=DEBUG bun run dev:inspector

2. Use MCP Inspector

   • Check Notifications pane for real-time logs
   • Test tools individually in Tools tab
   • Monitor server connection status

3. Run Test Suite

   bun run test:mcp

Contributing

Development Setup

1. Fork and clone the repository
2. Install dependencies: bun install
3. Copy .env.example to .env
4. Start development server: bun run dev:inspector
5. Make changes and test with Inspector
6. Run test suite: bun run test:mcp
7. Submit pull request

Code Style

• TypeScript with strict mode
• ESLint for linting
• Structured error handling
• Comprehensive logging
• Zod for input validation

License

MIT License - see LICENSE file for details.