[josix]

Summary

Adds a per-project MCP server so the agent can look up the repo's own existing code and patterns before it implements anything.

• Server (engine/retrieval/mcp_server.py), stdio via FastMCP:
  • tools: search_domain_context, index_project, index_status
  • a ground_implementation(task) prompt
  • server instructions
  • a retrieval://index/status resource
• Code reuse: builds on the existing CLI query and index code. Stdout carries only MCP protocol messages.
• When indexes get built:
  • The keyword (lexical) index is built on the first query.
  • Heavier strategies (turbovec, pi-serini, hybrid, treesitter) are used only after index_project builds them.
  • The LLM-enriched lexical+ctx index is never built or overwritten implicitly. Building it still requires an explicit CLI run.
• Agent-facing behaviour:
  • Tool descriptions tell the agent to use search first.
  • Search never raises. Skipped strategies come back with a reason and the fix.
  • top_k is clamped to 25, and snippets are size-capped with a truncated flag.
• Performance:
  • Loaded indexes are cached in memory.
  • Each request walks the project files once.
  • Builds use a separate lock, so index_status and searches don't wait on a long build. While a build runs, pi-serini is skipped with a retry hint.
• Packaging:
  • retrieval mcp subcommand and retrieval-mcp script.
  • Optional mcp extra.
  • Registered through plugin.json mcpServers and scripts/retrieval-mcp.sh. There is no root .mcp.json, so opening this repo doesn't create a broken project-scope server.
• Skill: new domain-context-retrieval skill so agents check these tools on their own while working in a repo. It falls back to the CLI when the server is unavailable.
• Docs:
  • Updated the README, SETUP, USAGE, the CLI and environment-variable reference pages, the coding-agents how-to, and the changelog (Unreleased section).
  • Shell snippets now use set -- … "$@", so they work in zsh as well as bash.

Notes

• The engine/uv.lock diff is large mainly because a newer uv rewrote the lock format (revision 3 → 5). No dependency versions were bumped.
• No version bump; the changelog entry is under Unreleased.

Test plan

• uv run --directory engine python -m unittest discover -s tests: 582 tests, OK (18 skipped)
• ruff check and isort --check are clean on the changed Python files
• uv build produces the sdist and wheel
• A manual stdio initialize handshake through scripts/retrieval-mcp.sh succeeds
• After merging, reinstall the plugin and confirm plugin:agentic-retrieval:retrieval shows as connected in /mcp

🤖 Generated with Claude Code

https://claude.ai/code/session_019qtBjPUTJs57FUt6JJRk6K