mcp-bridge
README.md
# mcp-bridge: a safe MCP server over your documents and invoice checks
A reference build of a **Model Context Protocol (MCP) server**: lets Claude Desktop, Claude Code, ChatGPT-style clients or any MCP client call your tools safely. Six read-only tools, no network, no model calls, **zero running cost**.
| Tool | Does |
|---|---|
| `search_documents` | BM25 search over a folder of .md/.txt. Verbatim passages with file, section, line. `weak_match` says "probably not in the documents" instead of guessing |
| `read_document` | Read part of one file (sandboxed path, line range) |
| `list_documents` | What can be searched, and which files were skipped and why |
| `check_invoice_math` | Recompute subtotal, tax, discount, total from line items (Decimal, never float). Flags ambiguous amounts like `1.100` |
| `find_duplicate_invoices` | Exact, near (one character changed) and possible duplicates |
| `server_status` | Health, uptime, counts, limits |
## Run it
```
pip install -r requirements.txt
set MCPBRIDGE_DOCS_ROOT=demo_docs (Windows; export on Mac/Linux)
set PYTHONPATH=src
python -m mcpbridge
```
Claude Desktop / any MCP client config:
```json
{ "mcpServers": { "mcp-bridge": { "command": "python", "args": ["-m", "mcpbridge"],
"env": { "PYTHONPATH": "C:/path/to/mcp-bridge/src", "MCPBRIDGE_DOCS_ROOT": "C:/path/to/your/docs" } } } }
```
Settings (all optional, bad values fall back to safe defaults): `MCPBRIDGE_MAX_FILE_BYTES`, `_MAX_FILES`, `_MAX_QUERY_CHARS`, `_MAX_K`, `_MAX_OUTPUT_CHARS`, `_CALL_TIMEOUT_S`, `_MAX_CONCURRENT`, `_MAX_CALLS_PER_MIN`, `MCPBRIDGE_LOG` (audit file; empty disables).
## What happens when things go wrong (the point of this build)
| Failure | Behaviour |
|---|---|
| Any bug inside a tool | One structured tool error `{code, message, hint}`; traceback goes to the log only; server keeps running |
| Bad or hostile input (wrong type, empty, huge, out of range) | Rejected up front with a stable code (`bad_k`, `query_too_long`, ...) |
| Path traversal, absolute paths, symlink escape | `outside_root`. Containment is checked **before** existence, so `../x` gives the same answer whether or not x exists (no probing) |
| A tool that hangs | Abandoned at the time limit with `timeout`; work is also size-capped |
| Flood of calls | `rate_limited` / `busy` immediately, no unbounded queue |
| Huge reply | Capped and flagged `truncated` |
| Missing / empty docs folder, binary, oversized or badly-encoded file | Server starts anyway; says exactly what is wrong; bad files are skipped and listed, never fatal |
| Files change while running | Index refreshes itself; deleted files disappear, no stale hits |
| Prompt injection inside a document | Returned as data with an untrusted-content notice; tools are read-only so there is nothing to hijack |
| Audit log cannot be written | Reported on stderr; the call still succeeds |
| Protocol corruption | Nothing is ever printed to stdout except protocol messages |
Every row above has a test. `pytest` runs 52 tests, including an end-to-end suite that spawns the server and attacks it over the real MCP protocol.
## Honest limits
- Search is keyword (BM25), not semantic. It is fast, free and explainable; a semantic/vector layer is an add-on (see the Ask-My-Shop project).
- `weak_match` is a heuristic (share of question words found), not proof.
- Invoice tools check numbers you give them; they do not read PDFs and cannot prove a vendor is real.
- A timed-out call is abandoned, not killed (Python threads); bounded inputs keep this theoretical.
- The symlink-escape test is skipped on Windows without developer mode.
- Pinned to the MCP Python SDK 1.x (`mcp<2`); 2.x renamed its server API.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues