# harsha135135/agent-systems architecture

> Architecture diagram of the GitHub repository harsha135135/agent-systems, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsha135135/agent-systems
- Repository: https://github.com/harsha135135/agent-systems

## Overview

#### 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.

Main entry points: [`src/agent_systems/server.py`](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py) (Stdio server loop), [`src/agent_systems/protocol.py`](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/protocol.py) (JSON-RPC protocol), [`src/agent_systems/tools.py`](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/tools.py) (Search and evaluation tools), [`.mcp.json`](https://github.com/harsha135135/agent-systems/blob/main/.mcp.json) (Local MCP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MCP Client"]
  node_mcp_client(("Local MCP client<br/>MCP consumer<br/>[.mcp.json]"))
end

subgraph group_server["agent-systems Process"]
  node_entrypoint["Module entry point<br/>Python entry<br/>[__main__.py]"]
  node_stdio_server["Stdio server loop<br/>server runtime<br/>[server.py]"]
  node_protocol["JSON-RPC protocol<br/>transport boundary<br/>[protocol.py]"]
  node_stdin["stdin requests<br/>JSONL input"]
  node_stdout["stdout responses<br/>JSONL output"]
  node_lifecycle["MCP lifecycle<br/>state handling<br/>[server.py]"]
  node_tool_catalog["Tool catalog<br/>MCP metadata<br/>[tools.py]"]
  node_tool_dispatch["Tool dispatch<br/>handler routing<br/>[server.py]"]
  node_tools["Search and evaluation tools<br/>MCP tools<br/>[tools.py]"]
  node_tool_errors["Tool-level errors<br/>MCP result content<br/>[server.py]"]
  node_package["Python package<br/>packaging<br/>[pyproject.toml]"]
end

subgraph group_external["Retrieval Runtime"]
  node_retrieval_lab{{"retrieval-lab<br/>external Python runtime"}}
  node_local_filesystem[("Local repositories<br/>filesystem access")]
end

subgraph group_quality["Conformance"]
  node_handshake_docs["Handshake guide<br/>protocol documentation<br/>[handshake.md]"]
  node_conformance_tests["Wire conformance tests<br/>unit tests"]
  node_stdio_integration["Stdio session tests<br/>integration tests"]
end

node_mcp_client -->|"launches"| node_entrypoint
node_entrypoint -->|"starts"| node_stdio_server
node_mcp_client -->|"JSON-RPC JSONL"| node_stdin
node_stdin -->|"parse and validate"| node_protocol
node_protocol -->|"validated messages"| node_stdio_server
node_stdio_server -->|"initialize / initialized"| node_lifecycle
node_stdio_server -->|"tools/list"| node_tool_catalog
node_stdio_server -->|"tools/call"| node_tool_dispatch
node_tool_dispatch -->|"invoke handler"| node_tools
node_tools -->|"lazy import and execute"| node_retrieval_lab
node_tools -->|"repository grep"| node_local_filesystem
node_retrieval_lab -.->|"unavailable or domain failure"| node_tool_errors
node_tool_errors -->|"isError result"| node_stdio_server
node_stdio_server -->|"responses and RPC errors"| node_protocol
node_protocol -->|"serialize JSONL"| node_stdout
node_stdout -->|"protocol responses"| node_mcp_client
node_package -.->|"packages"| node_entrypoint
node_handshake_docs -.->|"documents"| node_lifecycle
node_conformance_tests -.->|"verifies"| node_protocol
node_stdio_integration -.->|"verifies subprocess boundary"| node_stdio_server

click node_mcp_client "https://github.com/harsha135135/agent-systems/blob/main/.mcp.json"
click node_entrypoint "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/__main__.py"
click node_stdio_server "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py"
click node_protocol "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/protocol.py"
click node_lifecycle "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py"
click node_tool_catalog "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/tools.py"
click node_tool_dispatch "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py"
click node_tools "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/tools.py"
click node_tool_errors "https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py"
click node_package "https://github.com/harsha135135/agent-systems/blob/main/pyproject.toml"
click node_handshake_docs "https://github.com/harsha135135/agent-systems/blob/main/docs/handshake.md"
click node_conformance_tests "https://github.com/harsha135135/agent-systems/blob/main/tests/unit/test_conformance.py"
click node_stdio_integration "https://github.com/harsha135135/agent-systems/blob/main/tests/integration/test_stdio_session.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_client toneBlue
class node_entrypoint,node_stdio_server,node_protocol,node_stdin,node_stdout,node_lifecycle,node_tool_catalog,node_tool_dispatch,node_tools,node_tool_errors,node_package toneAmber
class node_retrieval_lab,node_local_filesystem toneMint
class node_handshake_docs,node_conformance_tests,node_stdio_integration toneRose
```

## Components

### MCP Client

- [Local MCP client](https://github.com/harsha135135/agent-systems/blob/main/.mcp.json): MCP consumer · Launches the server and communicates over pipes. · `.mcp.json`

### agent-systems Process

Local Python subprocess using stdio only.

- [Module entry point](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/__main__.py): Python entry · `src/agent_systems/__main__.py`
- [Stdio server loop](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py): server runtime · Owns startup, lifecycle, dispatch, and stdout isolation. · `src/agent_systems/server.py`
- [JSON-RPC protocol](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/protocol.py): transport boundary · Frames JSON lines, validates envelopes, negotiates MCP versions, and emits RPC errors. · `src/agent_systems/protocol.py`
- **stdin requests**: JSONL input · Request and notification messages.
- **stdout responses**: JSONL output · Reserved exclusively for serialized protocol responses.
- [MCP lifecycle](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py): state handling · Initialize negotiation and initialized notification handling. · `src/agent_systems/server.py`
- [Tool catalog](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/tools.py): MCP metadata · Lists four camelCase input schemas. · `src/agent_systems/tools.py`
- [Tool dispatch](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py): handler routing · Validates call arguments and maps calls to handlers. · `src/agent_systems/server.py`
- [Search and evaluation tools](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/tools.py): MCP tools · search_documents, corpus_info, run_evaluation, and search_my_repos. · `src/agent_systems/tools.py`
- [Tool-level errors](https://github.com/harsha135135/agent-systems/blob/main/src/agent_systems/server.py): MCP result content · Dependency and domain failures use successful RPC results with isError. · `src/agent_systems/server.py`
- [Python package](https://github.com/harsha135135/agent-systems/blob/main/pyproject.toml): packaging · Dependencies are declared in pyproject.toml and locked with uv. · `pyproject.toml`

### Retrieval Runtime

- **retrieval-lab**: external Python runtime · Lazily imported hybrid search and evaluation dependency.
- **Local repositories**: filesystem access · Read-only repository grep operates within local process trust.

### Conformance

- [Handshake guide](https://github.com/harsha135135/agent-systems/blob/main/docs/handshake.md): protocol documentation · Documents initialize-to-tools lifecycle. · `docs/handshake.md`
- [Wire conformance tests](https://github.com/harsha135135/agent-systems/blob/main/tests/unit/test_conformance.py): unit tests · Protect JSON-RPC and MCP wire behavior. · `tests/unit/test_conformance.py`
- [Stdio session tests](https://github.com/harsha135135/agent-systems/blob/main/tests/integration/test_stdio_session.py): integration tests · Exercises a real subprocess, framing, flushing, isolation, and recovery. · `tests/integration/test_stdio_session.py`

## Connections

- Local MCP client → Module entry point: launches
- Module entry point → Stdio server loop: starts
- Local MCP client → stdin requests: JSON-RPC JSONL
- stdin requests → JSON-RPC protocol: parse and validate
- JSON-RPC protocol → Stdio server loop: validated messages
- Stdio server loop → MCP lifecycle: initialize / initialized
- Stdio server loop → Tool catalog: tools/list
- Stdio server loop → Tool dispatch: tools/call
- Tool dispatch → Search and evaluation tools: invoke handler
- Search and evaluation tools → retrieval-lab: lazy import and execute
- Search and evaluation tools → Local repositories: repository grep
- retrieval-lab → Tool-level errors: unavailable or domain failure
- Tool-level errors → Stdio server loop: isError result
- Stdio server loop → JSON-RPC protocol: responses and RPC errors
- JSON-RPC protocol → stdout responses: serialize JSONL
- stdout responses → Local MCP client: protocol responses
- Python package → Module entry point: packages
- Handshake guide → MCP lifecycle: documents
- Wire conformance tests → JSON-RPC protocol: verifies
- Stdio session tests → Stdio server loop: verifies subprocess boundary