mcp-bridge/README.md

# mcp-bridge

The MCP-to-HTTP Bridge is a lightweight local service that translates HTTP requests into Model Context Protocol (MCP) calls, allowing standard web tools to communicate with local MCP adapters.

## Features

- HTTP to JSON-RPC translation for MCP adapters
- Configurable HTTP endpoints mapped to MCP methods
- Dynamic configuration reloading via SIGHUP or HTTP endpoint
- Structured JSON logging with configurable verbosity
- Graceful shutdown and process management
- Support for multiple concurrent adapters

## Quick Install

To install the `mcp-bridge` binary to your local system, run the following command:

```bash
curl -sSL https://git.nixc.us/colin/mcp-bridge/raw/branch/main/install.sh | bash
```

This will download the appropriate binary for your system from the `dist` directory and place it in your path.

For custom installation options:

```bash
# Install to a custom directory
curl -sSL https://git.nixc.us/colin/mcp-bridge/raw/branch/main/install.sh | bash -s -- --dir=$HOME/bin
```

## Usage

To run the bridge:

```bash
mcp-bridge -port 8091 -v info -config config.yaml
```

Options:
- `-port`: HTTP server port (overrides the port in config.yaml)
- `-v`: Log verbosity level (debug, info, warn, error)
- `-config`: Path to the configuration file (default: config.yaml)
- `-version`: Show version information and exit

## Configuration

The bridge is configured using YAML files. A main `config.yaml` file defines the port and a set of services, and each service has its own YAML file defining its endpoints and the command to run its MCP adapter.

### Main Configuration File (config.yaml)

```yaml
port: 8091
services:
  service1:
    config: service1.yaml
    command:
      - /path/to/adapter
      - --arg1
      - --arg2
  service2:
    config: service2.yaml
    command:
      - /path/to/another/adapter
```

### Service Configuration File (service1.yaml)

```yaml
serviceName: service1
endpoints:
  - path: /api/v1/method1
    mcp_method: method1
    tool_name: tool1
  - path: /api/v1/method2
    mcp_method: method2
    tool_name: tool2
```

## Configuration Reload

The bridge supports dynamic configuration reloading without restarting the service. There are two ways to trigger a reload:

1. Send a SIGHUP signal to the process:
   ```bash
   kill -SIGHUP <pid>
   ```

2. Send a POST request to the `/reload` endpoint:
   ```bash
   curl -X POST http://localhost:8091/reload
   ```

When a reload is triggered:
1. The configuration is reloaded from the config file
2. Existing services are gracefully shut down
3. New services are started based on the updated configuration
4. HTTP handlers are re-registered

Note: The HTTP server port cannot be changed during a reload.

## Making Requests

To call an MCP adapter method, send an HTTP request to the configured endpoint:

```bash
curl -X POST http://localhost:8091/path/to/endpoint -d '{"param1": "value1", "param2": "value2"}'
```

The request body will be passed as parameters to the MCP method, and the response from the adapter will be returned as the HTTP response.

### Error Handling

JSON-RPC errors returned by the adapter are translated to HTTP status codes:
- JSON-RPC errors are returned with HTTP 400 (Bad Request)
- Other errors are returned with HTTP 500 (Internal Server Error)

## Building from Source

To build the project from source:

```bash
git clone https://git.nixc.us/colin/mcp-bridge.git
cd mcp-bridge
./build-test-deploy.sh
```

This will:
1. Run all tests
2. Build binaries for multiple platforms (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64)
3. Create checksum files
4. Stage the binaries for commit

## Development

### Project Structure

```
mcp-bridge/
├── bin/                  # Compiled binaries for testing
├── dist/                 # Distribution binaries
├── src/                  # Source code
│   ├── main.go           # Main application
│   ├── handler/          # HTTP handlers
│   └── logger/           # Structured logging
├── test/                 # Tests
│   ├── adapter/          # Mock adapter for testing
│   └── integration_test.go # Integration tests
├── config.yaml           # Example configuration
├── service1.yaml         # Example service configuration
├── build-test-deploy.sh  # Build script
└── install.sh            # Installation script
```

### Running Tests

```bash
# Run unit tests
go test ./src/...

# Run integration tests
go test ./test
```

## License

See the [LICENSE](LICENSE) file for details.