Content
## Project Introduction
MCP Client is a Node.js client implementation based on the Model Context Protocol (using Function Calling), which allows your application to connect to various MCP servers and interact with them through large language models (LLMs). MCP (Model Context Protocol) is an open protocol for standardizing how applications provide context to LLMs.
## Core Features
- Supports connecting to any MCP-compliant server
- Supports LLM capabilities compatible with OpenAI API format
- Automatic discovery and use of tools provided by the server
- Comprehensive logging system, including API requests and tool calls
- Interactive command-line interface
- Supports tool calls and result processing
## System Requirements
- Node.js 17 or higher
- LLM API key (Ollama is not supported yet)
- Disk space for storing log files (located in the `logs/` directory)
## Installation
### 1. Clone the Repository
```bash
git clone https://github.com/ConardLi/mcp-client-nodejs.git
cd mcp-client-nodejs
```
### 2. Install Dependencies
```bash
npm install
```
Required dependencies:
- @modelcontextprotocol/sdk
- openai
- dotenv
- typescript (development dependency)
- @types/node (development dependency)
### 3. Configure Environment Variables
Copy the example environment variable file and set your LLM API key:
```bash
cp .env.example .env
```
Then edit the `.env` file to fill in your LLM API key, model provider API address, and model name:
```
OPENAI_API_KEY=your_api_key_here
MODEL_NAME=xxx
BASE_URL=xxx
```
### 4. Build the Project
```bash
npm run build
```
## Usage
To start the MCP client, you can use the following methods:
### 1. Directly Specify the Server Script Path
```bash
node build/index.js <server script path>
```
Where `<server script path>` is the path to the MCP server script, which can be a JavaScript (.js) or Python (.py) file.
### 2. Use a Configuration File
```bash
node build/index.js <server identifier> <configuration file path>
```
Where `<server identifier>` is the server name defined in the configuration file, and `<configuration file path>` is the path to the JSON file containing the server definition.
```json
{
"mcpServers": {
"time": {
"command": "node",
"args": [
"/Users/xxx/mcp/dist/index.js"
],
"description": "Custom Node.js MCP server"
},
"mongodb": {
"command": "npx",
"args": [
"mcp-mongo-server",
"mongodb://localhost:27017/studentManagement?authSource=admin"
]
}
},
"defaultServer": "mongodb",
"system": "Custom system prompt"
}
```
### 3. Use npm Package (npx)
You can run the package directly through npx without cloning and building locally:
```bash
# Directly connect to the script
$ npx mcp-client-nodejs /path/to/mcp-server.js
# Connect through configuration file
$ npx mcp-client-nodejs mongodb ./mcp-servers.json
```
> Note: You need to configure model-related information in the `.env` file in the current running directory.
### Example
Directly connect to a JavaScript MCP server:
```bash
node build/index.js /path/to/weather-server/build/index.js
```
Directly connect to a Python MCP server:
```bash
node build/index.js /path/to/mcp-server.py
```
Connect to a server using a configuration file:
```bash
node build/index.js mongodb ./mcp-servers.json
```
Run using npx:
```bash
# Directly connect to the script
$ npx mcp-client-nodejs /path/to/mcp-server.js
# Connect through configuration file
$ npx mcp-client-nodejs mongodb./mcp-servers.json
```
## Working Principle
1. **Server Connection**: The client connects to the specified MCP server
2. **Tool Discovery**: Automatically obtain the list of available tools provided by the server
3. **Query Processing**:
- Send user queries to LLM
- LLM decides whether to use tools
- If needed, the client executes tool calls through the server
- Return tool results to LLM
- LLM provides the final response
4. **Interactive Loop**: Users can continuously input queries until they type "quit" to exit
## Logging System
MCP Client includes a comprehensive logging system that records all critical operations and communications in detail. Log files are saved in the `logs/` directory in JSON format for easy query and analysis.
### Log Types
- **LLM Requests and Responses** - Record all communications with the LLM API
- **Tool Calls and Results** - Record all tool call parameters and return results
- **Error Messages** - Record any errors during system operation
### Log Naming and Format
Log files are uniformly named as `[index] [log_type] YYYY-MM-DD HH:MM:SS.json`, including sequence number, log type, and timestamp, making it easy to view the entire session in chronological order.
## Architecture Design
MCP Client is based on a modular client-server architecture:
- **Transport Layer**: Use Stdio transport mechanism to communicate with the server
- **Protocol Layer**: Use MCP protocol to handle requests/responses and tool calls
- **Model Layer**: Provide LLM capabilities through OpenAI SDK
### Core Components
- **MCPClient Class**: Manage server connections, process queries, and tool calls
- **Client Object**: Client implementation provided by MCP SDK
- **StdioClientTransport**: Transport implementation based on standard input/output
## Best Practices
- **Error Handling**: Use TypeScript type system for better error detection
- **Security**: Store API keys securely in `.env` files
- **Tool Permissions**: Pay attention to tool permissions and security
## Troubleshooting
### Server Path Issues
- Ensure the server script path is correct
- If relative paths do not work, use absolute paths
- For Windows users, ensure to use forward slashes (/) or escaped backslashes (\) in paths
- Verify that server files have the correct extensions (.js or .py)
### Response Time
- The first response may take up to 30 seconds to return
- This is normal and occurs during server initialization, query processing, and tool execution
- Subsequent responses are usually faster
### Common Error Messages
- `Error: Cannot find module`: Check the build folder and ensure TypeScript compilation is successful
- `Connection refused`: Ensure the server is running and the path is correct
- `Tool execution failed`: Verify that environment variables required by the tool are set
- `OPENAI_API_KEY is not set`: Check your `.env` file and environment variables
- `TypeError`: Ensure to use the correct types for tool parameters
## License
Apache License 2.0
