carrot-mcp

# AGENTS.md

## Project Overview

Carrot MCP is a collection of MCP (Model Context Protocol) servers for hardware and data interfaces, structured as a UV workspace.

## Project Structure & Navigation

- `src/carrot_mcp/`: Root CLI entry point (`cli.py`) and agent config managers (`claude.py`, `mimocode.py`, `opencode.py`, `gemini.py`)
- `packages/carrot-mcp-<name>/`: Independent MCP servers (`io`, `pdf`, `office`, `nfc`, `sys`)
- `tests/<name>/`: Test suites matching each sub-package
- `tests/test_cli.py`, `tests/test_agents.py`: Root CLI and agent config test suites
- `tests/HIL/`: Hardware-in-the-loop tests and verification scripts
- **Tool Specs & Architecture**: Defined in each package's `packages/carrot-mcp-<name>/README.md` and `src/carrot_mcp_<name>/server.py`. Consult them on-demand via search/view tools.

## Build & Test Commands

```bash
# Dependencies & Testing
uv sync --all-packages
uv run pytest                          # Run all tests (unit tests)
uv run pytest tests/<name>/ -v          # Run specific package tests (e.g. tests/io/)
uv run pytest tests/test_cli.py -v     # Run root CLI tests

# Run MCP Servers
uv run carrot-mcp list                 # List available servers
uv run carrot-mcp run <server>         # Run via root CLI (pdf, office, io, nfc, sys)
uv run carrot-mcp-<name>               # Run via package script (e.g. carrot-mcp-pdf)
uv run python -m carrot_mcp_<name>     # Run package module directly
```

## Engineering Rules & Code Style

- **Python 3.10+** (except `carrot-mcp-nfc` which requires **Python 3.14+**), strict type hints.
- **FastMCP Pattern**: Each server uses FastMCP (`from fastmcp import FastMCP`) in `server.py` and implements a `version` tool.
- **Tool Return Convention**: All tools return a dict `{"status": "ok"|"error", ...}`, except tools returning images (which return `list[TextContent | ImageContent]`).
- **Version SSOT**: Versions are read dynamically from package metadata via `importlib.metadata.version("<package_name>")`. Never hardcode `__version__` in `__init__.py`.
- **CRITICAL Redline**: **`tests/` directories must NOT contain `__init__.py`** — doing so shadows pyserial's top-level `serial` package.
- **Documentation SSOT**: When modifying tools or signatures, update the corresponding `packages/carrot-mcp-<name>/README.md` and verify with `uv run pytest`.

## Adding a New MCP Server

1. Create `packages/carrot-mcp-<name>/`.
2. Add `pyproject.toml` with `fastmcp>=0.1.0`, scripts entry (`carrot-mcp-<name> = "carrot_mcp_<name>.server:main"`), and entry point:
   ```toml
   [project.entry-points."carrot_mcp.servers"]
   <name> = "carrot_mcp_<name>.server:mcp"
   ```
3. Implement FastMCP server in `src/carrot_mcp_<name>/server.py` with a `version` tool.
4. Add `src/carrot_mcp_<name>/__main__.py` for module execution (`python -m carrot_mcp_<name>`).
5. Add package to root `pyproject.toml` dependencies and `uv.sources`.
6. Add unit tests under `tests/<name>/` (ensure no `__init__.py`).

## Agent Config Management

CLI commands to manage external agent MCP configurations (`claude`, `mimocode`, `opencode`, `gemini`):

```bash
carrot-mcp list                         # List available servers
carrot-mcp run <server>                 # Run a specific MCP server
carrot-mcp mcp add [--uvx|--local]      # Register carrot servers with agents
carrot-mcp mcp remove [agent ...]       # Unregister carrot servers
```

- Auto-detects `--uvx` vs `--local` mode based on PATH if unspecified.
- Preserves existing environment configurations and non-managed / remote MCP servers (`type == "http"` or `"remote"`).
- Config backups are saved automatically under `%APPDATA%/carrot-mcp/agents/<agent>/` (Windows) or `~/.local/share/carrot-mcp/agents/<agent>/` (Linux/macOS).
- **Adding a new agent**: Implement `src/carrot_mcp/<agent>.py` (`is_available`, `add`, `remove`, `list_carrot`, `list_carrot_local`, `get_env`) and register under `[project.entry-points."carrot_mcp.agents"]`.