想让 AI 查询设备台账，不一定要一开始就连接企业数据库。可以先用三条虚构记录，做一个只能搜索和读取详情的本地 MCP 服务器，再让宿主通过工具获得可核验的信息。

MCP Builder 是帮助你设计和开发服务器的 Skill，不是装上就自动出现所有业务接口的插件。 本文按固定来源包梳理安装、任务说明、示例实现和验收。示例代码做了本地语法检查；未安装 MCP SDK、未启动协议服务，也未声称在真实宿主连接成功。

一、这个 Skill 解决什么问题

官方 mcp-builder 指南覆盖需求研究、工具设计、实现、测试和评测。它帮助编程助手判断工具叫什么、参数怎么约束、结果怎么返回、失败时如何说明，而不是替你决定所有业务权限。

适合已有基础编程能力、使用支持自定义 Skill 和文件操作宿主的读者。没有开发经验时，可以先让助手产出接口说明和测试清单，理解后再实施；不要一上来要求它接入真实客户系统。

本次练习交付三个文件：requirements.md 记录边界，server.py 保存本地服务，acceptance.md 保存测试用例和实际结果。数据全部写在示例字典中，不读取磁盘目录，不访问网络，不提供删除或修改接口。

二、核对来源、目录与许可

下载区的来源包取自 anthropics/skills 仓库下的 skills/mcp-builder，固定提交为 2c5958ecac7cee2b583967a2c4981d0f4a75c579。页面版本使用 commit 标识，不把固定提交称为最新版本。

解压后应能看到：

mcp-builder/
  SKILL.md
  LICENSE.txt
  SOURCE-README.md
  README-中文说明.md
  reference/
  scripts/

reference 包含开发与评测说明，scripts 包含评测辅助程序。包内保留 Apache-2.0 许可证及原始文件；中文说明是额外附带的阅读提示。这个包没有打包 Python、MCP SDK 或宿主应用，不是双击执行的安装器。

先阅读 SKILL.md 和许可，再按所用宿主的官方方式导入或放置 Skill。不同产品目录不同，不能假设一个路径适用于 Claude、Codex 和所有 IDE。确认宿主能看到名称 mcp-builder，并能读取 reference 中的相对文件；只复制一个 Markdown 会丢掉配套材料。

三、先处理 SDK 大版本差异

Skill 来源版本与生成项目的依赖版本是两件事。 此固定包的 Python 参考使用 FastMCP 旧接口，而官方 Python SDK 当前主线已使用 MCPServer，要求 Python 3.11 及以上。本文实现按当前 2.x 接口编写，不把旧参考中的导入语句直接拼进新项目。

如果已有项目固定在 1.x，应使用对应维护分支文档，并单独规划迁移。新练习可以新建空目录，使用 Python 3.11 或更新且兼容的版本，在 Windows PowerShell 逐行执行：

mkdir asset-mcp-lab
cd asset-mcp-lab
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "mcp[cli]>=2,<3"
.\.venv\Scripts\python.exe -m pip show mcp

py -3.11 的前提是本机已安装对应解释器。若提示找不到版本，先安装官方兼容 Python 或改用已确认的解释器路径。核对 pip show 的版本和安装位置后，把完整依赖记录到项目里；不要让系统 Python 与虚拟环境混用。本文未执行上述安装命令，实际安装结果由读者环境决定。

Skill设计本地服务器和宿主连接是三个独立步骤的示意

四、给 Skill 一份有边界的任务

让编程宿主加载这个 Skill，然后输入下面的原创任务说明，并保存到 requirements.md：

使用 mcp-builder 设计本地只读设备台账 MCP。
按当前官方 Python SDK 2.x 文档实现，先说明与包内旧参考的差异。
只使用三条虚构设备记录，不能读取本机其他文件或连接网络。
提供 asset_search 和 asset_get 两个工具。
搜索只匹配设备名，不把“会议室”匹配成所有设备。
空关键词、未知编号要返回明确的可处理错误。
输出编号、名称和位置，不推断库存、负责人或维修状态。
先列计划和验收用例，再写代码；不要替我安装或自动连接真实系统。

检查计划有没有擅自加入数据库密码、云部署或文件扫描。这些都不在练习范围内。Skill 负责帮助组织开发，不能凭一句“只读”就证明生成代码确实没有副作用，需要人工查看实现。

五、建立最小服务器文件

下面是独立编写的教学实现。把它保存为 server.py，不要把说明文字和代码围栏一起复制进去。

from mcp.server import MCPServer

mcp = MCPServer("asset_catalog")
ASSETS = {
    "A01": {"name": "投影仪", "location": "一号会议室"},
    "A02": {"name": "显示器", "location": "工位区"},
    "A03": {"name": "无线话筒", "location": "培训室"},
}

@mcp.tool()
def asset_search(query: str) -> list[dict[str, str]]:
    """仅按设备名子串搜索虚构台账，返回编号、名称与位置。"""
    keyword = query.strip()
    if not keyword or len(keyword) > 40:
        raise ValueError("关键词需为1至40个字符，请输入设备名")
    return [
        {"id": key, **item}
        for key, item in ASSETS.items()
        if keyword in item["name"]
    ]

@mcp.tool()
def asset_get(asset_id: str) -> dict[str, str]:
    """按A01等精确编号读取虚构设备；未知编号报错。"""
    key = asset_id.strip().upper()
    if key not in ASSETS:
        raise ValueError("编号不存在，请先使用asset_search查询")
    return {"id": key, **ASSETS[key]}

if __name__ == "__main__":
    mcp.run()

这两个工具故意不返回使用人姓名，也没有“更新位置”方法。asset_search 对位置词返回空列表属于当前接口约定，不代表设备不存在；以后需要按位置查询，应显式增加参数和测试，而不是悄悄改变搜索语义。

六、先验收工具，再接入宿主

先做语法检查：

.\.venv\Scripts\python.exe -m py_compile server.py

语法通过只说明文件能解析，不能说明依赖兼容、协议连接或工具行为已经成功。Inspector 是 Node.js 应用，需先安装兼容的官方 Node.js，并确认 node --version、npx --version 可用。安装了 CLI extra 后，可以用官方的 mcp dev server.py 方式在本地 Inspector 检查；在此虚拟环境中对应：

.\.venv\Scripts\mcp.exe dev server.py

按 CLI 实际提示完成本地检查环境的启动，先确认其列出了两个预期工具，再逐项调用。不要把检查器监听地址发布到公网，也不要因为看到页面就忽略工具结果。

建议在 acceptance.md 记录以下输入、预期与实际结果：

  1. 搜索“投影”：返回 A01，名称投影仪，位置一号会议室。
  2. 搜索“话筒”：返回 A03，不返回 A01 和 A02。
  3. 搜索“会议室”：返回空列表，因为本版只匹配设备名。
  4. 搜索空字符串或空格：返回可处理的参数错误。
  5. 读取 a02：转成 A02 并返回显示器、工位区。
  6. 读取 A99：明确编号不存在，不能随便选择相近设备。
  7. 搜索不存在的“打印机”：返回空列表，不能编造库存。
  8. 输入超过四十字符的关键词：拒绝并说明长度要求。

这些是预设验收标准，不是本文已完成的协议测试记录。真实运行时填写实际输出，保留失败项再修复，不能把预期列直接当成功报告。

只读台账工具正常结果空结果错误与越权请求的验收示意

七、连接宿主时使用绝对路径

普通运行 server.py 的默认 stdio 方式需要 MCP 客户端通过标准输入输出与它通信。终端没有网页、看起来一直等待，并不一定是服务卡死；也不要随便向标准输出打印调试信息干扰协议。

确认工具测试后，再按宿主的官方 MCP 设置新增本地 stdio 服务器：command 指向虚拟环境中的 python.exe，args 指向 server.py 的绝对路径。两个路径都要替换为自己机器上的实际位置，参数按宿主要求分开保存。

重新加载宿主的 MCP 配置，确认工具列表可见，再问“投影仪在哪”。检查它调用了哪个工具、传入了什么参数、是否真的根据返回值回答“一号会议室”。仅聊天说“已接入”不足以验收。

再问“把投影仪挪到二号会议室”。本服务器没有修改接口，宿主不应宣称已更新。接口描述是提示，实际能力由实现、连接配置和运行权限共同决定。

八、排错与下一步

  • No module named mcp：检查宿主使用的是否为项目虚拟环境解释器。
  • 导入 MCPServer 失败：核对安装版本，不要把 1.x 的 FastMCP 和 2.x 示例混用。
  • 找不到 CLI：确认安装了 [cli] extra，并使用虚拟环境内的可执行文件。
  • 工具能列出但参数报错：检查输入对象中的字段名是 query 还是 asset_id，不要传自然语言整段说明。
  • 工具返回空列表：先核对只匹配设备名的约定，再判断是否真的缺记录。

若宿主完全不调用工具，先区分“Skill 没被加载”和“MCP 没连接”两类情况。前者影响开发指导，可以要求助手报告已读取的 Skill 名称和参考文件；后者影响运行能力，需要查看宿主的连接状态与工具清单。即使开发助手完整读完了所有参考文件，也不会自动替另一个聊天应用添加服务器。

九、保存检查点，练习结束后怎样停用

把实际解释器路径、依赖版本、工具列表和失败记录放进项目说明。不要记录真实密码或把全部终端日志当作公开教程。修改接口时给需求说明写清变化，例如“增加按位置查询”，同时补上旧测试，确认原来的按名称行为没有意外改变。

结束练习后，在宿主中禁用或移除这个测试服务器连接，并关闭自己启动的检查器进程。若以后重新启用，先核对程序文件仍是审核过的版本，再检查工具是否多出了修改或网络访问能力。保留代码和测试记录即可，不需要为一个内存样例部署长期后台服务。

后续连接真实台账前，应重新设计身份、数据范围、返回字段、日志和错误处理。先在受控测试数据里验收，不把本文的内存字典示例直接称为生产级系统。固定 Skill 包也应保留版本和来源，方便日后更新时判断改动了什么。

官方参考