Content
# MCP Chat Client
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
<p align="center">
<img src="https://amap.com/favicon.ico" alt="Gaode Map" width="80" height="80">
</p>
## Project Introduction
This is a chat client based on the Model Context Protocol (MCP), which implements natural language interaction with the Gaode Map service. By combining large language models with the MCP protocol, users can query geographic information, plan routes, and obtain weather data using natural language.
> **Key Features**: This project demonstrates how to integrate large language models with map services to achieve natural language interactive map functionality queries through the MCP protocol.
## Features
- **Intelligent Dialogue Interaction**: Integrate with the Qianwen large model using the Silicon-based Flow API to achieve natural language understanding.
- **Map Service Integration**: Supports various MCP tools from Amap, including:
- Location search and nearby queries
- Route planning for cycling, driving, public transport, and walking
- Weather information queries
- Geocoding and reverse geocoding
- **Real-time Communication**: Achieve real-time connection with Amap's MCP services through SSE (Server-Sent Events).
- **User-friendly Interface**: Provides a simple and intuitive web chat interface that supports multi-turn dialogue.
## Environment Requirements
- **Node.js**: >= 16.0.0
- **Package Manager**: npm
- **API Key**: A silicon-based flow API key is required
## Quick Start
### 1. Clone the Project
```bash
git clone https://github.com/Ceeon/mcp-chat-client.git
cd mcp-chat-client
```
### 2. Install Dependencies
```bash
npm install
```
### 3. Configure Environment Variables
Create a `.env` file and add the following configurations:
```env
SILICONFLOW_API_KEY=your SiliconFlow API key
AMAP_MCP_URL=Gaode Map MCP service URL
PORT=3000 # optional, defaults to 3000
```
### 4. Start the Service
Choose any of the following methods to start the service:
```bash
# Method 1: Using npm script
npm start
# Method 2: Run the server file directly
```bash
node server.js
```
### 5. Accessing the Application
After the service starts, open your browser and visit:
```
http://localhost:3000
```
## Project Structure
### Directory Structure
```
└── MCP Client
├── server.js # Main server file
├── mcp-chat-simple/ # Frontend file directory
│ ├── index.html # Main page
│ ├── app.js # Frontend logic
│ └── styles.css # Stylesheet
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── .env # Environment variables (to be created by yourself)
└── .env.example # Environment variable example
```
### Core File Description
#### Backend Files
- **server.js** ⭐⭐
- Main server file, built on Express
- Provides web services and API endpoints
- **Connects to Gaode Map MCP service and manages tool calls** ⭐⭐⭐
- **Integrates Siliconflow API for large model interactions** ⭐⭐⭐
- **siliconflow-client.ts** ⭐⭐
- TypeScript source file that defines the core logic of the client
- **Implements interactions with Siliconflow API and Gaode Map MCP service** ⭐⭐⭐
- Contains type definitions for tool calls and message handling
- **build/siliconflow-client.js**
- JavaScript file generated by TypeScript compilation
- Referenced by the server at runtime
#### Frontend Files
- **index.html**
- The HTML structure of the chat interface
- Defines the message container and input area
- **styles.css**
- Defines the styles for the chat interface
- Implements responsive design
- **app.js** ⭐⭐
- Frontend JavaScript code
- Handles user input and message display
- **Interacts with the backend API, sends queries, and processes responses** ⭐⭐
#### Configuration Files
- **package.json** - Project metadata, dependencies, and script definitions
- **tsconfig.json** - TypeScript compiler configuration
- **.env** - Environment variable configuration (to be created by yourself)
- **.env.example** - Example of environment variable configuration
## Core Technology Highlights
<div align="center">
<table>
<tr>
<th>Technical Highlights</th>
<th>Importance</th>
<th>Description</th>
</tr>
<tr>
<td><b>MCP Protocol Integration</b></td>
<td>⭐⭐⭐</td>
<td>
- Achieves seamless connection between large models and map services<br>
- Supports 12 geographic service tools provided by Amap<br>
- Real-time communication via SSE
</td>
</tr>
<tr>
<td><b>Large Language Model Application</b></td>
<td>⭐⭐⭐</td>
<td>
- Accesses Qianwen large model using silicon-based flow API<br>
- Intelligently parses user intent and selects appropriate tools<br>
- Processes tool invocation results and generates natural language responses
</td>
</tr>
<tr>
<td><b>Map Service Integration</b></td>
<td>⭐⭐</td>
<td>
- Supports functions such as location search, nearby queries, and route planning<br>
- Integrates cycling, driving, public transport, and walking route planning<br>
- Weather queries, geocoding, and reverse geocoding functionalities
</td>
</tr>
<tr>
<td><b>Frontend and Backend Separation Architecture</b></td>
<td>⭐</td>
<td>
- Express backend provides API services<br>
- Simple frontend interface for user interaction<br>
- RESTful API design promotes decoupling of frontend and backend
</td>
</tr>
</table>
</div>
## Development Guide
### Quick Start
This section provides key code examples and guidelines for project development, helping you quickly understand the core functionality implementation of the project.
### Backend Development
#### 1. MCP Client Initialization
```javascript
// Create MCP client
const mcpClient = new Client({
name: "mcp-chat-client",
version: "1.0.0"
});
// Initialize SSE transport and connect to Amap MCP service
const transport = new SSEClientTransport(new URL(AMAP_MCP_URL));
mcpClient.connect(transport);
// Get the list of available tools
const toolsResult = await mcpClient.listTools();
const availableTools = toolsResult.tools;
console.log(`Retrieved ${availableTools.length} available tools`);
```
#### 2. Integration of Large Models and Tool Calls
```javascript
// Prepare tool definitions for the large model
const toolDefinitions = availableTools.map(tool => ({
type: "function",
function: {
name: tool.name,
description: tool.description,
parameters: tool.inputSchema
}
}));
// Call the SiliconFlow API
const response = await axios.post(
SILICONFLOW_API_URL,
{
model: QWEN_MODEL,
messages: messages,
tools: toolDefinitions,
temperature: 0.7,
// Other parameters...
},
{
headers: {
'Authorization': `Bearer ${SILICONFLOW_API_KEY}`,
'Content-Type': 'application/json',
},
}
);
// If the model decides to call tools
if (responseMessage.tool_calls && responseMessage.tool_calls.length > 0) {
// Handle tool calls
for (const toolCall of responseMessage.tool_calls) {
const toolName = toolCall.function.name;
const toolArgs = JSON.parse(toolCall.function.arguments);
// Call MCP tool
const toolResult = await mcpClient.callTool({
name: toolName,
arguments: toolArgs
});
console.log(`Tool ${toolName} call result:`, toolResult);
}
}
```
#### 3. Message Processing Flow
```javascript
// Complete message processing flow
async function processQuery(message) {
// 1. Add user message to history
const messages = [...messageHistory, { role: 'user', content: message }];
// 2. Call the large model API
const initialResponse = await callLLMAPI(messages, availableTools);
// 3. If there are tool calls
if (initialResponse.tool_calls) {
// 3.1 Execute tool calls
const toolResults = await executeToolCalls(initialResponse.tool_calls);
// 3.2 Add tool results to message history
const messagesWithTools = addToolResultsToMessages(messages,
initialResponse.tool_calls,
toolResults);
// 3.3 Call the large model again to get the final response
const finalResponse = await callLLMAPI(messagesWithTools);
return finalResponse.content;
}
// 4. If there are no tool calls, return content directly
return initialResponse.content;
}
```
### Frontend Development
#### 1. Chat Interface Initialization
```javascript
// DOM element initialization
const chatMessages = document.getElementById('chatMessages');
const userInput = document.getElementById('userInput');
const sendButton = document.getElementById('sendButton');
// Initialization
document.addEventListener('DOMContentLoaded', () => {
// Add welcome message
addMessage('system', 'Welcome to the Gaode Map MCP Chat Assistant! You can ask questions about weather, route planning, location queries, and more.');
});
```
#### 2. User Interaction Handling
```javascript
// Handle user input
async function handleUserInput() {
const query = userInput.value.trim();
if (!query || isProcessing) return;
// Clear the input box and add user message
userInput.value = '';
addMessage('user', query);
messages.push({ role: 'user', content: query });
// Show loading indicator
addLoadingMessage();
isProcessing = true;
try {
// Call backend API
const response = await callBackendAPI(query);
removeLoadingMessage();
addMessage('assistant', response);
} catch (error) {
removeLoadingMessage();
addMessage('error', `An error occurred: ${error.message || 'Unknown error'}`);
console.error('Error processing query:', error);
} finally {
isProcessing = false;
}
}
```
#### 3. API Call
```javascript
// Call backend API
async function callBackendAPI(query) {
try {
// Send request
const response = await fetch(BACKEND_API_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ messages: messages })
});
// Error handling
if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.error || `Request failed: ${response.status}`);
}
// Handle response
const data = await response.json();
if (data.content) {
messages.push({ role: 'assistant', content: data.content });
return data.content;
} else {
throw new Error('Server response format error');
}
} catch (error) {
console.error('API call failed:', error);
throw error;
}
}
```
## Open Source License
This project is open-sourced under the [MIT License](https://opensource.org/licenses/MIT).
## Contribution Guidelines
We warmly welcome and appreciate all forms of contributions!
### How to Contribute
1. Fork this repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add some amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Create a Pull Request
### Types of Contributions
* Feature enhancements and new features
* Bug fixes and performance optimizations
* Documentation improvements
* Test cases
* Code quality improvements
## Notes and Best Practices
### Key Configuration
1. **API Key Management**
- Ensure that `SILICONFLOW_API_KEY` is correctly configured in the `.env` file
- Never hardcode API keys in the code
- Consider using environment variables or secure key management services in production
2. **MCP Connection Management**
- Implement a connection retry mechanism to handle network fluctuations
- Add connection status monitoring and health checks
- Provide graceful degradation handling in case of connection failures
### MCP Tool Invocation Notes
1. **Tool Name Format**
```javascript
// Example of Gaode Map MCP tool name format
const toolName = "mcp0_maps_text_search"; // Place search
const toolName = "mcp0_maps_direction_driving"; // Driving route planning
```
2. **Correct Tool Invocation Format**
```javascript
// ✅ Correct invocation method
const toolResult = await mcpClient.callTool({
name: toolName,
arguments: toolArgs
});
// ❌ Incorrect invocation method
// const toolResult = await mcpClient.callTool(toolName, toolArgs);
```
3. **Parameter Format Validation**
- Ensure parameters meet the tool's `inputSchema` requirements
- Validate the completeness of the tool definition before sending it to the large model
### Error Handling
```javascript
// Example of error handling for tool calls
try {
const toolResult = await mcpClient.callTool({
name: toolName,
arguments: toolArgs
});
return toolResult;
} catch (error) {
console.error(`Tool ${toolName} call failed:`, error);
// Return a friendly error message to the user
return { error: `Unable to complete the operation: ${error.message || 'Unknown error'}` };
}
```
## Frequently Asked Questions
<details>
<summary><b>Failed to connect to Gaode Map MCP Service</b></summary>
### Issue
Unable to connect to the Gaode Map MCP Server when starting the server.
### Solutions
1. Check if the network connection is stable.
2. Confirm whether the API Key in AMAP_MCP_URL is valid.
3. Check the detailed error messages in the server logs.
4. Try increasing the connection timeout or implementing a retry mechanism.
</details>
<details>
<summary><b>Large Model API Call Failed</b></summary>
### Issue
An error occurs when calling the Silicon-based Flow API.
### Solutions
1. Verify that SILICONFLOW_API_KEY is correctly configured and valid.
2. Check if the request format meets the API requirements.
3. Review the response status code and error message.
4. Confirm whether the API call limit has been exceeded.
</details>
<details>
<summary><b>Tool Call Returns Error</b></summary>
### Issue
An error is returned when calling the Gaode Map MCP tool.
### Solutions
1. Check if the tool name is correct (including the prefix `mcp0_`)
2. Verify that the parameter format meets the tool's `inputSchema` requirements
3. For geographic coordinate parameters, ensure the format is "longitude,latitude"
4. Check the detailed error messages in the server logs
</details>
<details>
<summary><b>Frontend interface cannot load</b></summary>
### Issue
The frontend interface cannot be loaded when accessing http://localhost:3000.
### Solutions
1. Confirm whether the server has started successfully and check if the port is occupied.
2. Verify that Express is correctly configured for static file serving.
3. Check the browser console for any error messages.
4. Try clearing the browser cache or using incognito mode.
