ForgeMCP: Instructions file for Codex

ForgeMCP agent guide

Project

ForgeMCP is a Python MCP server for structured C and C++ development. The current codebase is a small foundation; do not recreate the deleted plugin/core framework.

Read first

Before designing or changing a module, read:

1. README.md
2. docs/architecture.md
3. The nearest tests and the C++ acceptance fixture documentation when relevant

Design rules

• Prefer direct code over framework-building. Add an abstraction only after at least two concrete callers need the same policy or lifecycle.
• Do not add callbacks, interfaces, or other abstractions solely for tests. Keep operation-specific orchestration at its call site.
• MCP-independent functions and structures are justified only by concrete inter-module interaction. Use the SDK directly for MCP-specific behavior.
• src/forgemcp/server.py is the composition root. It creates services, injects their dependencies, and registers their MCP surface.
• A service never constructs another service in its constructor. Dependencies are explicit constructor parameters and are wired in server.py.
• New feature code goes in src/forgemcp/<feature>/. Put business logic and the main service class in service.py, expected domain errors in errors.py, and tests in tests/<feature>/test_service.py.
• Extra files such as models.py, parsers, process runners, or kit discovery are allowed only when they represent a real responsibility that would otherwise make service.py harder to understand or test.
• Keep public result models beside the service until their number or reuse justifies models.py.
• Use WorkspacePath for paths shared between modules and in tool arguments/results. It serializes as project/..., storage/..., or root/<absolute-path>; native executable locations and low-level filesystem operations still use Path.
• Each feature module owns filesystem operations on its files. Do not read, write, create, move, or delete files through WorkspaceService methods from another module. Implement Workspace tool operations in their decorated MCP handlers; expose only the Workspace APIs other modules actually need for provider registration and result resources.
• Feature services launch external programs only through the injected ProcessService; do not call asyncio.create_subprocess_exec directly outside the process module.