Skip to main content
Glama

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:

{ "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).

Related MCP server: Project Files Read-only MCP

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables local ChatGPT/OpenAI MCP clients to read files and search within explicitly authorized directories using read-only, policy-constrained tools.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables secure, read-only access to local project files (including text, DOCX, PDF, and XLSX) through MCP, with strict directory whitelisting and no write, edit, or command-execution tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides local, read-only MCP tools that expose a specified workspace's directory listing, file contents, text search, git status, and git diff to AI clients.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables privacy-preserving document retrieval by exposing read-only search tools over MCP, allowing agents to query local vector and structured indexes without sending data to the cloud.
      2
      MIT