MCP模型上下文协议客户端开发教程 - 零基础入门指南

在人工智能快速发展的今天，大型语言模型（LLM）的应用场景不断拓展。为了让LLM更好地整合数据和工具，MCP（Model Context Protocol）应运而生。它就像AI领域的USB-C接口，为AI应用提供了标准化的连接方式。今天，我们将为大家带来一篇适合国内零基础小白学习的MCP客户端开发教程，帮助大家轻松上手MCP客户端开发。

一、准备工作

在开始之前，你需要确保系统满足以下要求：

操作系统：Mac或Windows计算机。
编程语言：安装最新版本的Python。
工具：安装最新版本的uv。

二、搭建环境

首先，我们需要创建一个新的Python项目并安装uv：

pip install uv

三、设置API密钥

你需要从Anthropic控制台获取一个API密钥。

创建一个.env文件来存储它：

touch .env

将你的密钥添加到.env文件中：

ANTHROPIC_API_KEY=your_api_key_here

将.env添加到你的.gitignore文件中，以避免将其提交到Git仓库：

.env

四、创建客户端

基本客户端结构

首先，我们设置导入并创建基本的客户端类：

import os
import asyncio
from typing import List, Optional
from dotenv import load_dotenv
from anthropic import ClaudeApi
from fastmcp import FastMCPClient


load_dotenv()


class MCPChatClient:
    def __init__(self):
        self.claude_api = ClaudeApi(api_key=os.getenv("ANTHROPIC_API_KEY"))
        self.mcp_client = FastMCPClient()
        self.session = None

服务器连接管理

接下来，我们实现连接到MCP服务器的方法：

    async def connect_to_server(self, server_path: str):
        """连接到MCP服务器"""
        await self.mcp_client.connect(server_path)
        self.session = await self.mcp_client.initialize_session()
        tools = await self.mcp_client.list_tools(self.session)
        print(f"Available tools: {tools}")

查询处理逻辑

现在，我们添加处理查询和处理工具调用的核心功能：

    async def process_query(self, query: str) -> str:
        """处理查询并调用工具"""
        # 获取可用工具
        tools = await self.mcp_client.list_tools(self.session)

        
        # 发送查询到Claude并获取响应
        response = await self.claude_api.send_query(query, tools)

        
        # 处理工具调用
        if response.requires_tool_call:
            tool_call_result = await self.mcp_client.call_tool(
                self.session,
                response.tool_to_call,
                response.tool_input
            )
            response = await self.claude_api.send_tool_result(
                response.conversation_id,
                tool_call_result
            )

        
        return response.content

交互式聊天界面

现在，我们添加聊天循环和清理功能：

    async def chat(self):
        """启动交互式聊天界面"""
        print("Starting chat with Claude...")
        print("Type 'exit' to end the chat.")

        
        while True:
            query = input("You: ")
            if query.lower() == 'exit':
                break

            
            response = await self.process_query(query)
            print(f"Claude: {response}")

        
        await self.mcp_client.close()

主入口点

最后，我们添加主执行逻辑：

async def main():
    client = MCPChatClient()

    
    server_path = input("Enter the path to your MCP server: ")
    await client.connect_to_server(server_path)

    
    await client.chat()


if __name__ == "__main__":
    asyncio.run(main())

五、关键组件解释

1. 客户端初始化

MCPChatClient类初始化会话管理和API客户端。
使用AsyncExitStack进行正确的资源管理。
配置Anthropic客户端以进行Claude交互。

2. 服务器连接

支持Python和Node.js服务器。
验证服务器脚本类型。
设置适当的通信渠道。
初始化会话并列出可用工具。

3. 查询处理

维护对话上下文。
处理Claude的响应和工具调用。
管理Claude和工具之间的消息流。
将结果整合成一个连贯的响应。

4. 交互界面

提供简单的命令行界面。
处理用户输入并显示响应。
包含基本的错误处理。
允许优雅地退出。

5. 资源管理

正确清理资源。
处理连接问题的错误。
优雅的关闭程序。

六、常见的自定义点

工具处理
- 修改process_query()以处理特定类型的工具。
- 为工具调用添加自定义错误处理。
- 实现特定工具的响应格式。
响应处理
- 自定义工具结果的格式。
- 添加响应过滤或转换。
- 实现自定义日志记录。
用户界面
- 添加图形用户界面或Web界面。
- 实现丰富的控制台输出。
- 添加命令历史或自动完成。

七、运行客户端

要运行你的客户端与任何MCP服务器：

确保你的服务器正在运行。
提供你的服务器脚本的路径。
启动客户端。

客户端将：

连接到指定的服务器。
列出可用工具。
启动交互式聊天会话，你可以：
- 输入查询。
- 查看工具执行情况。
- 获取Claude的响应。

八、工作原理

当你提交一个查询时：

客户端从服务器获取可用工具列表。
你的查询连同工具描述一起发送给Claude。
Claude决定使用哪些工具（如果有的话）。
客户端通过服务器执行任何请求的工具调用。
结果被发送回Claude。
Claude提供自然语言响应。
响应被显示给你。

九、最佳实践

错误处理
- 始终将工具调用包装在try-catch块中。
- 提供有意义的错误消息。
- 优雅地处理连接问题。
资源管理
- 使用AsyncExitStack进行正确的清理。
- 完成后关闭连接。
- 处理服务器断开连接的情况。
安全性
- 将API密钥安全地存储在.env中。
- 验证服务器响应。
- 谨慎处理工具权限。

十、故障排除

服务器路径问题

双重检查你的服务器脚本路径是否正确。
如果相对路径不起作用，使用绝对路径。
对于Windows用户，确保在路径中使用正斜杠（/）或转义的反斜杠（\）。
验证服务器文件具有正确的扩展名（.py用于Python，.js用于Node.js）。

响应时间

第一个响应可能需要长达30秒才能返回。
这是正常的，发生在以下情况：
- 服务器初始化时。
- Claude处理查询时。
- 工具正在执行时。
后续的响应通常更快。
在这个初始等待期间不要中断进程。

常见错误消息

如果你看到：

FileNotFoundError：检查你的服务器路径。
Connection refused：确保服务器正在运行且路径正确。
Tool execution failed：验证工具所需的环境变量是否已设置。
Timeout error：考虑在客户端配置中增加超时时间。

希望这篇教程能帮助你更好地理解和掌握MCP客户端开发。在编程狮（W3Cschool.cn）平台，你可以找到更多关于MCP开发的实例和教程，帮助你进一步提升开发技能。