# santaigh/mcpclient architecture

> Architecture diagram of the GitHub repository santaigh/mcpclient, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santaigh/mcpclient
- Repository: https://github.com/santaigh/mcpclient

## Overview

This is a Spring-based calculator chat client: a user submits arithmetic in the browser, the API hands the message to an agent, and the agent lets the language model choose among tools supplied by an MCP calculator server. The response includes both the model’s reply and a trace of tool calls for display. The graph includes the request, response, and tool-call records as a useful internal data layer. MCP and model connections are shown only where supported; provider configuration details were not sampled.

Main entry points: [`src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java`](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java) (MCP calculator agent), [`src/main/resources/static/js/chat.js`](https://github.com/santaigh/mcpclient/blob/main/src/main/resources/static/js/chat.js) (Chat interaction), [`src/main/java/com/calc/mcpclient/controller/ChatController.java`](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/controller/ChatController.java) (Chat endpoint), [`src/main/java/com/calc/mcpclient/dto/ChatResponse.java`](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ChatResponse.java) (Chat response)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser chat"]
  node_chat_page["Chat page<br/>[chat.html]"]
  node_chat_js["Chat interaction<br/>[chat.js]"]
end

subgraph group_api["Chat API"]
  node_controller["Chat endpoint"]
end

subgraph group_agent["Agent and tools"]
  node_agent["MCP calculator agent<br/>[McpCalcAgent.java]"]
  node_chat_config["Chat client setup"]
  node_recorder["Tool call recorder"]
  node_unavailable["Unavailable error"]
end

subgraph group_data["Chat records"]
  node_request["Chat request<br/>[ChatRequest.java]"]
  node_response["Chat response<br/>[ChatResponse.java]"]
  node_tool_call["Tool call record<br/>[ToolCall.java]"]
end

node_user(("User"))
node_mcp_server["MCP calculator server"]
node_model["Anthropic model"]

node_user -->|"uses"| node_chat_page
node_chat_page -->|"loads"| node_chat_js
node_chat_js -->|"posts message"| node_controller
node_controller -->|"accepts"| node_request
node_controller -->|"handles message"| node_agent
node_agent -->|"creates"| node_response
node_controller -->|"returns"| node_response
node_chat_js -->|"renders reply"| node_response
node_agent -.->|"uses client"| node_chat_config
node_agent -->|"lists tools"| node_mcp_server
node_agent -->|"wraps tools"| node_recorder
node_recorder -->|"delegates calls"| node_mcp_server
node_recorder -->|"records calls"| node_tool_call
node_response -->|"includes calls"| node_tool_call
node_chat_js -->|"shows trace"| node_tool_call
node_agent -.->|"invokes via client"| node_model
node_agent -->|"throws on failure"| node_unavailable

click node_chat_page "https://github.com/santaigh/mcpclient/blob/main/src/main/resources/static/chat.html"
click node_chat_js "https://github.com/santaigh/mcpclient/blob/main/src/main/resources/static/js/chat.js"
click node_controller "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/controller/ChatController.java"
click node_agent "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java"
click node_chat_config "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/ChatClientConfig.java"
click node_recorder "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/RecordingToolCallback.java"
click node_unavailable "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/CalculatorUnavailableException.java"
click node_request "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ChatRequest.java"
click node_response "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ChatResponse.java"
click node_tool_call "https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ToolCall.java"

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_chat_page,node_chat_js,node_user toneBlue
class node_controller toneAmber
class node_agent,node_chat_config,node_recorder,node_unavailable,node_mcp_server toneMint
class node_request,node_response,node_tool_call toneRose
class node_model toneIndigo
```

## Components

### Browser chat

- [Chat page](https://github.com/santaigh/mcpclient/blob/main/src/main/resources/static/chat.html): `src/main/resources/static/chat.html`
- [Chat interaction](https://github.com/santaigh/mcpclient/blob/main/src/main/resources/static/js/chat.js): `src/main/resources/static/js/chat.js`

### Chat API

- [Chat endpoint](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/controller/ChatController.java): `src/main/java/com/calc/mcpclient/controller/ChatController.java`

### Agent and tools

- [MCP calculator agent](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java): `src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java`
- [Chat client setup](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/ChatClientConfig.java): `src/main/java/com/calc/mcpclient/agent/ChatClientConfig.java`
- [Tool call recorder](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/RecordingToolCallback.java): `src/main/java/com/calc/mcpclient/agent/RecordingToolCallback.java`
- [Unavailable error](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/agent/CalculatorUnavailableException.java): `src/main/java/com/calc/mcpclient/agent/CalculatorUnavailableException.java`

### Chat records

- [Chat request](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ChatRequest.java): `src/main/java/com/calc/mcpclient/dto/ChatRequest.java`
- [Chat response](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ChatResponse.java): `src/main/java/com/calc/mcpclient/dto/ChatResponse.java`
- [Tool call record](https://github.com/santaigh/mcpclient/blob/main/src/main/java/com/calc/mcpclient/dto/ToolCall.java): `src/main/java/com/calc/mcpclient/dto/ToolCall.java`

### Other components

- **User**
- **MCP calculator server**
- **Anthropic model**

## Connections

- User → Chat page: uses
- Chat page → Chat interaction: loads
- Chat interaction → Chat endpoint: posts message (evidence: `src/main/resources/static/js/chat.js`)
- Chat endpoint → Chat request: accepts (evidence: `src/main/java/com/calc/mcpclient/controller/ChatController.java`)
- Chat endpoint → MCP calculator agent: handles message (evidence: `src/main/java/com/calc/mcpclient/controller/ChatController.java`)
- MCP calculator agent → Chat response: creates (evidence: `src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java`)
- Chat endpoint → Chat response: returns (evidence: `src/main/java/com/calc/mcpclient/controller/ChatController.java`)
- Chat interaction → Chat response: renders reply (evidence: `src/main/resources/static/js/chat.js`)
- MCP calculator agent → Chat client setup: uses client
- MCP calculator agent → MCP calculator server: lists tools (evidence: `src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java`)
- MCP calculator agent → Tool call recorder: wraps tools (evidence: `src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java`)
- Tool call recorder → MCP calculator server: delegates calls (evidence: `src/main/java/com/calc/mcpclient/agent/RecordingToolCallback.java`)
- Tool call recorder → Tool call record: records calls (evidence: `src/main/java/com/calc/mcpclient/agent/RecordingToolCallback.java`)
- Chat response → Tool call record: includes calls (evidence: `src/main/java/com/calc/mcpclient/dto/ChatResponse.java`)
- Chat interaction → Tool call record: shows trace (evidence: `src/main/resources/static/js/chat.js`)
- MCP calculator agent → Anthropic model: invokes via client
- MCP calculator agent → Unavailable error: throws on failure (evidence: `src/main/java/com/calc/mcpclient/agent/McpCalcAgent.java`)
