
如何使用模型上下文协议构建自定义工具 原创
本文介绍如何构建模型上下文协议(MCP)服务器以扩展人工智能功能。创建可以无缝集成人工智能模型的工具,并通过arXiv论文搜索实现进行演示。
模型上下文协议(MCP)在人工智能开发领域变得越来越重要,它可以实现人工智能模型和外部工具之间的无缝集成。本指南将探讨如何创建MCP服务器,通过自定义工具实现增强人工智能功能。
什么是模型上下文协议?
模型上下文协议允许人工智能模型以标准化的方式与外部工具和服务进行交互。它使像Claude这样的人工智能助手能够执行自定义功能、处理数据并与外部服务交互,同时保持一致的界面。
MCP服务器开发入门
在开始创建MCP服务器时,需要对Python和异步编程有基本的了解。以下介绍设置和实现自定义MCP服务器的过程。
设置项目
创建MCP服务器最简单的方法是使用官方的MCP服务器创建工具。其中有两个选择:
1 # Using uvx (recommended)
2 uvx create-mcp-server
3
4 # Or using pip
5 pip install create-mcp-server
6 create-mcp-server
这将创建一个基本的项目结构:
Plain Text
1 my-server/
2 ├── README.md
3 ├── pyproject.toml
4 └── src/
5 └── my_server/
6 ├── __init__.py
7 ├── __main__.py
8 └── server.py
实施首个MCP服务器
首先创建一个实例:创建一个arXiv论文搜索工具,人工智能模型可以使用它来获取学术论文。以下是实现方法:
1 import asyncio
2 from mcp.server.models import InitializationOptions
3 import mcp.types as types
4 from mcp.server import NotificationOptions, Server
5 import mcp.server.stdio
6 import arxiv
7
8 server = Server("mcp-scholarly")
9 client = arxiv.Client()
10
11 @server.list_tools()
12 async def handle_list_tools() -> list[types.Tool]:
13 """
14 List available tools.
15 Each tool specifies its arguments using JSON Schema validation.
16 """
17 return [
18 types.Tool(
19 name="search-arxiv",
20 description="Search arxiv for articles related to the given keyword.",
21 inputSchema={
22 "type": "object",
23 "properties": {
24 "keyword": {"type": "string"},
25 },
26 "required": ["keyword"],
27 },
28 )
29 ]
30
31 @server.call_tool()
32 async def handle_call_tool(
33 name: str, arguments: dict | None
34 ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
35 """
36 Handle tool execution requests.
37 Tools can modify server state and notify clients of changes.
38 """
39 if name != "search-arxiv":
40 raise ValueError(f"Unknown tool: {name}")
41
42 if not arguments:
43 raise ValueError("Missing arguments")
44
45 keyword = arguments.get("keyword")
46 if not keyword:
47 raise ValueError("Missing keyword")
48
49 # Search arXiv papers
50 search = arxiv.Search(
51 query=keyword,
52 max_results=10,
53 sort_by=arxiv.SortCriterion.SubmittedDate
54 )
55 results = client.results(search)
56
57 # Format results
58 formatted_results = []
59 for result in results:
60 article_data = "\n".join([
61 f"Title: {result.title}",
62 f"Summary: {result.summary}",
63 f"Links: {'||'.join([link.href for link in result.links])}",
64 f"PDF URL: {result.pdf_url}",
65 ])
66 formatted_results.append(article_data)
67
68 return [
69 types.TextContent(
70 type="text",
71 text=f"Search articles for {keyword}:\n"
72 + "\n\n\n".join(formatted_results)
73 ),
74 ]
关键组件说明
- 服务器初始化。服务器使用标识MCP服务的唯一名称进行初始化。
- 工具登记。@server.list_tools()装饰器使用JSON Schema注册可用的工具及其规范。
- 工具实施。使用@server.call_tool()装饰器处理人工智能模型调用工具时的实际执行。
- 响应格式。工具返回结构化的响应,这些响应可以包括文本、图像或其他嵌入资源。
MCP服务器开发的最佳实践
- 输入验证。始终使用JSON模式彻底验证输入参数。
- 错误处理。实现全面的错误处理以提供有意义的反馈。
- 资源管理。正确管理外部资源和连接。
- 文档。提供对工具及其参数的清晰描述。
- 类型安全。使用Python的类型提示来确保整个代码的类型安全。
测试MCP服务器
测试MCP服务器有两种主要方法:
1.使用MCP检查器
对于开发和调试,MCP Inspector提供了一个测试服务器的友好界面:
lain Text
1 npx @modelcontextprotocol/inspector uv --directory /your/project/path run your-server-name
检查器将显示一个URL,可以在浏览器中访问该URL以开始调试。
2.与Claude Desktop集成
使用Claude Desktop测试MCP服务器:
(1)找到Claude Desktop配置文件:
MacOS:~/Library/Application Support/Claude/claude_desktop_config.json
Windows:%APPDATA%/Claude/claude_desktop_config.json
(2)添加MCP服务器配置:
1 {
2 "mcpServers": {
3 "mcp-scholarly": {
4 "command": "uv",
5 "args": [
6 "--directory",
7 "/path/to/your/mcp-scholarly",
8 "run",
9 "mcp-scholarly"
10 ]
11 }
12 }
13 }
对于已发布的服务器,可以使用更简单的配置:
1 {
2 "mcpServers": {
3 "mcp-scholarly": {
4 "command": "uvx",
5 "args": [
6 "mcp-scholarly"
7 ]
8 }
9 }
10 }
(3)启动Claude Desktop——现在应该可以在工具列表中看到工具(例如“search-arxiv”):
测试清单:
- 验证工具注册和发现
- 测试输入验证
- 检查错误处理
- 验证响应格式
- 确保适当的资源清理
与人工智能模型的集成
一旦MCP服务器准备就绪,它就可以与支持模型上下文协议的人工智能模型集成。该集成使人工智能模型能够:
- 通过list_tools端点发现可用工具
- 调用具有适当参数的特定工具
- 处理响应并将其融入其交互中
例如,当与Claude Desktop集成时,MCP工具会出现在“可用的MCP工具”列表中,从而在对话过程中可以直接访问这些工具。然后,人工智能可以利用这些工具来增强其能力——在arXiv示例中,Claude可以在讨论中实时搜索和引用学术论文。
常见挑战与解决方案
- 异步操作。确保正确处理异步操作以防止阻塞。
- 资源限制。实现适当的超时和资源限制。
- 错误恢复。设计健壮的错误恢复机制。
- 状态管理。在并发操作中谨慎处理服务器状态。
结论
构建MCP服务器为扩展人工智能功能提供了新的可能性。通过遵循本指南和最佳实践,可以创建与人工智能模型无缝集成的健壮工具。arXiv搜索实现的示例展示了如何创建实用且有用的工具来增强人工智能功能。
无论是构建研究工具、数据处理服务还是其他人工智能增强功能,模型上下文协议都提供了一种标准化的方式来扩展人工智能模型功能。用户可以构建自己的MCP服务器,并为不断增长的人工智能工具和服务生态系统做出贡献。
本文作者的官方MCP Scholarly服务器已被MCP存储库接受为社区服务器。可以在此处的社区部分找到它。
资源
- Model Context Protocol Documentation
- MCP Official Repository
- MCP Python SDK
- MCP Python Server Creator
- MCP Server Examples
- arXiv API Documentation
- Example arXiv Search MCP Server
为了更深入地了解MCP及其功能,可以浏览官方MCP文档,该文档提供了有关协议规范和实现细节的全面信息。
原文标题:Building Custom Tools With Model Context Protocol,作者:Aditya Karnam Gururaj Rao,Arjun Jaggi
