feat: MCP server — let agents call session search over stdio#6
feat: MCP server — let agents call session search over stdio#6lupuletic wants to merge 2 commits into
Conversation
Adds a `code-recall mcp` subcommand that serves an MCP stdio server, turning code-recall into a retrieval tool any agent (Claude Code, Codex) can call instead of grepping ~/.claude transcripts by hand. Why MCP-over-stdio rather than a remote server or a bare CLI: the CLI already has --json, so the real gap was agent-native integration. stdio is the documented transport for local tools with direct filesystem/DB access, and Claude Code's Tool Search loads MCP tools on demand so a focused tool set doesn't bloat context. Shipping it as a subcommand of the existing binary keeps it to one install. Tools exposed (FastMCP, structured output): - search_sessions(query, limit, provider, project) -> ranked hits with title, project, provider, score, why-matched, snippet, resume command. Supports file:/cmd:/branch: prefixes. - get_session_detail(session_id) -> files, commands, branch, model, prompts, resume command. The server honors the same --db / --claude-dir / --codex-dir flags as the rest of the CLI (paths captured in the tool closures), runs a quick incremental index before each query, and stays local-only. mcp is a new optional dependency: `code-recall[mcp]`, also folded into `[all]`. Uses typing_extensions.TypedDict for pydantic schema-gen on Python < 3.12. Tests: 6 new tool-layer tests (call_tool against a temp index with the reindex stubbed) plus a manual stdio round-trip against a real index. 342 pass.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1bbdd7cc00
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| results = search(query, db_path=db_path, limit=limit, project_filter=project) | ||
| if provider: | ||
| results = [r for r in results if r.session.provider == provider] | ||
| return [_to_hit(r) for r in results[:limit]] |
There was a problem hiding this comment.
search_sessions fetches only limit unfiltered results and then applies the provider filter in Python, so in mixed-provider datasets a valid provider can appear to have no matches just because its sessions rank below the first limit global hits. This makes MCP results incomplete/incorrect for provider="claude" or provider="codex" queries when both providers are indexed.
Useful? React with 👍 / 👎.
| conn = get_connection(db_path) | ||
| try: | ||
| row = conn.execute( | ||
| "SELECT * FROM sessions WHERE session_id = ?", (session_id,) | ||
| ).fetchone() |
There was a problem hiding this comment.
get_session_detail reads directly from SQLite without calling _ensure_fresh_index, unlike search_sessions. If a new session has been written to transcripts but not yet indexed, this tool can return None or stale metadata for an otherwise valid session_id, which violates the freshness behavior documented for MCP queries.
Useful? React with 👍 / 👎.
| mcp = ["mcp>=1.2"] | ||
| all = ["code-recall[semantic,tui,mcp]"] |
There was a problem hiding this comment.
This commit introduces a new user-visible command (code-recall mcp) and documentation surface but keeps the package version unchanged (0.2.5). Under this repo’s versioning policy, user-visible behavior changes must bump version metadata, otherwise installed artifacts are indistinguishable across feature boundaries and release/version checks can drift.
Useful? React with 👍 / 👎.
Adds `code-recall mcp install` — registers the MCP server with every
supported agent CLI found on PATH, so setup for both providers is a
single command:
pip install 'code-recall[all]' && code-recall mcp install
Under the hood it runs (idempotently — removes any stale entry first):
claude mcp add --scope user code-recall -- code-recall mcp
codex mcp add code-recall -- code-recall mcp
Verified end-to-end against real CLIs: Claude Code reports "✓ Connected";
Codex registers as an enabled stdio server (the "Unsupported" it shows is
the Auth column — stdio servers don't do OAuth, same as any other local
MCP server). If an agent CLI is absent it's skipped with a note rather
than failing.
README now leads the MCP section with the one-liner and documents the
manual commands in a details block.
Tests: +2 (no-CLI fallback returns 1; both-CLIs path issues add for each).
344 pass.
1 participant
Summary
Adds an MCP stdio server so a coding agent (Claude Code and Codex) can call fast, ranked session retrieval instead of grepping
~/.claude/~/.codextranscripts by hand.One-line install + setup for both agents:
code-recall mcp installregisters the server with every agent CLI on PATH (idempotent). Restart the agent and ask it to find a past session.Why MCP-over-stdio (and not a remote server or a bare CLI)
--json, so "build a CLI" was largely done — the real gap was agent-native integration.Tools exposed
search_sessions(query, limit, provider, project)file:/cmd:/branch:prefixes.get_session_detail(session_id)Built with FastMCP, structured output via
TypedDict(typing_extensions.TypedDictfor pydantic schema-gen on Python < 3.12).Install command
code-recall mcp installruns, idempotently (removes stale entry first):Missing CLIs are skipped with a note; succeeds if at least one agent is configured.
Notes
--db/--claude-dir/--codex-dirflags as the rest of the CLI (paths captured in the tool closures), runs a quick incremental index before each query, stays local-only.mcpis a new optional dependency:code-recall[mcp], also folded into[all].Testing
tests/test_mcp_server.py): tool listing, hit shape, limit, provider filter, detail round-trip, missing-id handling, plus install fallback (no CLI → exit 1) and dual-agent registration.code-recall mcp installagainst actual CLIs — Claude Code reports✓ Connected; Codex registers as an enabled stdio server. Confirmed a full stdio round-trip (initialize→list_tools→search_sessions→get_session_detail) against the installedcode-recall mcpbinary returns well-formed structured results.Test plan
pip install 'code-recall[all]' && code-recall mcp installclaude mcp listshowscode-recall ✓ Connected;codex mcp listshows it enabledsearch_sessions