README.md•5.85 kB
# JSON DB MCP Server (FastAPI + FastMCP)
A minimal **Model Context Protocol (MCP)** server that also exposes a small **REST API**.
Data is stored in a single JSON file (`db.json`) as **collections** of items with auto-generated UUIDs.
- **MCP Tools:** `db.add_item`, `db.get_item`, `db.list_items`, `db.update_item`, `db.delete_item`
- **REST Endpoints:** `POST/GET/PUT/DELETE /db/{collection}[/{id}]`
- **Transports:** HTTP (recommended) and SSE (optional)
- **Stack:** Python, FastAPI, Uvicorn, FastMCP
---
## Features
- Simple JSON-file database with atomic writes
- Thread-safe in a single-process server using a lock
- Shared core logic for both **MCP tools** and **REST**
- Works with **VS Code Copilot (Chat)** and **Gemini CLI** as an MCP server
---
## Requirements
- Python **3.10+**
- [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`
- Git (optional, for version control)
---
## Project Layout
```
.
├─ main.py
├─ db.json # created on first write
└─ README.md
```
---
## Installation
### Using `uv` (recommended)
```bash
uv venv
uv pip install fastapi uvicorn fastmcp
```
### Using `pip`
```bash
python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn fastmcp
```
---
## Running
### Development (auto-reload)
```bash
uv run main.py
# or
uv run python main.py
# Server: http://localhost:8000
```
> **Default MCP transport:** HTTP at `/mcp/` (recommended).
> If you prefer SSE, see **MCP over SSE (optional)** below.
---
## REST API
All endpoints operate on a **collection** (created on first write) with items of shape:
```json
{
"id": "uuid-string",
"...": "fields you provide"
}
```
### Create
```bash
curl -X POST http://localhost:8000/db/users \
-H "Content-Type: application/json" \
-d '{"name":"Omar","role":"admin"}'
```
### List
```bash
curl http://localhost:8000/db/users
```
### Get by ID
```bash
curl http://localhost:8000/db/users/<ITEM_ID>
```
### Update
```bash
curl -X PUT http://localhost:8000/db/users/<ITEM_ID> \
-H "Content-Type: application/json" \
-d '{"role":"owner"}'
```
### Delete
```bash
curl -X DELETE http://localhost:8000/db/users/<ITEM_ID>
```
---
## MCP Server (HTTP transport, recommended)
This server mounts FastMCP’s **HTTP** transport at **`/mcp/`**.
### VS Code — GitHub Copilot (Chat)
1. Open **Copilot Chat** → **Tools** (or **Add MCP**).
2. **Transport:** `HTTP`
3. **URL:** `http://localhost:8000/mcp/` *(include the trailing slash)*
4. Enable the server. You should see tools:
- `db.add_item`, `db.get_item`, `db.list_items`, `db.update_item`, `db.delete_item`
**Using tools in chat:**
Select a tool from the list or ask:
> Use `db.add_item` with `collection="users"` and `payload={"name":"Omar"}`.
### Gemini CLI
Add the server via CLI (writes settings for you):
```bash
# Project-scoped (./.gemini/settings.json)
gemini mcp add --transport http jsondb http://localhost:8000/mcp/
# Or user-scoped (~/.gemini/settings.json)
gemini mcp add --scope user --transport http jsondb http://localhost:8000/mcp/
```
List tools:
```bash
gemini mcp list
```
Call a tool:
```bash
gemini mcp call jsondb db.add_item \
--args collection=users \
--args payload='{"name":"Omar"}'
```
---
## MCP over SSE (optional)
If you prefer SSE, change the mount in `main.py`:
```python
# replace the HTTP mount:
# mcp_http_app = mcp.http_app(path="/")
# app.mount("/mcp", mcp_http_app)
mcp_sse_app = mcp.sse_app()
app.mount("/mcp", mcp_sse_app) # SSE lives under /mcp/sse/
```
- **SSE endpoint:** `http://localhost:8000/mcp/sse/` *(note trailing slash)*
- **Copilot:** Transport = `SSE`, URL = `http://localhost:8000/mcp/sse/`
- **Gemini CLI:**
```bash
gemini mcp add --scope user --transport sse jsondb http://localhost:8000/mcp/sse/
```
> Many HTTP clients require a trailing slash for SSE endpoints; use `/mcp/sse/`.
---
## Health Check (optional)
Add this to `main.py` (after `app = FastAPI(...)`) if you want a friendly root:
```python
@app.get("/")
def health():
return {"ok": True, "rest": "/db/{collection}", "mcp": "/mcp/"}
```
---
## Persistence & Backups
- Data file: `db.json` (created on first write).
- Writes are **atomic**: a `db.json.tmp` is written then replaced.
- For safety, consider periodic snapshots (e.g., `cp db.json db.json.bak` in a cron job).
---
## Authentication (optional)
For local development MCP/REST are open.
If you need auth, simplest is an API key header via FastAPI middleware and **headers** in your MCP client configuration. Example:
```python
from fastapi import Request
from fastapi.responses import JSONResponse
import os
API_KEY = os.getenv("API_KEY", "")
@app.middleware("http")
async def api_key_guard(request: Request, call_next):
if API_KEY and request.headers.get("x-api-key") != API_KEY:
return JSONResponse(status_code=401, content={"detail": "Unauthorized"})
return await call_next(request)
```
- Copilot/Gemini: configure an `x-api-key` header in the MCP server settings.
---
## Troubleshooting
- **404 on `/`**
Expected. Use REST under `/db/...` and MCP at `/mcp/` (HTTP) or `/mcp/sse/` (SSE).
- **307 redirect** from `/mcp` → `/mcp/`
Some SSE clients don’t follow redirects. Use the **trailing slash** or disable redirect slashes:
```python
app.router.redirect_slashes = False
```
- **SSE returns 404**
Make sure you’re hitting `/mcp/sse/` (not `/mcp/`).
- **Concurrency**
Run as a **single process** for file-backed DB. Multi-process/worker deployments need a real DB or OS-level file locks.
- **Git push errors (VS Code AskPass socket)**
Unset helper vars or use GitHub CLI / SSH keys:
```bash
unset GIT_ASKPASS SSH_ASKPASS VSCODE_GIT_ASKPASS_NODE VSCODE_GIT_ASKPASS_MAIN
```
---
## License
Copyright© - Omar SOLIMAN