# MCPMan

A Model Context Protocol (MCP) server manager that acts as a proxy/multiplexer for multiple MCP servers.

## Overview

MCPMan allows you to:
- Connect to multiple MCP servers simultaneously (stdio and HTTP transports)
- Generate and execute code from natural language descriptions using LLMs
- Execute JavaScript code with access to all connected MCP tools
- Invoke tools from multiple servers with batch and parallel execution
- Manage server configurations with OAuth 2.1 support
- Dynamically add new servers without restarting
- Store and access tool results through $results array

## Quick Start

### Installation

```bash
bun install
```

### Initialize Configuration

```bash
mcpman init
```

### Add MCP Servers

```bash
# Add stdio server
mcpman add filesystem --command npx --args @modelcontextprotocol/server-filesystem

# Add HTTP server with OAuth
mcpman add api-server --url https://api.example.com/mcp
```

### Generate and Execute Code from Natural Language

The `code` tool uses LLMs (via Claude Agent SDK or MCP sampling) to generate JavaScript code from natural language descriptions. Generated code is validated with TypeScript compiler before execution.

```bash
# Generate code from description
mcpman code "list all files in the current directory"

# Generate code with custom root directories
mcpman code "read the package.json file and show the dependencies" --roots /path/to/project
```

**Features:**
- **Automatic Code Generation**: LLM writes JavaScript code to accomplish your task
- **TypeScript Validation**: Generated code is validated with TypeScript compiler API (with up to 3 retries if validation fails)
- **Type-Safe API**: Generated TypeScript definitions provide autocomplete and type checking for all MCP tools
- **Server Filtering**: Optional `servers` parameter limits which MCP servers are available to reduce context size and improve code quality
- **$results Integration**: Generated code results are automatically stored in `$results` array

When using as an MCP tool, strongly recommend specifying the `servers` parameter to limit context:

```javascript
// Good - limits context to only playwright tools
{
  functionDescription: "navigate to google.com and take a screenshot",
  servers: ["playwright"]
}

// Avoid - includes all servers which may result in poor performance
{
  functionDescription: "navigate to google.com and take a screenshot"
}
```

### Evaluate Function Expressions with MCP Tools

```bash
# Simple function with no arguments
mcpman eval "() => listServers()"

# Function with argument
mcpman eval "(arg) => filesystem.listFiles({ path: arg.directory })" --arg '{"directory": "."}'

# Specify custom root directories
mcpman eval "(arg) => filesystem.listFiles({ path: arg.path })" --arg '{"path": "/tmp"}' --roots /tmp

# Complex function with console output
mcpman eval "(arg) => { console.log('Processing:', arg.name); return arg.value * 2; }" --arg '{"name": "test", "value": 21}'
```

### Run as MCP Server

```bash
mcpman serve
```

## Architecture

MCPMan operates in two modes:

### Server Mode
- Acts as an MCP server exposing multiple tools:
  - `code` - Generate and execute JavaScript code from natural language descriptions using LLMs with TypeScript validation
  - `eval` - Execute JavaScript with access to all MCP tools
  - `invoke` - Batch invoke tools with parallel/sequential execution
  - `list_servers` - List connected servers and their tools
  - `help` - Get documentation for specific tools
  - `install` - Dynamically add new servers
- Connects to multiple upstream MCP servers
- Transparently forwards root directory information from clients to upstream servers
- Provides unified JavaScript execution environment with $results array

### CLI Mode
- Direct command-line interface for server management
- Execute JavaScript code with MCP tool access
- Configure and test server connections

## Configuration

Configuration is stored in `~/.mcpman/settings.json`:

```json
{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {},
      "disabled": false,
      "timeout": 30000
    },
    "api-server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "headers": {},
      "oauth": {
        "clientName": "mcpman",
        "redirectUrl": "http://localhost:3000/callback",
        "scopes": ["mcp:tools"],
        "clientId": "optional-client-id",
        "clientSecret": "optional-client-secret"
      },
      "disabled": false,
      "timeout": 30000
    }
  }
}
```

## CLI Commands

```bash
# Server management
mcpman init                          # Initialize configuration
mcpman add <name>                    # Add new server
mcpman list                          # List configured servers
mcpman validate                      # Validate configuration
mcpman test                          # Test server connections

# Execution
mcpman code "description" [--roots /path]                  # Generate and execute code from natural language
mcpman eval "function-expr" [--arg '{}'] [--roots /path]   # Execute function expression with MCP tools
mcpman serve                                               # Run as MCP server

# Authentication
mcpman auth <server-name>            # Authenticate with OAuth server
```

## JavaScript Execution Environment

> **Inspired by [Cloudflare's Code Mode](https://blog.cloudflare.com/code-mode/)** - Instead of directly calling MCP tools, LLMs write code that interacts with a JavaScript API. This approach leverages LLMs' strength in writing code and enables more sophisticated tool chaining and composition.

In the eval environment, each configured server is available as a global object. All code must be provided as function expressions:

```javascript
// No argument function - list servers
() => listServers()

// Function with argument - list files
(arg) => filesystem.listFiles({ path: arg.directory })

// Complex function with multiple operations
(arg) => {
  console.log("Processing directory:", arg.path);
  const files = filesystem.listFiles({ path: arg.path });
  return files.filter(f => f.name.endsWith('.js'));
}

// Async function with multiple server calls
async (arg) => {
  const servers = listServers();
  console.log("Available servers:", servers);
  const result = await someServer.someTool({ param: arg.value });
  return result;
}

// Access previous results via $results array
() => {
  console.log("Previous result:", $results[0]);
  return $results[0];
}
```

### $results Array

When using the `eval` or `invoke` tools as an MCP client, results are automatically stored in the `$results` array. Each tool invocation appends its result to this array, and you can access previous results by index:

```javascript
// After calling invoke or eval, results are stored
$results[0]  // First result
$results[1]  // Second result
```

## Batch Tool Invocation

The `invoke` tool allows you to call multiple MCP tools in batch mode:

```javascript
// Sequential execution (stops on first error)
{
  calls: [
    { server: "filesystem", tool: "read_file", parameters: { path: "package.json" } },
    { server: "filesystem", tool: "read_file", parameters: { path: "README.md" } }
  ],
  parallel: false
}

// Parallel execution (all tools execute concurrently)
{
  calls: [
    { server: "filesystem", tool: "list_directory", parameters: { path: "." } },
    { server: "git", tool: "status", parameters: {} }
  ],
  parallel: true
}
```

## Logging

When running in server mode, MCPMan redirects console output to log files:

- **Main log**: `~/.mcpman/mcpman.log` - All console.log/error/warn/info output
- **Trace log**: `~/.mcpman/trace.log` - Detailed trace logging (requires `MCPMAN_TRACE=1`)

Logs use synchronous writes to ensure all messages are captured, even during crashes. Error objects are formatted with full stack traces and causes.

```bash
# Enable trace logging
MCPMAN_TRACE=1 mcpman serve

# View logs
tail -f ~/.mcpman/mcpman.log
tail -f ~/.mcpman/trace.log
```

## Development

### Setup

```bash
bun install
pre-commit install  # Install git hooks
```

### Available Scripts

```bash
bun dev              # Development server with hot reload
bun run build        # Build compiled binary
bun run lint         # Lint code
bun run format       # Format code
bun run typecheck    # Type check
bun test             # Run tests
```

### Code Style

- TypeScript with strict type checking
- Biome for linting and formatting (100 char line width, 2-space indents)
- Zod schemas for configuration validation
- Pre-commit hooks ensure code quality

## MCP Protocol Support

MCPMan fully supports the MCP protocol including:
- Tool discovery and execution
- Root directory management (transparent proxy)
- Request/response handling
- Error propagation
- OAuth 2.1 authentication for HTTP transports

## License

MIT