1  ### radicle-mcp — Agent & Contributor Guide (AGENTS.md)
  2  
  3  This document is for coding agents and human contributors working on this repository. It explains
  4  how to develop, extend, and test `radicle-mcp`, and serves as the authoritative reference for the
  5  server’s tools (names, arguments, result shapes).
  6  
  7  If you are looking for client/operator instructions to integrate an MCP client with `radicle-mcp`,
  8  see the project README. This file focuses on building and testing the server, not re‑explaining the
  9  MCP protocol.
 10  
 11  ______________________________________________________________________
 12  
 13  ### What this server does (brief)
 14  
 15  - Exposes an MCP server over stdio implemented with the official Rust SDK `rmcp`.
 16  - Operates against the Radicle project associated with the server process’s current working
 17    directory (CWD). It discovers the repository via the `rad` Git remote (`rad://<rid>`).
 18  - Provides tools to list issues, read comments, create issues, add comments, add labels, and edit
 19    issue status using the Radicle Rust library (not the CLI).
 20  
 21  Runtime assumptions:
 22  
 23  - Start the server from a Git repository that is also a Radicle project (has a `rad` remote pointing
 24    to `rad://<rid>`).
 25  - The process has access to a valid Radicle profile (key material) so it can sign operations when
 26    required (e.g., creating an issue, adding a comment/label).
 27  
 28  ______________________________________________________________________
 29  
 30  ### Developer quickstart
 31  
 32  Build with Cargo and run from a Radicle-enabled repository:
 33  
 34  ```
 35  cargo build
 36  cargo run --quiet [<path>]
 37  ```
 38  
 39  Wire protocol
 40  
 41  - This server speaks MCP over JSON‑RPC 2.0 using `rmcp`.
 42  - Discover server info/capabilities and tools via `initialize` and `tools/list`.
 43  - For protocol details, see the MCP spec and the `rmcp` crate documentation.
 44  
 45  References
 46  
 47  - MCP spec: https://modelcontextprotocol.io/
 48  - rmcp (Rust SDK): https://crates.io/crates/rmcp
 49  
 50  Server identity (as reported by `initialize`)
 51  
 52  - `serverInfo.name`: `radicle-mcp`
 53  - `serverInfo.version`: crate version
 54  - `protocolVersion`: `2024-11-05`
 55  
 56  ______________________________________________________________________
 57  
 58  ### Development workflow & tips
 59  
 60  - Handle JSON‑RPC errors. Notably, invalid inputs use `-32602` and will include a human-readable
 61    message.
 62  - The server works on a single repository determined at start. To act on a different project,
 63    restart the server with a different CWD.
 64  
 65  ### Testing and linting
 66  
 67  - Unit tests: `cargo test`
 68  - Lint (deny warnings): `cargo clippy -- -D warnings`
 69  - Format: `cargo fmt --all` (or `just format` if you use the provided justfile)
 70  
 71  ______________________________________________________________________
 72  
 73  ### Code structure & contribution conventions
 74  
 75  - Where tools live:
 76  
 77    - Tools are implemented with rmcp macros directly on the server in `src/rmcp_server.rs` using
 78      `#[tool_router]` and `#[tool]` methods.
 79    - Business logic helpers live under `src/tools/` as `run_*` functions that accept `&Profile`,
 80      `RepoId`, and typed arguments.
 81  
 82  - Adding a new tool (step-by-step):
 83  
 84    1. Implement or extend a helper in `src/tools/<name>.rs` (pure logic, testable).
 85    1. Add a `#[tool(name = "<name>")]` method on `RadicleServer` that:
 86       - Parses and validates `JsonObject` inputs, mapping missing/invalid fields to
 87         `ErrorData::invalid_params`.
 88       - Calls your helper, mapping failures to `ErrorData::internal_error` with a helpful message.
 89       - Returns `CallToolResult::success(vec![Content::json(&payload)?])` on success.
 90    1. Update the tool catalog in this file if argument/result shapes change.
 91  
 92  - Error semantics:
 93  
 94    - Use standard JSON-RPC codes where applicable:
 95      - `-32602` for invalid params
 96      - `-32601` for unknown tool (handled by rmcp routing)
 97      - Implementation/internal errors map to server errors with a clear message
 98  
 99  - Developer utilities:
100  
101    - Formatting: `just format` (runs cargo fmt, taplo, nixpkgs-fmt)
102    - Linting: `just lint` (Clippy, no warnings)
103    - Tests: `just test` (or `cargo test`)
104  
105  ______________________________________________________________________
106  
107  ### See also
108  
109  - `README.md` for client/operator quickstart and a minimal example.
110  - Radicle Rust crate documentation for underlying data types and operations.