harsha135135/agent-systems

Purpose and Entry Points

agent-systems is a hand-built Model Context Protocol (MCP) server using raw JSON-RPC 2.0 over stdin/stdout. It bridges MCP clients to retrieval-lab’s hybrid search and evaluation capabilities. The executable entry point is src/agent_systems/__main__.py; server startup and the stdio loop live in src/agent_systems/server.py.

Wire Protocol Layer

src/agent_systems/protocol.py owns JSON line framing, JSON-RPC envelopes, protocol error responses, and negotiation across MCP versions 2025-06-18, 2025-03-26, and 2024-11-05. This is the strict transport boundary: stdin is parsed as request/notification messages and stdout emits only serialized protocol responses.

MCP Lifecycle and Dispatch

src/agent_systems/server.py implements initialization, lifecycle state, tools/list, and tools/call dispatch. Notifications—especially notifications/initialized—receive no response because they have no request ID. Unsupported methods and malformed requests become JSON-RPC errors; tool execution failures remain successful RPC results containing isError: true.

Stdio Integrity Boundary

The process uses stdio transport only: stdout is protocol data, while diagnostics must go to stderr. During tool invocation, the server guards/redirects stdout so output from retrieval dependencies or handlers cannot inject non-JSON bytes into the session. This behavior is exercised against a real subprocess in tests/integration/test_stdio_session.py.

Tool Surface and Retrieval Integration

src/agent_systems/tools.py defines four MCP tools: search_documents, corpus_info, run_evaluation, and search_my_repos. Tools expose camelCase inputSchema metadata to MCP clients. Retrieval-lab imports are lazy: the server can complete protocol startup without the adjacent retrieval repository, and an unavailable dependency is reported as a readable tool-level error rather than a startup failure.

Primary Flow

1. A local MCP client launches python -m agent_systems and sends newline-delimited JSON-RPC on stdin.

2. The server negotiates protocol version during initialize, advertises only tool capability, then accepts the initialized notification.

3. tools/list returns schemas; tools/call validates arguments and invokes the mapped handler.

4. Search/evaluation tools cross into the external retrieval-lab runtime; results are transformed into MCP tool content and emitted as a JSON-RPC response.

5. Protocol failures stay at the JSON-RPC boundary; domain/dependency failures stay in tool results.

Runtime, Deployment, and Trust Boundaries

The runtime is Python, packaged from src/agent_systems with uv dependency locking in uv.lock and declared dependencies in pyproject.toml. It is intended as a local subprocess registered with MCP-aware clients via .mcp.json, not as an HTTP service. There is no authentication: the meaningful trust boundary is the local process and its filesystem access, including read-only local-repository grep.

Conformance Focus

Wire-level behavior is protected primarily by tests/unit/test_conformance.py, while tests/integration/test_stdio_session.py validates framing, flushing, stdout isolation, and malformed-message recovery through pipes. docs/handshake.md documents the expected initialize-to-tools lifecycle.