内容
# 简单的 MCP server，带有 AI Agent 工具
一个快速且轻量级的 **MCP server**，带有不同的 AI Agent 工具。它支持 STDIO (Claude Desktop) 和 SSE (远程 agents)。
## 目录
- [Prerequisites](#prerequisites)
- [Configuration](#configuration)
- [Run server in STDIO mode](#run-server-in-stdio-mode)
- [Run server in SSE mode](#run-server-in-sse-mode)
- [Configure Claude Desktop](#configure-claude-desktop)
- [Available tools](#available-tools)
- [Create new tool](#create-new-tool)
- [Debug in VSCode](#debug-in-vscode)
---
## Prerequisites
- Python >= 3.11
- uv 和 pip 已安装
[↑ index](#index)
---
## Configuration
初始化 **virtualenv** 并安装依赖：
```bash
uv venv
source .venv/bin/activate
uv sync
```
通过复制创建你的 ```.env``` 文件：
```bash
cp env.dist .env
```
然后，根据需要进行自定义。
[↑ index](#index)
---
## Run server in STDIO mode
首先，要测试服务器，安装并运行一个 MCP Inspector：
```bash
npx @modelcontextprotocol/inspector uv run python -m app.main
```
最后，一个 UI 将在你的浏览器中打开。通过单击左侧菜单上的 **Connect** 连接到服务器。
然后，从顶部栏中，单击 **Tools** 和 **List tools**。此时，你可以选择你喜欢的工具并使用它。
如果你想在没有 inspector 的情况下进行测试，只需使用以下命令启动：
```bash
uv run python -m app.main
```
[↑ index](#index)
---
## Run server in SSE mode
如果你想通过 **SSE** 从远程 agents 使用服务器，请使用以下命令启动它：
```bash
uv run python -m app.main --sse --port 8000
```
与 STDIO 模式一样，你可以使用 MCP Inspector (remote) 进行测试：
```bash
npx @modelcontextprotocol/inspector
```
如果你想模拟来自远程 agent 的工具调用，请在 python 中创建一个简单的 **STDIO client** (例如 `stdio_test.py`)，代码如下：
```python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def test():
server_params = StdioServerParameters(command="uv", args=["run", "python", "server.py"], cwd="./")
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Tools list
tools = await session.list_tools()
print("Tools:", [t.name for t in tools.tools])
# Call calculate
result = await session.call_tool("calculate", { "operation": "multiply", "a": 6, "b": 7 })
print("Result:", result.content)
asyncio.run(test())
```
然后运行：
```bash
python3 stdio_test.py
```
你将看到 **available tools list** 和 `calculate` 的结果。
[↑ index](#index)
---
## Configure Claude Desktop
如果你想在 **Claude Desktop** 上使用工具，请创建文件 `claude_desktop_config.json`，内容如下：
```json
{
"mcpServers": {
"mcp-server-tools": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-server", "python", "-m", "app.main"]
}
}
}
```
将此文件移动到：
- macOS: `~/Library/Application Support/Claude`
- Windows: `%APPDATA%\Claude`
[↑ index](#index)
---
## Available tools
| Tool | Descrizione |
| :--- | :--- |
| `calculate` | 数学运算（加、减、乘、除、幂） |
| `get_datetime` | 具有时区和可配置格式的日期/小时 |
| `process_text` | 文本处理程序（字数统计、提取电子邮件/URL、统计信息） |
| `fetch_url` | HTTP GET/HEAD 请求 |
| `convert_data` | JSON、Base64、Hex 转换 |
[↑ index](#index)
---
### Create new tool
要创建新工具，你需要：
- 创建一个新文件（例如 `app/tools/my_new_tool.py`）
- 编写你的逻辑，保持以下结构：
```python
from app.mcp import mcp
@mcp.tool()
def my_new_tool(your_param: str) -> dict[str, Any]:
"""
Clear and exaustive tool description.
Args:
your_param: clear and exaustive param description
Returns:
Clear and exaustive result description
"""
# YOUR LOGIC HERE
if some_error:
return {"success": False, "error": "Clear error description"}
return {
"success": True,
"your_resp": "...",
"other_resp": "...",
}
```
- 编辑 `app/tools/__init__.py` 文件并添加你的工具：
```python
from app.tools import my_new_tool
__all__ = [
"my_new_tool",
]
```
- 重启你的服务器
同样，如果你想**删除**现有工具，只需从 `__init__.py` 中删除它，然后删除相关的 `.py` 文件。
[↑ index](#index)
---
### Debug in VSCode
要调试你的 Python 微服务，你需要：
- 安装 **VSCode**
- 确保你已安装 **Python extension**
- 确保你已在 VSCode 上选择了带有 virtualenv 的**正确的解释器**
- 单击 **Run and Debug** 菜单并**创建一个 launch.json 文件**
- 从下拉列表中，选择 **Python debugger** 和 **FastAPI**
- 使用以下内容更改项目根目录中创建的 ```.vscode/launch.json```（如果已更改，请自定义主机和端口）：
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "MCP Server (SSE)",
"type": "debugpy",
"request": "launch",
"module": "app.main",
"args": [
"--sse",
"--port", "8000",
"--reload"
],
"envFile": "${workspaceFolder}/.env",
"console": "integratedTerminal",
"cwd": "${workspaceFolder}",
"justMyCode": true
},
{
"name": "MCP Server (STDIO)",
"type": "debugpy",
"request": "launch",
"module": "app.main",
"args": [
"--reload"
],
"envFile": "${workspaceFolder}/.env",
"console": "integratedTerminal",
"cwd": "${workspaceFolder}",
"justMyCode": true
}
]
}
```
- 在代码中放置一些断点，然后按**绿色播放按钮**
- 调用 API 进行调试
[↑ index](#index)
---
Made with ♥️ by Alessandro Orrù
