mcp-client-demo

# MCP Client Node.js client implementation based on Model Context Protocol (MCP) ## Project Introduction MCP Client is a Node.js client implementation based on the Model Context Protocol, allowing your application to connect to various MCP servers and interact with these servers through large language models (LLM). MCP (Model Context Protocol) is an open protocol designed to standardize the way applications provide context to LLMs. ## Core Features - Supports connection to any server compliant with the MCP standard - Provides LLM capabilities using the OpenAI API - Automatically discovers and utilizes tools provided by the server - Interactive command-line interface - Supports tool invocation and result handling ## System Requirements - Node.js version 17 or higher - Latest version of npm - OpenAI API key ## Installation ### 1. Clone the Repository ```bash git clone https://github.com/yourusername/mcp-client.git cd mcp-client ``` ### 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 OpenAI API key: ```bash cp .env.example .env ``` Then edit the `.env` file to include your OpenAI API key: ``` OPENAI_API_KEY=your_api_key_here ``` ### 4. Build the Project ```bash npm run build ``` ## Usage To start the MCP client, use the following command: ```bash node build/index.js <server_script_path> ``` Where `<server_script_path>` refers to the path of the MCP server script, which can be a JavaScript (.js) or Python (.py) file. ### Example Connect to a JavaScript MCP server: ```bash node build/index.js /path/to/weather-server/build/index.js ``` Connect to a Python MCP server: ```bash node build/index.js /path/to/mcp-server.py ``` ## How It Works 1. **Server Connection**: The client connects to the specified MCP server. 2. **Tool Discovery**: Automatically retrieves the list of available tools provided by the server. 3. **Query Handling**: - Sends user queries to OpenAI. - OpenAI decides whether tool invocation is necessary. - If needed, the client executes tool calls through the server. - Returns tool results to OpenAI. - OpenAI provides the final response. 4. **Interactive Loop**: Users can continuously input queries until they type "quit" to exit. ## Architectural Design MCP Client is based on a client-server architecture: - **Transport Layer**: Communicates with the server using Stdio transport mechanism. - **Protocol Layer**: Handles request/response and tool invocation using the MCP protocol. - **Model Layer**: Provides LLM capabilities through the OpenAI API. ### Core Components - **MCPClient Class**: Manages server connections, query handling, and tool invocation. - **Client Object**: Client implementation provided by the MCP SDK. - **StdioClientTransport**: Transport implementation based on standard input/output. ## Best Practices - **Error Handling**: Utilize TypeScript's type system for better error detection. - **Security**: Safely store API keys in the .env file. - **Tool Permissions**: Be mindful of tool permissions and security. ## Troubleshooting ### Server Path Issues - Ensure the server script path is correct. - If relative paths do not work, use absolute paths. - Windows users should ensure to use forward slashes (/) or escaped backslashes (\\) in paths. - Verify that the server file has the correct extension (.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 compiled successfully. - `Connection refused`: Ensure the server is running and the path is correct. - `Tool execution failed`: Verify that the required environment variables for the tool are set. - `OPENAI_API_KEY is not set`: Check your .env file and environment variables. - `TypeError`: Ensure the correct types are used for tool parameters. ## License MIT ## Contributing Contributions are welcome! Please submit Issues and Pull Requests!