agent-master-mcp/README.md

Model Context Protocol server exposing agent-master functionality to AI assistants for managing MCP server configurations across development tools

# 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:

```bash
# 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:
```bash
# Test the server
npx @modelcontextprotocol/inspector npx agent-master-mcp
```

### Installation

#### Option 1: NPM Package (Recommended)

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

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

#### Option 2: Development/Source

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

# Install dependencies
bun install

# Copy environment configuration
cp .env.example .env
```

### Development

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Run comprehensive test suite
bun run test:mcp
```

Tests verify:
- Tool availability and functionality
- Error handling
- Response formats
- Integration with daemon

### 3. Manual Testing

```bash
# 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

```bash
# 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:

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

#### Option 2: Using Global Installation

If installed globally:

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

#### Option 3: Development/Source

For development or source installation:

```json
{
  "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**
   ```bash
   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**
   ```bash
   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.