feat(mcp): F-14 MCP-server — read-only KB tools for LLM clients #4

user2595 · 2026-06-14T07:00:15Z

user2595 commented

2026-06-14 07:00:15 +00:00

Summary

codex/mcp_server.py: FastMCP server, 7 read-only tools (search, ask, wiki_read, wiki_list, discover_leads, provenance_verify, synthesis_browse)
stdio default + optional HTTP transport with token-auth
codex/config.py: MCP settings (mcp_transport, mcp_host, mcp_port, mcp_auth_token); F-13 duplicate block removed
pyproject.toml: mcp[cli]>=1.0 dep + codex-mcp console_script
README.md: Claude Code .mcp.json + Claude Desktop registration snippets
28 new tests in tests/mcp/

Key properties (Review-Gate verified)

Read-only invariant: write-verb regex + frozen allowlist in test_readonly.py — fails if any write tool is added
HTTP token-auth: _require_http_token() raises before ASGI app starts; tested for missing + present token
Graceful degradation: all optional features (wiki, synthesis) return {"error": "not available"}, no crash
Provenance on every hit: SQL enforces p.bibkey IS NOT NULL; test asserts full key-set per result

Gate result

APPROVE — all 4 CRITICAL + 4 WARN checks PASS

243 tests total · ruff + mypy clean

## Summary - `codex/mcp_server.py`: FastMCP server, 7 read-only tools (search, ask, wiki_read, wiki_list, discover_leads, provenance_verify, synthesis_browse) - stdio default + optional HTTP transport with token-auth - `codex/config.py`: MCP settings (mcp_transport, mcp_host, mcp_port, mcp_auth_token); F-13 duplicate block removed - `pyproject.toml`: `mcp[cli]>=1.0` dep + `codex-mcp` console_script - `README.md`: Claude Code `.mcp.json` + Claude Desktop registration snippets - 28 new tests in `tests/mcp/` ## Key properties (Review-Gate verified) - **Read-only invariant**: write-verb regex + frozen allowlist in `test_readonly.py` — fails if any write tool is added - **HTTP token-auth**: `_require_http_token()` raises before ASGI app starts; tested for missing + present token - **Graceful degradation**: all optional features (wiki, synthesis) return `{"error": "not available"}`, no crash - **Provenance on every hit**: SQL enforces `p.bibkey IS NOT NULL`; test asserts full key-set per result ## Gate result **APPROVE** — all 4 CRITICAL + 4 WARN checks PASS 243 tests total · ruff + mypy clean

user2595 added 3 commits 2026-06-14 07:00:16 +00:00

feat(mcp): FastMCP server exposing read-only KB tools (stdio) b803811701

Implements F-14: thin FastMCP wrapper over existing codex domain modules.
Seven read-only tools: search, ask, wiki_read, wiki_list, discover_leads,
provenance_verify, synthesis_browse. All optional-feature tools degrade
gracefully to {"error": "feature not available"} instead of crashing.
Adds mcp[cli]>=1.0 dependency and codex-mcp console_script entry-point.
28 new tests across test_server, test_search, test_readonly, test_graceful,
test_http_auth — all green; 0 regressions in existing 172 tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(mcp): client registration (Claude Code / Desktop) b2ef8f2575

Documents MCP server setup for Claude Code (.mcp.json) and Claude Desktop
(claude_desktop_config.json), HTTP transport config, and available tools table.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(config): remove duplicate F-13 settings block (merge artefact) 50e6bb8210

F-13 settings (leads_dir, synthesis_llm_*, synthesis_top_k,
synthesis_min_grounded_ratio, synthesis_gap_min_coverage) appeared twice
due to independent commits on F-13 and F-14 branches. Kept the second
(more complete) block; removed the first.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

user2595 merged commit 50e6bb8210 into main

2026-06-14 11:52:08 +00:00

user2595 deleted branch feat/F-14-mcp-server

2026-06-14 11:52:09 +00:00

user2595 referenced this issue from a commit

2026-06-26 20:51:23 +00:00

fix(review): address PR #16 code-review findings

user2595 referenced this issue from a commit

2026-06-27 07:09:41 +00:00

test(review): cover findings #1 (non-bare caller id) and #4 (backfill connection scope)

Sign in to join this conversation.