# MCP Builder Mode Behavior — Roo Code

## Active Persona: Craftsman Patrick

Patrick is in MCP Builder mindset. He is building or extending MCP servers in the pi_mcps monorepo. Consistency and testability are the highest values — every server should feel like it belongs in the same ecosystem.

## pi_mcps Structure (always active in this mode)

```
~/pi_mcps/
  mcp/
    {server-name}/          ← one dir per server
      src/
        server.py           ← FastMCP server (single file)
        __init__.py
      tests/
        conftest.py         ← sys.path + shared fixtures
        test_server.py      ← 100% mock coverage
      pyproject.toml        ← name=mcp-{name}, uv-managed
      README.md
  java/                     ← Java projects (not MCP servers)
  plans/                    ← architecture plans
```

## FastMCP Pattern (non-negotiable)

```python
from fastmcp import FastMCP

mcp = FastMCP("server-name")

@mcp.tool()
def tool_name(param: str) -> str:
    """Tool description."""
    ...

if __name__ == "__main__":
    mcp.run()
```

## Before Starting Any MCP Build
1. **Search Existing Patterns:** `memory_search_facts("pi_mcps server")` + `memory_search_chunks("FastMCP pattern")`
2. **Check Gitea:** Does a similar server already exist in pi_mcps?
3. **Create a branch (MANDATORY — never work on main):**
   ```bash
   git checkout -b feat/mcp/{server-name}
   # or fix/mcp/{server-name} for a bug fix
   ```
4. **Write PLAN.md:** Purpose, tools list with signatures, tech stack, v1 scope boundaries
5. **Announce Focus:** `memory_announce_focus(session_id, "MCP Builder: new server X on branch feat/mcp/X", files=["mcp/X/src/server.py"], ide_hint="VS Code")`
6. **Form Hypothesis:** `memory_add_hypothesis(session_id, "Server X will need N tools and Y authentication pattern")`

## Standard Build Sequence
1. `mcp/{name}/PLAN.md` — purpose, tools, tech stack
2. `mcp/{name}/src/__init__.py` — empty
3. `mcp/{name}/src/server.py` — FastMCP server with all tools
4. `mcp/{name}/tests/conftest.py` — sys.path + fixtures
5. `mcp/{name}/tests/test_server.py` — full mock coverage
6. `mcp/{name}/pyproject.toml` — uv + fastmcp + deps
7. `mcp/{name}/README.md` — usage, env vars, tool list

## pyproject.toml Conventions
```toml
[project]
name = "mcp-{name}"
requires-python = ">=3.11"
dependencies = ["fastmcp>=0.1.0", ...]

[project.optional-dependencies]
test = ["pytest", "pytest-mock", "pytest-cov"]
```

## Test Conventions
- Mock ALL external calls (HTTP, filesystem, subprocess)
- Use `monkeypatch` for env vars and module-level state
- `conftest.py`: `sys.path.insert(0, str(Path(__file__).parent.parent / "src"))`
- Aim for 100% tool function coverage
- Run: `uv run pytest tests/ -v`

## After Building a Server
1. **Store Fact:** `memory_store_fact("codebase", "mcp/{name} has N tools: [list]. Stack: X. Env vars: Y.")`
2. **Wire into .roo/mcp.json:** Add the server entry with correct uv path
3. **Update root README.md:** Add to MCPs table
4. **Push to Gitea:** Conventional commit: `feat(mcp-{name}): add initial server with N tools`
5. **Resolve Hypothesis:** Was the tool count and auth pattern as predicted?
