MCP 实战 04:把自己的工具接进 Cherry Studio

前面我们已经知道,MCP 能让 AI 调用工具。

这次直接动手:写一个查询工具,接进 Cherry Studio,让 AI 帮我们查项目缺陷。

不需要公司接口,也不需要数据库。先用几条虚构数据,把流程跑通。

一、先准备环境

电脑需要安装 Python 3.11 或更高版本,以及 Cherry Studio。

新建一个文件夹,命名为 mcp-demo。后面的两个代码文件,都放在里面。

Mac 在这个文件夹打开终端,执行:

bash 复制代码
python3 -m venv .venv
.venv/bin/python -m pip install mcp==2.3.0 pydantic==2.14.1

Windows 在文件夹打开 PowerShell,执行:

powershell 复制代码
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install mcp==2.3.0 pydantic==2.14.1

这里固定依赖版本,方便大家按同一份代码操作。

二、写一个能查缺陷的工具

新建 run.py,复制下面的完整代码:

python 复制代码
import json
import sys
from pathlib import Path
from typing import Annotated, Any, Literal

from pydantic import Field
from mcp.server import MCPServer

mcp = MCPServer("team-issues")

ROWS = [
    {"id": "DEMO-001", "title": "按钮重复响应", "status": "open"},
    {"id": "DEMO-002", "title": "报告标题异常", "status": "open"},
    {"id": "DEMO-003", "title": "空列表提示缺失", "status": "closed"},
    {"id": "DEMO-004", "title": "筛选条件未保留", "status": "open"},
]


@mcp.tool(description="查询虚构项目的缺陷,只读,不连接真实系统。")
def list_project_issues(
    project: Literal["demo-project"],
    status: Literal["open", "closed"] = "open",
    limit: Annotated[int, Field(strict=True, ge=1, le=20)] = 2,
) -> dict[str, Any]:
    matched = [row for row in ROWS if row["status"] == status]
    issues = matched[:limit]

    return {
        "source": "local-fixture",
        "project": project,
        "issues": issues,
        "returned_count": len(issues),
        "matched_total": len(matched),
        "has_more": len(issues) < len(matched),
    }


if __name__ == "__main__":
    if "--config" in sys.argv:
        print(json.dumps({
            "command": sys.executable,
            "args": [str(Path(__file__).resolve())],
            "env": {
                "PYTHONUTF8": "1",
                "PYTHONIOENCODING": "utf-8",
            },
        }, ensure_ascii=False, indent=2))
    else:
        mcp.run(transport="stdio")

这段代码做了三件事:

  • 准备四条演示缺陷。
  • 提供 list_project_issues 工具。
  • 允许按状态查询,并限制返回数量。

open 表示未关闭,closed 表示已关闭。

注意:这里的 has_more 只是提醒"还有记录没展示",这个小示例没有实现翻页。

三、先检查工具能不能调用

别急着接 AI,先确认工具本身没问题。

新建 check.py,和 run.py 放在同一个文件夹:

python 复制代码
import asyncio
import json
import sys
from pathlib import Path

from mcp import Client, StdioServerParameters


async def main():
    params = StdioServerParameters(
        command=sys.executable,
        args=[str(Path(__file__).with_name("run.py").resolve())],
        env={
            "PYTHONUTF8": "1",
            "PYTHONIOENCODING": "utf-8",
        },
    )

    async with Client(params) as client:
        tools = (await client.list_tools()).tools
        assert any(t.name == "list_project_issues" for t in tools)

        result = await client.call_tool("list_project_issues", {
            "project": "demo-project",
            "status": "open",
            "limit": 2,
        })

        assert not result.is_error
        data = result.structured_content

        assert data["source"] == "local-fixture"
        assert data["returned_count"] == 2
        assert data["matched_total"] == 3
        assert data["has_more"] is True
        assert [x["id"] for x in data["issues"]] == [
            "DEMO-001", "DEMO-002",
        ]

        print(json.dumps(data, ensure_ascii=False, indent=2))

    print("检查通过:服务可连接,工具能调用。")


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

Mac 执行:

bash 复制代码
.venv/bin/python check.py

Windows 执行:

powershell 复制代码
.\.venv\Scripts\python.exe check.py

正常情况下,会显示两条缺陷,并输出:

text 复制代码
检查通过:服务可连接,工具能调用。

这一步通过,说明本地 MCP 服务能连接、工具能调用。接下来再检查 AI 客户端。

四、生成自己电脑上的配置

Mac 执行:

bash 复制代码
.venv/bin/python run.py --config

Windows 执行:

powershell 复制代码
.\.venv\Scripts\python.exe run.py --config

终端会输出三个配置项:

配置项 含义
command 用哪个 Python 启动服务
args 要启动的 run.py 完整路径
env 中文编码设置

直接用自己电脑生成的内容,别照抄别人电脑上的路径。

移动项目文件夹或重建虚拟环境后,需要重新生成。

五、接进 Cherry Studio

在 Cherry Studio 的设置中,找到 MCP 服务器管理,添加本地服务。

按下面填写:

配置项 填写内容
名称 team-issues
类型 stdio,本地命令方式
命令 刚才输出的 command
参数 args 中的脚本完整路径
环境变量 env 中的两项编码设置

命令和参数要分开填。--config 只是用来查看配置,不要把它填进客户端的启动参数。

保存并启用,检查工具列表中有没有:

text 复制代码
list_project_issues

然后,在当前 Agent 的 MCP 设置中启用 team-issues。不同版本的入口文字可能有调整,重点是:服务添加后,还要给当前使用的 Agent 开启。

入口可参考 Cherry Studio 官方 MCP 指南。

六、让 AI 真正调用一次

选择支持工具调用的模型,新建对话,发送:

text 复制代码
请调用 list_project_issues 工具:

project 填 demo-project
status 填 open
limit 填 2

告诉我本次返回几条、总共有几条未关闭缺陷。
只根据工具结果回答,不要补充不存在的数据。

正常结果应该是:

text 复制代码
本次返回 2 条缺陷,共有 3 条未关闭缺陷。

DEMO-001:按钮重复响应
DEMO-002:报告标题异常

还有未展示的记录。

检查时,先看有没有实际的工具调用记录,再看回答内容。

模型只说一句"查询成功",不能证明它真的调用了工具。

七、卡住了,先检查这三处

**服务启动失败:**先运行 check.py,确认代码和依赖没有问题,再检查客户端中的路径。

**服务连接了,但 AI 不调用:**检查当前 Agent 是否启用了工具,以及所选模型是否支持工具调用。

**回答说总共只有两条:**让它区分 returned_count 和 matched_total。前者是本次返回数量,后者是符合条件的总量。

本文代码已在 Mac 上完成本地 stdio 调用检查。Windows 命令、Cherry Studio 界面操作和真实模型调用,仍需在你的电脑上验证。

相关推荐
莪_幻尘6 小时前
AI 编程的下一场战争,不在模型,在协议
agent·ai编程·mcp
我不会起名字3221 天前
Agent 总调错工具?MCP 接进 Go 后端的 4 个约束
后端·go·agent·mcp
vivo互联网技术1 天前
研发数字人 Agent:从 0 到 1 的架构与实践
人工智能·agent·mcp
Summer-Bright2 天前
企业落地智能体,供应链签名还是空白:1862 个 MCP 服务器无认证裸奔
服务器·人工智能·github·mcp
Flynt2 天前
不装SDK手写了一遍MCP:最新规范已经没有initialize握手了
agent·ai编程·mcp
Sakura_j_h_4 天前
MCP SDK 2.0 实战:用 MCPServer 搭本地笔记检索服务
开发语言·笔记·python·qt·ai工具·mcp·mcpserver
code2cat4 天前
【随笔】MCP长任务:查询已经返回,为什么任务还没有完成
javascript·人工智能·后端·mcp
装不满的克莱因瓶4 天前
【从零搭建】AI大模型之ReactAgent智能体对接MCP实战
java·人工智能·ai·springai·mcp·springaialibaba
xrlfreedom4 天前
MCP 面试高频考点:本地 AI 助手安全访问文件,Tools 与 Client 怎么协作?
tools·mcp·mcp client·python mcp sdk