MCP Chat with Claude

A full-stack application demonstrating the integration of Model Context Protocol (MCP) with Anthropic's Claude LLM, providing an interactive chat interface that leverages MCP tools.

Project Overview

This project consists of three main components:

1. Multiple MCP Servers: Node.js servers implementing the Model Context Protocol that provide various specialized tools for the LLM to use.
2. Host App: An Express server that acts as the intermediary between the user, Claude AI, and the MCP servers.
3. Web Client: A browser-based chat interface that communicates with the Host App.

Features

• Interactive chat interface with Claude AI
• Two-panel UI showing conversation and tool execution details
• Dynamic tool discovery from multiple MCP servers
• Support for specialized tools with different parameters from each server
• Proper handling of Claude's tool use via MCP

Project Structure

├── client/                 # Host app & web client
│   ├── dist/               # Compiled TypeScript
│   ├── host-app.ts         # Host application server
│   ├── chat.js             # Frontend chat interface logic
│   ├── index.html          # Main web interface
│   ├── styles.css          # Styling for web interface
│   ├── package.json        # Client dependencies
│   └── mcp-client-example.ts # Example MCP client for testing
│
├── server/                 # MCP servers
│   ├── dist/               # Compiled TypeScript
│   ├── mcp-server-todoplan.ts # TodoPlan MCP server implementation
│   ├── mcp-server-project.ts  # Project MCP server implementation
│   └── package.json        # Server dependencies
│
├── .gitignore              # Git ignore file
└── README.md               # Project documentation

Prerequisites

• Node.js 17 or higher
• npm or yarn
• Anthropic API key

Installation

1. Clone the repository:

   git clone https://github.com/jiangyan/typescript-mcp-demo.git
   cd typescript-mcp-demo
   

2. Install dependencies for both client and server:

   cd server
   npm install
   cd ../client
   npm install
   

3. Create .env file in the client directory with your Anthropic API key:

   ANTHROPIC_API_KEY=your-api-key-here
   MCP_SERVER_TODOPLAN_URL=http://localhost:8000/sse
   MCP_SERVER_PROJECT_URL=http://localhost:8001/sse
   PORT=3000
   

4. Create .env file in the server directory:

   MCP_SERVER_TODOPLAN_PORT=8000
   MCP_SERVER_PROJECT_PORT=8001
   

Setup and Running

Step 1: Start the MCP servers

# Terminal 1: Start the TodoPlan MCP server
cd server
npm run build:todoplan
npm run start:todoplan

# Terminal 2: Start the Project MCP server
cd server
npm run build:project
npm run start:project

The TodoPlan MCP server will start on port 8000 and the Project MCP server will start on port 8001 by default.

Step 2: Start the host app (web server)

cd client
npm run build
npm start

The web server will start on port 3000 by default.

Step 3: Access the chat interface

Open your browser and navigate to:

http://localhost:3000

Available MCP Tools

The MCP servers provide the following tools that Claude can use:

1. todoplan-server_get-todo: Get a todo item for a specific category

   • Parameters:
     • category: String (e.g., "life", "work", "family", "friends")

2. todoplan-server_get-plan: Get the overall plan

   • Parameters: None

3. project-server_get-project-details: Get details for a specific project

   • Parameters:
     • project_name: String (e.g., "Earth", "Mars", "Jupiter", "Saturn")

Additional Example

The project includes a standalone MCP client example (mcp-client-example.ts) that demonstrates how to connect to the MCP server programmatically without the web interface.

To run this example:

cd client
npm run client

Development

MCP Server Development

To add a new tool to an MCP server:

1. Open the server file (e.g., server/mcp-server-todoplan.ts)
2. Add a new tool definition following the existing pattern:

   server.tool("tool-name",
     { param1: z.string() },
     async ({ param1 }) => {
       // Tool implementation
       return {
         content: [{ type: "text", text: "Result" }]
       };
     }
   );
   

3. Rebuild and restart the server

Host App Development

The host app consists of:

• Backend (host-app.ts): Express server that communicates with Claude and multiple MCP servers
• Frontend (chat.js, index.html, styles.css): Chat interface that communicates with the backend

Architecture

┌─────────────┐       ┌────────────────┐       ┌───────────────┐
│             │       │                │       │               │
│  Web UI     │◄─────►│  Host App      │◄─────►│  MCP Servers  │
│  (Browser)  │       │  (Express)     │       │  (Node.js)    │
│             │       │                │       │               │
└─────────────┘       └───────┬────────┘       └───────────────┘
                              │
                              ▼
                      ┌───────────────┐
                      │               │
                      │  Claude API   │
                      │  (Anthropic)  │
                      │               │
                      └───────────────┘

Multiple MCP Servers Implementation

This project implements a multi-server MCP architecture, allowing Claude to access tools from different specialized servers.

Server Configuration

The project includes two distinct MCP servers:

1. TodoPlan MCP Server (server/mcp-server-todoplan.ts): Provides tools for managing todos and plans

   • get-todo: Get a todo item for a specific category
   • get-plan: Get the overall plan

2. Project MCP Server (server/mcp-server-project.ts): Provides tools for accessing project information

   • get-project-details: Get details for a specific project

Host App Integration

The host app (client/host-app.ts) has been implemented to:

1. Connect to multiple MCP servers simultaneously
2. Prefix tool names with their server name using underscores to avoid conflicts (e.g., todoplan-server_get-todo)
3. Route tool calls to the appropriate server based on the prefix
4. Present a unified set of tools to the LLM

Example Queries

Try the following queries to test the integration of multiple servers:

• "Tell me about project Earth"
• "What's my todo for the work category?"
• "Find my todo in the work category and tell me what projects are related to it"
• "What's my plan?"

Troubleshooting

1. Connection issues: Ensure both MCP servers and the host app are running and check the console for error messages.

2. Tool not found: Make sure the MCP servers are running and the tool names match exactly.

3. API key errors: Verify your Anthropic API key is correctly set in the client's .env file.

4. Tool use errors: Check the response panel for detailed error information.

5. Invalid tool name format: Ensure tool names follow Anthropic's required format (alphanumeric characters, underscores, and hyphens only).

License

MIT

Acknowledgments

• Model Context Protocol
• Anthropic Claude API