Ahnlich MCP

[osobotu]

This PR adds an MCP server for Ahnlich. Fixes #373

flowchart LR
    Agent["AI agent"] -->|"stdio"| MCP["ahnlich-mcp"]
    MCP -->|"DB profile: embeddings"| DB["ahnlich-db"]
    MCP -->|"AI profile: raw text"| AI["ahnlich-ai"]
    AI -->|"embeddings"| DB

Loading

• Adds db and ai profiles with profile-specific tool schemas.
• Exposes tools for store management, storage, similarity search, metadata filtering, and predicate indexes.
• Adds environment and CLI configuration plus a doctor connectivity command.
• Uses uv with Python 3.11 and the monorepo Python SDK.
• Separates tools, server setup, configuration, and backend communication.
• Centralizes shared backend behavior while preserving AI- and DB-specific logic.
• Adds unit, real-service integration, and MCP stdio tests.
• Adds CI with dependency/model caching and Docker-based integration testing.
• Documents installation, profiles, configuration, architecture, and development workflows.

[wizzywit]

After going through this implementation, there are some standards or optimization gaps that I think would be worth while to be implemented for this feature.

1. No tool annotations. drop_store and delete_by_metadata are irreversible, and ping/list_stores/server_info/get_by_metadata are read-only, but nothing is declared. FastMCP supports mcp.tool(annotations=ToolAnnotations(readOnlyHint=..., destructiveHint=..., idempotentHint=...)) — clients use these to gate confirmation prompts. This is the single highest-value addition for a server whose tools can wipe a store.

2. Errors are returned as successful results. error_response returns {"status": "error", ...} as a normal tool result, so isError is never set. The dict is LLM-legible, which is the important part, but protocol-level clients can't distinguish failure. Consider raising ToolError (or setting the error flag) while keeping the structured hint payload.

3. No read-only mode. An AHNLICH_MCP_READ_ONLY=1 that suppresses registration of drop_store / delete_by_metadata / drop_predicate_index would be cheap and is a common pattern for database MCP servers.

4. get_by_metadata and list_stores are unbounded. A predicate matching 100k entries returns all of them. Add a limit (with a sane default) and report truncation.

[wizzywit]

Overall the implementation looks solid.

• Transport errors are translated into domain exceptions carrying an actionable suggested_action, so a failing tool call tells the agent what to do rather than leaking a gRPC status.
• The server stays up when Ahnlich is unreachable (server.py:52-77) instead of dying at startup — right call for a stdio server whose client owns the process lifecycle.
• doctor is a genuinely useful operator affordance.
• Real end-to-end coverage through ClientSession in tests/integration/test_mcp_stdio.py, not just unit mocks.
• Reuses the in-repo sdk/ahnlich-client-py via [tool.uv.sources] rather than vendoring protobufs.

[wizzywit]

NON-BLOCKING (introduced by the fix for #383 (comment) — the validation itself is correct):

Missing separator in the implicit string concatenation, so the two sentences run together:

AHNLICH_AI_MODEL=bogus uv run ahnlich-mcp
ahnlich-mcp: error: Unsupported AI model 'bogus'.Supported models: all-minilm-l12-v2, all-minilm-l6-v2, bge-base-en-v1.5, bge-large-en-v1.5, jina-embeddings-v2-base-code

Suggested change

	f"Unsupported AI model {model!r}."
	f"Supported models: {supported}"
	f"Unsupported AI model {model!r}. "
	f"Supported models: {supported}"

I scanned the rest of mcp/src/ for the same pattern — this is the only occurrence, every other multi-line message keeps its trailing space.

While you're in this function: line 105 is whitespace-only. Same for backends/base.py:380,475,580. A ruff format --check step in mcp_test.yml would keep these from accumulating (raised in the review summary, not blocking).