# steosumit/multi-caller-mcp architecture

> Architecture diagram of the GitHub repository steosumit/multi-caller-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steosumit/multi-caller-mcp
- Repository: https://github.com/steosumit/multi-caller-mcp

## Overview

multi-caller-mcp is a local conversational agent with two MCP interaction modes: direct tool calling and TypeScript Code Mode. A user prompt is handled by the agent and local LLM; in Code Mode, the model submits one script, whose MCP calls are bridged through Python to configured stdio servers and whose logs become the tool result. Direct mode exposes MCP tools individually, while local calculator and Python tools are also available. The graph reflects the README workflow and sampled source; some internal wiring is documented rather than visible in the excerpts.

Main entry points: [`agent.py`](https://github.com/steosumit/multi-caller-mcp/blob/main/agent.py) (Agent CLI), [`codemode.py`](https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py) (Code executor), [`mcp_converter.py`](https://github.com/steosumit/multi-caller-mcp/blob/main/mcp_converter.py) (Stdio MCP clients), [`llm.py`](https://github.com/steosumit/multi-caller-mcp/blob/main/llm.py) (Chat model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent orchestration"]
  node_agent["Agent CLI<br/>[agent.py]"]
  node_llm["Chat model<br/>[llm.py]"]
end

subgraph group_mcp["MCP integration"]
  node_mcp_client["Stdio MCP clients<br/>[mcp_converter.py]"]
  node_mcp_tools["Direct tool adapter<br/>[mcp_converter.py]"]
end

subgraph group_code["Code Mode"]
  node_api_generator["TS API generation<br/>[codemode.py]"]
  node_executor["Code executor<br/>[codemode.py]"]
  node_runner["Bun harness<br/>[codemode_runner.ts]"]
  node_sandbox["Bun sandbox<br/>[codemode.py]"]
end

subgraph group_local["Local tools"]
  node_local_tools["Calculator and Python<br/>[sandbox.py]"]
end

node_user(("User"))
node_model_service(("OpenAI-compatible model"))
node_mcp_server(("MCP stdio server"))

node_user -->|"submits prompt"| node_agent
node_agent -->|"builds agent"| node_llm
node_llm -->|"sends requests"| node_model_service
node_agent -->|"starts servers"| node_mcp_client
node_mcp_client -->|"lists tools"| node_mcp_server
node_mcp_client -->|"calls tools"| node_mcp_server
node_agent -->|"loads direct tools"| node_mcp_tools
node_mcp_tools -->|"invokes client"| node_mcp_client
node_agent -->|"generates API"| node_api_generator
node_api_generator -->|"provides declarations"| node_executor
node_agent -->|"registers execution tool"| node_executor
node_executor -->|"launches harness"| node_runner
node_executor -->|"runs script in"| node_sandbox
node_runner -->|"emits call events"| node_executor
node_executor -->|"routes tool calls"| node_mcp_client
node_agent -->|"offers local tools"| node_local_tools
node_executor -->|"returns logs"| node_agent
node_llm -.->|"returns response"| node_agent

click node_agent "https://github.com/steosumit/multi-caller-mcp/blob/main/agent.py"
click node_llm "https://github.com/steosumit/multi-caller-mcp/blob/main/llm.py"
click node_mcp_client "https://github.com/steosumit/multi-caller-mcp/blob/main/mcp_converter.py"
click node_mcp_tools "https://github.com/steosumit/multi-caller-mcp/blob/main/mcp_converter.py"
click node_api_generator "https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py"
click node_executor "https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py"
click node_runner "https://github.com/steosumit/multi-caller-mcp/blob/main/codemode_runner.ts"
click node_sandbox "https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py"
click node_local_tools "https://github.com/steosumit/multi-caller-mcp/blob/main/sandbox.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_llm,node_user toneBlue
class node_mcp_client,node_mcp_tools toneAmber
class node_api_generator,node_executor,node_runner,node_sandbox,node_mcp_server toneMint
class node_local_tools toneRose
class node_model_service toneIndigo
```

## Components

### Agent orchestration

- [Agent CLI](https://github.com/steosumit/multi-caller-mcp/blob/main/agent.py): `agent.py`
- [Chat model](https://github.com/steosumit/multi-caller-mcp/blob/main/llm.py): `llm.py`

### MCP integration

- [Stdio MCP clients](https://github.com/steosumit/multi-caller-mcp/blob/main/mcp_converter.py): `mcp_converter.py`
- [Direct tool adapter](https://github.com/steosumit/multi-caller-mcp/blob/main/mcp_converter.py): `mcp_converter.py`

### Code Mode

- [TS API generation](https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py): `codemode.py`
- [Code executor](https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py): `codemode.py`
- [Bun harness](https://github.com/steosumit/multi-caller-mcp/blob/main/codemode_runner.ts): `codemode_runner.ts`
- [Bun sandbox](https://github.com/steosumit/multi-caller-mcp/blob/main/codemode.py): `codemode.py`

### Local tools

- [Calculator and Python](https://github.com/steosumit/multi-caller-mcp/blob/main/sandbox.py): `sandbox.py`

### Other components

- **User**
- **OpenAI-compatible model**
- **MCP stdio server**

## Connections

- User → Agent CLI: submits prompt (evidence: `README.md`)
- Agent CLI → Chat model: builds agent (evidence: `agent.py`)
- Chat model → OpenAI-compatible model: sends requests (evidence: `llm.py`)
- Agent CLI → Stdio MCP clients: starts servers (evidence: `agent.py`)
- Stdio MCP clients → MCP stdio server: lists tools (evidence: `mcp_converter.py`)
- Stdio MCP clients → MCP stdio server: calls tools (evidence: `mcp_converter.py`)
- Agent CLI → Direct tool adapter: loads direct tools (evidence: `agent.py`)
- Direct tool adapter → Stdio MCP clients: invokes client (evidence: `mcp_converter.py`)
- Agent CLI → TS API generation: generates API (evidence: `README.md`)
- TS API generation → Code executor: provides declarations (evidence: `README.md`)
- Agent CLI → Code executor: registers execution tool (evidence: `agent.py`)
- Code executor → Bun harness: launches harness (evidence: `README.md`)
- Code executor → Bun sandbox: runs script in (evidence: `README.md`)
- Bun harness → Code executor: emits call events (evidence: `codemode_runner.ts`)
- Code executor → Stdio MCP clients: routes tool calls (evidence: `README.md`)
- Agent CLI → Calculator and Python: offers local tools (evidence: `agent.py`)
- Code executor → Agent CLI: returns logs (evidence: `README.md`)
- Chat model → Agent CLI: returns response (evidence: `agent.py`)
