# DG MCP Server

The MCP layer is a local stdio bridge around the existing DiffusionGemma agent
commands. It is meant for MCP-capable IDEs and OSS agents that can launch a
server process and call tools.

The default server uses the official `modelcontextprotocol/python-sdk`
`FastMCP` implementation. A dependency-free legacy JSON-RPC fallback is kept for
debugging.

Run it directly:

```bash
cd /root/diffusiongemma-agent
scripts/dg_agent.sh mcp --list-tools
scripts/dg_agent.sh mcp
scripts/dg_agent.sh mcp --legacy
```

Repo-local launchers are created by:

```bash
scripts/dg_agent.sh workspace-init --repo /path/to/repo
```

Then use:

```bash
/path/to/repo/.dg-agent/bin/mcp --list-tools
/path/to/repo/.dg-agent/bin/mcp
/path/to/repo/.dg-agent/bin/mcp-http --host 127.0.0.1 --port 8765
/path/to/repo/.dg-agent/bin/serena-mcp --help-local
/path/to/repo/.dg-agent/bin/opencode-mcp --help
/path/to/repo/.dg-agent/bin/opencode-acp --help
/path/to/repo/.dg-agent/bin/goose-mcp --help-local
/path/to/repo/.dg-agent/bin/goose-acp --help
/path/to/repo/.dg-agent/bin/goose-serve --help
```

The checked-in OpenCode MCP profile mounts `dg_agent` and `repomix`. Serena is
available as a separate IDE MCP entry because its Pyright startup exceeds
OpenCode's fixed connection timeout on this host.
The checked-in Goose MCP profile mounts `dg_agent` and `serena`.

Client config:

```text
configs/client_profiles/mcp-server.json
configs/client_profiles/mcp-client-snippets.json
configs/client_profiles/claude-code.mcp.json
configs/client_profiles/claude-desktop-mcp.json
configs/client_profiles/cursor.mcp.json
configs/client_profiles/vscode.mcp.json
```

Workspace copy:

```text
.dg-agent/mcp-server.json
.dg-agent/mcp-client-snippets.json
.dg-agent/claude-code.mcp.json
.dg-agent/claude-desktop-mcp.json
.dg-agent/cursor.mcp.json
.dg-agent/vscode.mcp.json
.dg-agent/goose-mcp.dg.yaml
```

Client targets:

```text
Claude Code project: .mcp.json <- .dg-agent/claude-code.mcp.json
Claude Desktop: claude_desktop_config.json <- .dg-agent/claude-desktop-mcp.json
Cursor project: .cursor/mcp.json <- .dg-agent/cursor.mcp.json
VS Code workspace: .vscode/mcp.json <- .dg-agent/vscode.mcp.json
```

`mcp-client-snippets.json` preserves all of those shapes in one manifest. The
Cursor/Claude-family configs use top-level `mcpServers`; VS Code uses top-level
`servers` with a `stdio` server type. The snippets also include optional native
Repomix MCP server entries through `scripts/run_repomix_mcp.sh` for clients
and Serena MCP server entries through `scripts/run_serena_mcp.sh` for clients
that should use upstream repository-packing and semantic/LSP tools directly
alongside the DG tools.

For clients that cannot launch a local stdio process, run the same DG MCP server
over the official SDK streamable HTTP transport:

```bash
scripts/dg_agent.sh mcp-http -- --host 127.0.0.1 --port 8765
```

Endpoint:

```text
http://127.0.0.1:8765/mcp
```

You can also merge the local server entry into a repo client config without
overwriting unrelated servers:

```bash
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client claude-code
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor --with-repomix
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor --with-serena
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor --with-repomix --with-serena
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor --with-oss-stack
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client vscode
scripts/dg_agent.sh mcp-client-config --client claude-desktop --target /path/to/claude_desktop_config.json
```

After `workspace-init`, the same command is available as:

```bash
.dg-agent/bin/mcp-client-config --client cursor
.dg-agent/bin/mcp-client-config --client cursor --with-repomix
.dg-agent/bin/mcp-client-config --client cursor --with-serena
.dg-agent/bin/mcp-client-config --client cursor --with-oss-stack
```

Serena is an upstream semantic/LSP MCP server. Install and smoke-test it with:

```bash
scripts/install_serena_local.sh
scripts/dg_agent.sh smoke --suite serena-mcp --timeout 300
```

On Windows, use `scripts/run_serena_mcp.sh` rather than a direct Serena binary.
The runner prefers a WSL bridge with local Linux Node/Pyright so semantic tools
avoid blocked Windows `.exe` shims and native `.pyd` wheels. The smoke includes
a live `get_symbols_overview` call, so it validates the Pyright-backed symbol
path as well as MCP startup.

Run it over stdio from a target repo:

```bash
.dg-agent/bin/serena-mcp
```

Or expose Serena over streamable HTTP when a client cannot spawn stdio:

```bash
.dg-agent/bin/serena-mcp --transport streamable-http --port 9121
```

For clients that read project instruction files, install matching DG/MCP usage
rules:

```bash
.dg-agent/bin/agent-rules --target all
```

Exposed tools:

- `dg_repo_status`: inspect `git status --short`, diff stat, and untracked files.
- `dg_list_files`: list repository files through `rg --files` with git fallback.
- `dg_code_outline`: bounded symbol outline with upstream ast-grep outline.
- `dg_search`: bounded ripgrep search with line and column locations.
- `dg_ast_grep`: bounded structural code search with upstream ast-grep.
- `dg_read_file`: bounded line-numbered file reads inside the repo.
- `dg_git_diff`: bounded git diff or diff stat reads.
- `dg_task_note`: save durable Markdown task notes under `runlogs/`.
- `dg_task_notes`: list or read saved task notes.
- `dg_status`: check backend, Aider proxy, and LiteLLM health.
- `dg_context`: build the bounded repo context pack for a task.
- `dg_rag_context`: retrieve compact read-only RAG context without calling the model.
- `dg_rag_answer`: ask the local model over compact retrieved repo context.
- `dg_repo_pack`: pack filtered repo content with upstream Repomix.
- `dg_repo_map`: build a bounded upstream Aider repo-map for codebase context.
- `dg_preflight`: check repo workspace, wrappers, services, and GPU readiness.
- `dg_plan`: generate a task-runner JSON plan from a natural-language task.
- `dg_task`: execute an existing task-runner plan; use `dry_run` for inspection.
- `dg_session`: run context -> plan -> task -> verify with rollback on failure.
- `dg_verify`: run or infer a repo verification command.
- `dg_capabilities`: read or run wrapper capability probes.
- `dg_client_smoke`: prepare or validate a target repo for external IDE/agent clients.
- `dg_client_report`: generate `.dg-agent/CLIENT_HANDOFF.md` and `.dg-agent/client-handoff.json`.
- `dg_sessions`: list recent artifacted DG agent sessions.
- `dg_session_artifact`: read a preserved session artifact, defaulting to latest.

Exposed resources:

- `dg://client-pack`: current endpoints, profiles, launchers, and limits.
- `dg://status`: live backend/proxy/LiteLLM health snapshot.
- `dg://usage`: short Markdown usage guide for local agent workflows.
- `dg://notes`: recent task notes saved by MCP clients.
- `dg://notes/latest`: latest task note.
- `dg://sessions`: recent session list.
- `dg://sessions/latest`: latest `session.json`.
- `dg://sessions/latest/diff`: latest `final.diff`.
- `dg://capabilities/latest`: latest saved capability report.
- `dg://client-handoff`: repo-local handoff JSON generated by `dg_client_report`.
- `dg://client-handoff/markdown`: repo-local handoff Markdown generated by `dg_client_report`.
- `dg://agent-hub`: repo-local agent hub JSON generated by `workspace-init`.
- `dg://agent-hub/markdown`: repo-local first-read agent hub Markdown.
- `dg://command-kit`: repo-local command kit JSON for reusable workflows.
- `dg://command-kit/markdown`: repo-local command kit Markdown.
- `dg://ide-clients`: repo-local IDE client snippet JSON.
- `dg://ide-clients/markdown`: repo-local IDE client profile guide.
- `dg://codex-profile`: repo-local Codex CLI profile guide.
- `dg://codex-profile/config`: repo-local Codex CLI config template.

Exposed prompts:

- `dg_agent_session`: guide an MCP client through context -> session -> verify.
- `dg_agent_context`: guide an MCP client to gather bounded repo context before editing.
- `dg_agent_continue_latest`: guide an MCP client to inspect latest artifacts before continuing.

The server runs over MCP stdio through the official Python SDK. It deliberately
maps tools to existing reliable wrapper commands instead of relying on raw
model-generated tool syntax. The smoke test uses the SDK client
`ClientSession` over `stdio_client`, so it checks real MCP compatibility rather
than only hand-written JSON.

For full IDE-agent use, start with the repo tools (`dg_repo_status`,
`dg_list_files`, `dg_repo_map`, `dg_code_outline`, `dg_search`, `dg_ast_grep`, `dg_read_file`, `dg_git_diff`), save handoff state
with `dg_task_note` when useful, then run `dg_preflight` and `dg_context`.
For external clients, call `dg_client_smoke` or `dg_client_report` first; the
latter writes and exposes the repo-local handoff through `dg://client-handoff`.
For first-time bootstrap, read `dg://agent-hub/markdown` and then the matching
command kit, IDE, or Codex resource instead of manually opening repo files.
For larger repository questions, use `dg_rag_context` before asking the model or
planning edits. Use `dg_repo_map` for an Aider-style repository sketch, then `dg_code_outline` when a symbol map is enough to choose files or functions before reading source. Use `dg_ast_grep` for language-aware code patterns such as
returns, decorators, call sites, and declarations. Use `dg_repo_pack` with tight include filters when a Repomix
packed artifact is better than ranked snippets. Use `dg_session` for one-shot bounded edits. Use `dg_plan` followed by
`dg_task` when the client should review or store the plan before executing it.

Verification:

```bash
scripts/dg_agent.sh smoke --suite mcp --timeout 120
scripts/dg_agent.sh smoke --suite goose-mcp --timeout 180
scripts/dg_agent.sh smoke --suite goose-acp --timeout 180
```