npm package: @manualsoftware/mcp
Description: STDIO MCP bridge for Manual Process Store - connects STDIO-based MCP clients to remote Manual servers
Latest version: 0.1.0

# @manualsoftware/mcp

STDIO MCP bridge for Manual Process Store. Connects STDIO-based MCP clients (Claude Desktop, Cursor, etc.) to remote Manual Process Store servers using HTTP Streamable transport.

## Features

- **Transport Proxy**: Bridges STDIO transport to HTTP Streamable transport
- **Full MCP Support**: Proxies tools, prompts, and resources
- **Dynamic Discovery**: Tools are discovered dynamically from the remote server
- **API Key Authentication**: Authenticates with the server using X-API-Key header
- **Simple Configuration**: Configure via CLI arguments or environment variables

## Installation

```bash
npm install -g @manualsoftware/mcp
```

Or use directly via `npx` (no installation needed):

```bash
npx @manualsoftware/mcp --server http://localhost:8082/mcp/create --api-key sk-xxx
```

## Usage

### Command Line

```bash
# Using CLI arguments
npx @manualsoftware/mcp --server http://localhost:8082/mcp/create --api-key sk-your-api-key

# Using environment variables
MANUAL_SERVER=http://localhost:8082/mcp/create MANUAL_API_KEY=sk-your-api-key npx @manualsoftware/mcp
```

### Claude Desktop Configuration

Add to `~/.config/claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "manual": {
      "command": "npx",
      "args": ["@manualsoftware/mcp", "--server", "http://localhost:8082/mcp/create"],
      "env": {
        "MANUAL_API_KEY": "sk-your-api-key"
      }
    }
  }
}
```

### Cursor Configuration

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "manual": {
      "command": "npx",
      "args": ["@manualsoftware/mcp", "--server", "http://localhost:8082/mcp/create"],
      "env": {
        "MANUAL_API_KEY": "sk-your-api-key"
      }
    }
  }
}
```

## Options

- `--server <url>` or `MANUAL_SERVER`: URL of your Manual MCP endpoint (required)
  - For process creation tools: `http://your-server:8082/mcp/create`
  - For process following tools: `http://your-server:8082/mcp/follow`
- `--api-key <key>` or `MANUAL_API_KEY`: API key for authentication (required)

## How It Works

This bridge acts as an MCP transport proxy:

1. Accepts MCP connections from STDIO-based clients (Claude Desktop, Cursor)
2. Connects to your Manual MCP server using HTTP Streamable transport
3. Proxies all MCP requests (tools, prompts, resources) between the two transports
4. Authenticates with the server using your API key in the `X-API-Key` header

```
┌─────────────────────────────────────────────────────────────┐
│  STDIO MCP Client (Claude Desktop, Cursor)                  │
└────────────────────┬────────────────────────────────────────┘
                     │ STDIO (stdin/stdout)
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  @manualsoftware/mcp (Transport Proxy)                      │
│  - StdioServerTransport ← receives MCP from local client    │
│  - StreamableHTTPClientTransport → remote server            │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP Streamable + X-API-Key
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  Manual MCP Server                                          │
│  - /mcp/create (creation tools)                             │
│  - /mcp/follow (following tools)                            │
└─────────────────────────────────────────────────────────────┘
```

## Requirements

- Node.js 18.0.0 or higher
- Access to a Manual Process Store MCP server
- Valid API key for authentication

## Troubleshooting

### Authentication Failed

If you see "Authentication failed", check:
- Your API key is correct
- The API key has proper permissions on the server
- The server URL is correct and includes the MCP endpoint path (e.g., `/mcp/create`)

### Connection Errors

If you see connection errors:
- Verify the server URL is correct and reachable
- Ensure you're using the full MCP endpoint path (e.g., `http://localhost:8082/mcp/create`)
- Check your network connection
- Ensure the server is not behind a firewall blocking your access

### No Tools Found

If tools aren't appearing:
- Check the stderr output for connection messages
- Verify the MCP server is running on the expected port
- Try connecting to `/mcp/create` for creation tools or `/mcp/follow` for following tools

## Development

```bash
# Clone the repository
git clone <repository-url>
cd ManualSTDIOBridge

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js --server http://localhost:8082/mcp/create --api-key sk-xxx
```

## License

MIT