# mcpbridge

> One YAML file. Any data source. Instant MCP server.

[![npm version](https://img.shields.io/npm/v/mcpbridge)](https://www.npmjs.com/package/mcpbridge)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/your-handle/mcpbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/your-handle/mcpbridge/actions)

**mcpbridge** turns a YAML config file into a working [MCP](https://modelcontextprotocol.io) server — no code required.

Point it at a database, a REST API, or a folder of Markdown files. Claude (or any MCP client) can query them immediately.

---

## What It Does

- **`db_query`** — run parameterized SQL queries against PostgreSQL, SQLite, or MySQL
- **`get_endpoint`** — call any REST GET endpoint and expose the result as an MCP tool
- **`knowledge_base`** — serve `.md` files or directories as MCP resources

All three can live in a single `config.yaml`. Swap the YAML, restart — done.

---

## 5-Minute Quickstart

### With npx (no install)

```bash
# 1. Create a config file
cat > config.yaml << 'EOF'
server:
  name: weather-mcp
  version: 1.0.0
  transport: stdio

sources:
  - type: get_endpoint
    name: get_weather
    description: >
      Returns current weather for a location given latitude and longitude.
      Use when the user asks about weather or temperature.
    url: https://api.open-meteo.com/v1/forecast
    query_params:
      - name: latitude
        type: float
        required: true
      - name: longitude
        type: float
        required: true
    response_field: current_weather
EOF

# 2. Validate it
npx mcpbridge validate config.yaml

# 3. Add to Claude Desktop (see below) and ask: "What's the weather in Amsterdam?"
```

### With Docker

```bash
docker run \
  -v ./config.yaml:/app/config.yaml \
  --env-file .env \
  mcpbridge/mcpbridge
```

---

## Claude Desktop Setup

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcpbridge", "run", "/absolute/path/to/config.yaml"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}
```

---

## YAML Reference

### `db_query` — SQL query as MCP tool

```yaml
- type: db_query
  name: get_orders               # snake_case, becomes tool name
  description: >                 # LLM reads this — be specific about when to use it
    Returns all orders for a specific user.
    Use when asked about order history or purchases.
  query: >
    SELECT id, product, amount, status
    FROM orders
    WHERE user_id = :user_id
  params:
    - name: user_id
      type: integer              # string | integer | boolean | float
      required: true
  connection: "${DATABASE_URL}"  # always an env var — never hardcode
  allow_write: false             # default: false — set true only for explicit write tools
```

**Supported databases:** PostgreSQL (`postgresql://`), MySQL (`mysql://`), SQLite (`sqlite://./path.db`)

**Read-only by default.** INSERT/UPDATE/DELETE/DROP are blocked unless `allow_write: true`. DDL (DROP/ALTER/CREATE) is always blocked.

---

### `get_endpoint` — REST GET as MCP tool

```yaml
- type: get_endpoint
  name: get_weather
  description: >
    Returns current weather forecast for a given latitude and longitude.
    Use when the user asks about weather or temperature.
  url: https://api.open-meteo.com/v1/forecast
  query_params:
    - name: latitude
      type: float
      required: true
    - name: longitude
      type: float
      required: true
  headers:
    Authorization: "Bearer ${API_KEY}"   # env var substitution in headers too
  response_field: current_weather        # optional: extract nested field (dot notation)
  timeout: 30                            # seconds, default: 30
```

---

### `knowledge_base` — Markdown files as MCP resources

```yaml
- type: knowledge_base
  name: company_faq
  description: >
    Internal company FAQ and policies.
    Use when the user asks about company procedures or rules.
  path: ./kb/                    # file or directory (recursive)
  strategy: chunk                # full | chunk
  chunk_size: 800                # chars per chunk (default: 800)
  chunk_overlap: 100             # overlap between chunks (default: 100)
```

Hidden files (`.hidden.md`) and directories (`.git/`) are skipped automatically.

---

## Full Example Config

```yaml
server:
  name: my-company-mcp
  version: 1.0.0
  transport: stdio

sources:
  - type: get_endpoint
    name: get_weather
    description: >
      Returns current weather for a location.
      Use when the user asks about weather.
    url: https://api.open-meteo.com/v1/forecast
    query_params:
      - name: latitude
        type: float
        required: true
      - name: longitude
        type: float
        required: true
    response_field: current_weather

  - type: db_query
    name: get_orders
    description: >
      Returns orders for a specific user.
      Use when the user asks about their order history.
    query: "SELECT id, product, amount, status FROM orders WHERE user_id = :user_id"
    params:
      - name: user_id
        type: integer
        required: true
    connection: "${DATABASE_URL}"

  - type: knowledge_base
    name: company_faq
    description: >
      Company FAQ and internal policies.
      Use when the user asks about company procedures.
    path: ./kb/
    strategy: chunk
    chunk_size: 800
```

---

## Running Locally

```bash
# Install
npm install -g mcpbridge
# or without installing:
npx mcpbridge

# Validate a config
mcpbridge validate config.yaml

# Run the server
DATABASE_URL=sqlite://./dev.db mcpbridge run config.yaml
```

## Running with Docker

```bash
# Build locally
docker build -t mcpbridge .

# Run with a config
docker run \
  -v ./config.yaml:/app/config.yaml \
  -v ./kb:/app/kb \
  --env-file .env \
  mcpbridge

# Or with docker-compose (includes PostgreSQL)
docker compose up
```

---

## Security Notes

- **Secrets always via env vars.** The YAML schema rejects connection strings not using `${ENV_VAR}` syntax.
- **Read-only DB by default.** Set `allow_write: true` explicitly per source to enable mutations.
- **DDL is never allowed.** DROP/ALTER/CREATE/TRUNCATE are blocked regardless of `allow_write`.
- **No auth on the MCP server** in v0.1 — run behind a firewall or VPN. Auth is on the v0.2 roadmap.

---

## Let Claude Configure It For You

1. Share your CLAUDE.md with Claude (or just point Claude at this repo)
2. Say: *"Configure mcpbridge for my [restaurant / e-commerce store / SaaS app]. Here's what it does: ..."*
3. Claude generates a complete `config.yaml` and `.env.example`
4. Run `mcpbridge validate config.yaml` to verify, then deploy

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Roadmap

See [ROADMAP.md](ROADMAP.md).

## License

MIT — see [LICENSE](LICENSE).