# syedzoherer/mcp-playground architecture

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

- Interactive diagram: https://gitdiagram.com/syedzoherer/mcp-playground
- Repository: https://github.com/syedzoherer/mcp-playground

## Overview

This repository demonstrates weather tools exposed over MCP, with interactive clients that let a language model select tools and return weather answers. The main documented path is a user query through the HTTP client, Claude, the HTTP MCP server, and the National Weather Service; a stdio server and Lambda/API Gateway deployment are alternate server paths. Bedrock model and agent clients are additional integrations. The graph reflects sampled source and README statements; some deployment details and unsampled modules are represented only where documented.

Main entry points: [`mcp-client-typescript/http-client.ts`](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/http-client.ts) (HTTP chat client), [`weather/src/index.ts`](https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/index.ts) (Stdio MCP server), [`mcp-client-typescript/api-gateway-client.ts`](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/api-gateway-client.ts) (Gateway chat client), [`mcp-client-typescript/index.ts`](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/index.ts) (TypeScript chat client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Interactive clients"]
  node_http_client["HTTP chat client<br/>[http-client.ts]"]
  node_gateway_client["Gateway chat client"]
  node_stdio_client["TypeScript chat client<br/>[index.ts]"]
  node_bedrock_client["Bedrock model client<br/>[index.ts]"]
  node_agent_client["Bedrock agent client<br/>[index.ts]"]
end

subgraph group_servers["MCP weather servers"]
  node_http_server["HTTP MCP server<br/>[http-server.ts]"]
  node_stdio_server["Stdio MCP server<br/>[index.ts]"]
end

subgraph group_weather["Weather data"]
  node_weather_tools["Forecast and alerts<br/>[http-server.ts]"]
  node_stdio_weather_tools["Forecast and alerts<br/>[index.ts]"]
  node_lambda_weather_tools["Forecast and alerts<br/>[lambda.ts]"]
end

subgraph group_deployment["Cloud deployment"]
  node_lambda_server["Lambda MCP handler<br/>[lambda.ts]"]
end

node_user(("Question asker"))
node_anthropic{{"Anthropic Claude"}}
node_bedrock_model{{"AWS Bedrock"}}
node_bedrock_agent{{"AWS Bedrock Agent"}}
node_nws{{"National Weather Service"}}
node_api_gateway{{"API Gateway"}}

node_user -->|"asks"| node_http_client
node_http_client -->|"sends query"| node_anthropic
node_anthropic -->|"selects tools"| node_http_client
node_http_client -->|"connects over HTTP"| node_http_server
node_http_client -->|"calls tool"| node_http_server
node_http_server -->|"registers tools"| node_weather_tools
node_weather_tools -->|"requests forecasts and alerts"| node_nws
node_user -->|"asks"| node_gateway_client
node_gateway_client -->|"sends query"| node_anthropic
node_gateway_client -.->|"targets deployment"| node_api_gateway
node_api_gateway -.->|"routes requests"| node_lambda_server
node_lambda_server -->|"registers tools"| node_lambda_weather_tools
node_lambda_weather_tools -->|"requests forecasts and alerts"| node_nws
node_user -->|"asks"| node_stdio_client
node_stdio_client -->|"sends query"| node_anthropic
node_stdio_client -.->|"connects over stdio"| node_stdio_server
node_stdio_server -->|"registers tools"| node_stdio_weather_tools
node_stdio_weather_tools -->|"requests forecasts and alerts"| node_nws
node_user -.->|"asks"| node_bedrock_client
node_bedrock_client -->|"invokes model"| node_bedrock_model
node_bedrock_client -.->|"calls MCP tools"| node_stdio_server
node_user -.->|"asks"| node_agent_client
node_agent_client -->|"invokes agent"| node_bedrock_agent
node_agent_client -.->|"calls MCP tools"| node_stdio_server

click node_http_client "https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/http-client.ts"
click node_gateway_client "https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/api-gateway-client.ts"
click node_stdio_client "https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/index.ts"
click node_bedrock_client "https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-bedrock/index.ts"
click node_agent_client "https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-bedrock-agent/index.ts"
click node_http_server "https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/http-server.ts"
click node_stdio_server "https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/index.ts"
click node_lambda_server "https://github.com/syedzoherer/mcp-playground/blob/main/weather-lambda/src/lambda.ts"
click node_weather_tools "https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/http-server.ts"
click node_stdio_weather_tools "https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/index.ts"
click node_lambda_weather_tools "https://github.com/syedzoherer/mcp-playground/blob/main/weather-lambda/src/lambda.ts"

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_http_client,node_gateway_client,node_stdio_client,node_bedrock_client,node_agent_client toneBlue
class node_http_server,node_stdio_server toneAmber
class node_weather_tools,node_stdio_weather_tools,node_lambda_weather_tools,node_api_gateway toneMint
class node_lambda_server toneRose
class node_user,node_anthropic,node_bedrock_model,node_bedrock_agent,node_nws toneIndigo
```

## Components

### Interactive clients

- [HTTP chat client](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/http-client.ts): `mcp-client-typescript/http-client.ts`
- [Gateway chat client](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/api-gateway-client.ts): `mcp-client-typescript/api-gateway-client.ts`
- [TypeScript chat client](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-typescript/index.ts): `mcp-client-typescript/index.ts`
- [Bedrock model client](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-bedrock/index.ts): `mcp-client-bedrock/index.ts`
- [Bedrock agent client](https://github.com/syedzoherer/mcp-playground/blob/main/mcp-client-bedrock-agent/index.ts): `mcp-client-bedrock-agent/index.ts`

### MCP weather servers

- [HTTP MCP server](https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/http-server.ts): `weather/src/http-server.ts`
- [Stdio MCP server](https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/index.ts): `weather/src/index.ts`

### Weather data

- [Forecast and alerts](https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/http-server.ts): `weather/src/http-server.ts`
- [Forecast and alerts](https://github.com/syedzoherer/mcp-playground/blob/main/weather/src/index.ts): `weather/src/index.ts`
- [Forecast and alerts](https://github.com/syedzoherer/mcp-playground/blob/main/weather-lambda/src/lambda.ts): `weather-lambda/src/lambda.ts`

### Cloud deployment

- [Lambda MCP handler](https://github.com/syedzoherer/mcp-playground/blob/main/weather-lambda/src/lambda.ts): `weather-lambda/src/lambda.ts`

### Other components

- **Question asker**
- **Anthropic Claude**
- **AWS Bedrock**
- **AWS Bedrock Agent**
- **National Weather Service**
- **API Gateway**

## Connections

- Question asker → HTTP chat client: asks (evidence: `README.md`)
- HTTP chat client → Anthropic Claude: sends query (evidence: `mcp-client-typescript/http-client.ts`)
- Anthropic Claude → HTTP chat client: selects tools (evidence: `mcp-client-typescript/http-client.ts`)
- HTTP chat client → HTTP MCP server: connects over HTTP (evidence: `mcp-client-typescript/http-client.ts`)
- HTTP chat client → HTTP MCP server: calls tool (evidence: `mcp-client-typescript/http-client.ts`)
- HTTP MCP server → Forecast and alerts: registers tools (evidence: `weather/src/http-server.ts`)
- Forecast and alerts → National Weather Service: requests forecasts and alerts (evidence: `weather/src/http-server.ts`)
- Question asker → Gateway chat client: asks (evidence: `mcp-client-typescript/api-gateway-client.ts`)
- Gateway chat client → Anthropic Claude: sends query (evidence: `mcp-client-typescript/api-gateway-client.ts`)
- Gateway chat client → API Gateway: targets deployment (evidence: `README.md`)
- API Gateway → Lambda MCP handler: routes requests (evidence: `README.md`)
- Lambda MCP handler → Forecast and alerts: registers tools (evidence: `weather-lambda/src/lambda.ts`)
- Forecast and alerts → National Weather Service: requests forecasts and alerts (evidence: `weather-lambda/src/lambda.ts`)
- Question asker → TypeScript chat client: asks (evidence: `mcp-client-typescript/index.ts`)
- TypeScript chat client → Anthropic Claude: sends query (evidence: `mcp-client-typescript/index.ts`)
- TypeScript chat client → Stdio MCP server: connects over stdio
- Stdio MCP server → Forecast and alerts: registers tools (evidence: `weather/src/index.ts`)
- Forecast and alerts → National Weather Service: requests forecasts and alerts (evidence: `weather/src/index.ts`)
- Question asker → Bedrock model client: asks
- Bedrock model client → AWS Bedrock: invokes model (evidence: `mcp-client-bedrock/index.ts`)
- Bedrock model client → Stdio MCP server: calls MCP tools
- Question asker → Bedrock agent client: asks
- Bedrock agent client → AWS Bedrock Agent: invokes agent (evidence: `mcp-client-bedrock-agent/index.ts`)
- Bedrock agent client → Stdio MCP server: calls MCP tools
