AgentForge MCP

A local MCP (Model Context Protocol) server that inspects and analyzes Agentic AI projects on your machine. It requires no external APIs, no API keys, no database, and no paid services — everything runs locally, offline, using Python's own file system and code-parsing capabilities.

Table of contents

• Why this was built

• Who it's for

• What it does

• How it works

• Tools, Resources, and Prompts provided

• Example output

• Project structure

• Requirements

• Running and testing it

• Connecting to Claude Desktop

• Design notes and limitations

Related MCP server: digital-rain-mcp

Why this was built

Understanding an unfamiliar agentic AI codebase — which agents it defines, what tools those agents can call, whether basics like a README, a dependency file, or tests exist — usually means opening files one by one. AgentForge automates that first pass of inspection.

It also exists as a small, complete, working reference implementation of an MCP server: one that actually uses all three MCP primitives (Tools, Resources, and Prompts) together, rather than only one of them.

Who it's for

• Developers who want a quick structural overview of an agentic AI project before reading through its code.

• Anyone learning MCP by working with a real, runnable example rather than isolated snippets.

What it does

AgentForge reads and analyzes the structure of a Python project. It never imports or executes any code belonging to the project it's inspecting — all analysis is done by reading file contents and parsing source code as text (via Python's built-in ast module for .py files). Given a folder path, it can:

• Report the project's file structure: total files, Python file count, key files present (README.md, requirements.txt, pyproject.toml, etc.), and which known agent framework (if any) it appears to use, based on simple text matching against import statements and dependency files.

• Detect functions and classes that look like agent "tools" — functions decorated with something tool-like (e.g. @tool), named *_tool / tool_*, or classes with "Tool" in the name.

• Detect classes that look like agent definitions — classes named *Agent* or inheriting from a base class with "Agent" in its name.

• Combine all of the above into one architecture report, plus a short list of best-practice warnings (e.g. no README found, no tests found, no tools detected).

A small sample project is bundled at example_agent_project/ so every tool, resource, and prompt can be tested immediately by passing the path "example", without needing a real project on hand first.

How it works, in simple terms

AgentForge is a normal Python program built on the fastmcp library. It exposes three kinds of capabilities over the MCP protocol:

• Tools — functions that take an input (a project path) and compute a fresh result on every call. An AI client can invoke these on its own, based on what the user asks in conversation.

• Resources — fixed content addressed by a URI (e.g. agentforge://architecture), with no input parameters. Clients typically require the user to attach these explicitly rather than fetching them automatically.

• Prompts — reusable instruction templates with named arguments (e.g. path, issue_description). A user selects a prompt and fills in its arguments; the template text becomes the starting instructions for the AI, directing it to call specific tools in a specific order.

An MCP client (such as Claude Desktop) starts server.py as a subprocess and communicates with it over standard input/output (the "stdio" transport) using JSON-RPC messages. When a tool is called, the client sends a message naming the tool and its arguments; the server runs the matching Python function and returns the result as plain text.

Internally, server.py only handles this MCP wiring. The actual logic lives in the agentforge/ package, split by responsibility:

• agentforge/utils.py — resolves the path argument (including the "example" shortcut) and walks the directory tree, skipping folders like .git, __pycache__, and venv.

• agentforge/scanner.py — implements the logic behind scan_project.

• agentforge/tool_lister.py — implements the logic behind list_agent_tools, using ast.parse() and ast.walk().

• agentforge/analyzer.py — implements the logic behind analyze_agent, combining the two above with its own agent-class detection and warning checks.

Because this logic doesn't depend on MCP at all, it's tested directly with pytest in tests/, with no MCP client or protocol involved.

Tools, Resources, and Prompts provided

Tools

All three accept the literal string "example" in place of a real path, which resolves to the bundled example_agent_project/ folder. Invalid paths return a readable error message rather than raising an exception to the client.

Resources

Prompts

Example output

Running scan_project("example") against the bundled sample project returns:

Project Scan: .../example_agent_project Total files: 11 Python files: 9 Other files: 2 Frameworks detected None detected (plain Python, or a framework not in our signature list) Key files found README.md requirements.txt File tree (11 entries shown) README.md agents/init.py agents/base.py agents/researcher_agent.py agents/writer_agent.py main.py requirements.txt tools/init.py tools/base.py tools/calculator_tool.py tools/search_tool.py

Running analyze_agent("example") additionally reports 3 agent classes found (Agent, ResearcherAgent, WriterAgent), 2 tools found (web_search, calculate_tool), and two warnings: no known framework detected, and no test files detected — both true, since the example project is intentionally minimal.

Project structure

agentforge-mcp/ ├── server.py # MCP server: registers all tools, resources, prompts ├── requirements.txt # fastmcp, pytest ├── pytest.ini # lets tests import agentforge/ from the project root ├── .gitignore ├── agentforge/ # Core logic — no MCP-specific code │ ├── init.py │ ├── utils.py # path resolution, safe directory walking │ ├── scanner.py # logic behind scan_project │ ├── tool_lister.py # logic behind list_agent_tools │ └── analyzer.py # logic behind analyze_agent ├── example_agent_project/ # Bundled sample project used for testing │ ├── README.md │ ├── requirements.txt │ ├── main.py │ ├── agents/ │ │ ├── base.py # fake Agent base class │ │ ├── researcher_agent.py # ResearcherAgent │ │ └── writer_agent.py # WriterAgent │ └── tools/ │ ├── base.py # fake @tool decorator │ ├── search_tool.py # web_search (fake, no network call) │ └── calculator_tool.py # calculate_tool (real, safe ast-based eval) ├── tests/ # pytest tests for agentforge/ core logic │ ├── test_scanner.py │ ├── test_tool_lister.py │ └── test_analyzer.py └── config/ └── claude_desktop_config.example.json

Requirements

• Python 3.10 or newer

• fastmcp>=2.3.0

• pytest>=7.4.0 (only needed to run the test suite)

Both dependencies are listed in requirements.txt.

Running and testing it

python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt

Run the automated test suite (tests the core logic in agentforge/ directly, no MCP client needed):

pytest -v

Run the server directly, as a sanity check. It will sit idle, since it's waiting for MCP protocol messages on stdin — this is expected. Press Ctrl+C to stop it:

python server.py

Connecting to Claude Desktop

Claude Desktop supports local MCP servers over the stdio transport. Add an entry to its configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentforge": {
      "command": "/ABSOLUTE/PATH/TO/agentforge-mcp/venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/agentforge-mcp/server.py"]
    }
  }
}

Replace the paths with the real absolute path to this project on your machine. On Windows, use venv\Scripts\python.exe and double backslashes in the JSON. Fully quit and reopen Claude Desktop for the change to take effect. A ready-to-edit copy of this config is included at config/claude_desktop_config.example.json.

Once connected, Tools can be invoked by describing what you want in a normal chat message. Resources and Prompts require using Claude Desktop's attachment/template UI (the + button next to the message box), since MCP clients require explicit user selection for those two primitive types rather than triggering them automatically.

Design notes and limitations

• Framework and tool detection are based on simple text/AST pattern matching, not a real import resolver — they can miss unusual patterns or, less commonly, produce false positives (e.g. a framework name mentioned only in a comment or docstring).

• No project code is ever executed; all analysis is static (file reading and ast parsing only), which makes it safe to point at any project.

• The bundled example_agent_project/ is intentionally minimal (no tests, no framework) so that analyze_agent's warnings can be demonstrated meaningfully on it.