forge-mcp

Read-only MCP server that gives Claude Code structured knowledge about the Forge repository, including its templates, project structure, documentation, validation rules, doctor checks, and generated-project conventions.

Forge remains the authoritative application. forge-mcp reads Forge; it does not modify it.

v0.1.1 has no write tools.

Tools

Tool	Purpose
get_forge_overview	Forge version, CLI entry point, capabilities, templates, doc availability
list_templates	Available local templates with metadata
get_template_summary	One template: purpose, language, files, variables, output structure
list_template_files	Sorted file listing for one template
read_template_file	Read a text file inside a template
get_project_structure	Generated-project conventions per template type
get_validation_commands	Validation commands as inert strings (never executed)
read_forge_document	Read approved Forge docs by stable identifier
explain_forge_doctor	Doctor checks, required/optional, overall success rule
get_template_change_checklist	Source-backed process for changing a Forge template

Requirements

• Python 3.10+
• Forge repository at a known path
• FORGE_REPOSITORY_ROOT environment variable or --forge-root CLI argument

Installation

cd forge-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Usage

# Set the Forge root and run the server over stdio
FORGE_REPOSITORY_ROOT=/srv/workspaces/projects/portfolio/forge forge-mcp

# Or pass it explicitly
forge-mcp --forge-root /srv/workspaces/projects/portfolio/forge

# Version check
forge-mcp --version
python -m forge_mcp --version

Claude Code setup

See docs/claude-code-setup.md and examples/claude-code.mcp.json.

Development

python -m pytest -q
python -m ruff check src/ tests/

Document availability

get_forge_overview distinguishes between documents that are approved in the allowlist and documents that are currently present on disk:

• available_documents — approved identifiers whose files exist in the Forge repository right now
• unavailable_documents — approved identifiers configured in the allowlist but whose files are absent

Both fields are always present. Both are sorted alphabetically by identifier. The union of the two sets always equals the full approved-document allowlist.

read_forge_document accepts only approved identifiers. It returns a structured error with code DOCUMENT_NOT_FOUND when the identifier is unknown or the file is absent, and DOCUMENT_ERROR for other read failures (binary content, size limit, encoding). It never accepts arbitrary paths.

Security

forge-mcp is strictly read-only. See docs/security-boundary.md.

Separation

Forge is a separate repository and application. forge-mcp does not modify Forge. forge-mcp does not import Forge modules, execute Forge commands, or touch Forge's Git history.