napthaai/automcp

<explanation>

1. Identify the project type and purpose

- automcp is an open‑source Python CLI tool and library whose purpose is to convert existing agent frameworks (CrewAI, LangGraph, Llama Index, OpenAI Agents SDK, Pydantic AI, mcp‑agent) into standardized MCP servers.

- It exposes a CLI (automcp init, automcp serve) to generate boilerplate, configure adapters, and launch MCP servers via STDIO or SSE transports.

2. Analyze the file structure

Top‑level directories/files:

• .github/workflows/: CI/CD for publishing

• automcp/: core Python package

– cli.py: entrypoint for commands

– cli_templates/: YAML and Python templates used by init

– adapters/: one module per supported framework + utility code

• examples/: demonstration projects, each using a different framework

• pyproject.toml, uv.lock, LICENSE, README.md: build, dependencies, license, doc

3. Examine the README for additional insights

- Describes project overview, supported frameworks, CLI usage, generated files (run_mcp.py), server transports, example workflows, deployment via Naptha MCPaaS.

- Shows how adapters integrate agent instances with FastMCP servers.

4. Main components and their relationships

A. CLI Layer

• automcp init -f <framework>

→ reads cli_templates, generates a run_mcp.py scaffold in the user’s project

• automcp serve -t <stdio|sse>

→ launches the scaffolded run_mcp.py or directly invokes FastMCP

B. Core Library

• automcp/cli.py: parses arguments, dispatches to init or serve

• automcp/cli_templates: boilerplate for new MCP servers

• automcp/adapters:

– Each adapter implements create_<framework>_adapter(...)

– Wraps a framework‑specific orchestrator/tool into a plain‑callable function taking a Pydantic InputSchema and returning a result

C. MCP Server

• run_mcp.py (generated):

– Imports FastMCP (mcp.server.fastmcp.FastMCP)

– Configures transport handlers (STDIO, SSE)

– Instantiates the adapter, adds it as a tool to the MCP instance

– Defines entrypoint functions serve_stdio() and serve_sse()

D. External Agent Frameworks

• CrewAI, LangGraph, etc. invoked through their Python SDKs/APIs inside adapters

• Consumers of automcp (example projects or end users) provide environment variables (API keys)

E. Clients and Deployment

• MCP clients (Cursor IDE, Claude Desktop) communicate via STDIO or SSE

• Naptha MCPaaS ▸ uses uv and pyproject.toml scripts to deploy to cloud

5. Architectural patterns and design principles

- Adapter Pattern: each framework support is isolated in its own module under automcp/adapters/.

- Template Generation: CLI‑driven code generation via Jinja‑style templates (cli_templates).

- Plugin‑like extensibility: new frameworks can be supported by adding new adapter modules and example directories.

- Separation of Concerns: CLI, templating, adapter logic, MCP server runtime are decoupled.

6. How to draw the system design diagram

a. Components (boxes):

– CLI Layer (left)

– Core automcp Library (templates & adapters)

– Generated MCP Server (run_mcp.py)

– FastMCP Server Runtime

– Framework Adapter Modules (crewAI, langgraph, llamaindex, openai, pydantic, mcp_agent)

– External Agent Frameworks & SDKs

– Clients (Cursor, Claude Desktop) / Naptha MCPaaS

b. Relationships (arrows):

1. User invokes CLI → CLI Layer

2. CLI Layer reads Templates → generates run_mcp.py

3. User edits run_mcp.py, then runs serve → FastMCP Runtime

4. FastMCP calls the adapter function → calls Framework SDK → obtains result

5. FastMCP returns result over STDIO/SSE → Client

c. Callouts for patterns:

– Adapter modules shield FastMCP from framework specifics

– Template folder governs code generation

d. Technologies & frameworks:

– Python 3, Pydantic, FastMCP, YAML (templates), Hatchling (build), UV (task runner), GitHub Actions

7. Guidelines for tailoring the diagram to this open‑source tool

- Highlight the CLI → Template → Generated Code flow as the core workflow

- Emphasize adapter extensibility points under automcp/adapters/

- Show how external agent frameworks plug into the adapters

- Include deployment integrations (UV, Naptha MCPaaS) as an optional extension

8. Diagram elements to include

- Clear labeled boxes for each component (CLI, Core, Adapters, FastMCP, Frameworks, Clients)

- Directional arrows with labels (e.g., “init → code generation”, “serve → transport”)

- Color coding:

• Blue for automcp internal components (CLI, core library)

• Green for generated server/runtime (run_mcp.py, FastMCP)

• Yellow for adapter modules

• Orange for external systems (agent frameworks, clients, MCPaaS)

By following this breakdown, the principal engineer can produce a detailed, accurate architecture diagram that clearly shows how automcp orchestrates template generation, adapter abstraction, MCP server runtime, and external integrations.

</explanation>