mcp-server-shipping

发布个人 MCP 服务

适用于此类仓库的工作流：仓库的全部用途是生成供个人跨项目使用的 MCP 服务，而不是供其他代码导入的库。介绍如何从一个可正常工作的仓库，做到“可在任何项目中加载”，以及开发机器与其他环境之间有何不同。示例使用作者自己的服务名称——一组 *-polite-mcp 仓库——因为具体名称比占位符更易读；请在所有地方替换为你自己的名称。

发布 Agent Skill 是另一项工作，机制也不同——请参阅 skill-authoring-taudelta 技能，其中还介绍了如何部署对现有技能的修改。

此技能读取、运行和写入的内容

此技能不提供脚本；它通过指示你运行的命令来完成所有操作。

• 运行：uv tool install、claude mcp add、claude mcp list。
• 写入：uv tool install 会在 uv 的工具目录下创建工具环境，并在 PATH 中放置一个 shim（默认位于 ~/.local/bin/）；claude mcp add --scope user 会将服务注册信息写入 Claude Code 的用户级配置，--scope project 则写入仓库的 .mcp.json。两者都可以通过相应工具的 uninstall／remove 撤销。除此之外不会写入任何内容，也不会改动服务所在仓库中的任何内容，只有你手动添加的 [project.scripts] 条目除外。
• 网络：uv tool install git+… 会克隆你指定的仓库。

每个仓库的开发循环

这里有两点具有普遍性，另一点则是作者自己的技术栈。 普遍适用的两点是：这类仓库需要一个一条命令即可完成的设置流程，从已提交的锁文件同步环境，而不是重新解析依赖；还需要一个一条命令即可完成的检查关卡，自动修复后运行与 CI 相同的检查。你的仓库已经在用什么，就继续用什么——重点在于两者都存在，且都能通过一条命令完成，而不是由哪个运行器提供。

本节其余内容描述的是作者的配置，仅作为实例，而非操作说明。在作者的机器上，这一系列仓库都会将 repo-tasks 作为开发依赖（将 git 用作制品存储，无需 PyPI），而不是手写 tasks.py 逻辑；因此仓库自己的 tasks.py 只有 from repo_tasks import ns；inv dev-env.setup 是设置命令，inv quality.precommit 是检查关卡；AGENTS.md／CLAUDE.md／skills 脚手架则在创建仓库时由 scaffoldapy 生成。请在所有地方替换为你自己的同类工具。

无论你使用什么运行器，都值得遵循这一条规则： 任务运行器是每个项目各自的依赖，绝不能假定它位于 PATH 中。任何从未激活的 shell 外部调用它的操作——CI 步骤、项目生成钩子、任何自动化——都必须通过项目自身的环境执行（对于由 uv 管理的项目，使用 uv run <runner> <task>），因为没有任何保证能确保单独使用运行器名称时，解析到的是此项目的版本，而不是其他版本，甚至不是什么都找不到。这正是本节旨在避免的错误，与使用哪个运行器无关。

一个入口点：通过 uv tool install 安装稳定的 PATH 二进制文件

在编写 server.py 之前，先在 MCP 仓库的 pyproject.toml 中添加 [project.scripts] 入口点（例如 olx-polite-mcp = "olx_polite_mcp.server:main"），而不是事后补上。然后通过 uv tool 将其作为真正的工具安装（已在 olx-polite-mcp/README.md 中端到端验证），而不是让 claude mcp add 指向 uv run/uvx 调用。uv tool install 会构建隔离环境，并在 PATH 上放置一个 shim（默认位于 ~/.local/bin/），因此注册时只需使用裸二进制名称，无需维护路径或标志：

主动开发期间，对本地工作树进行安装（可编辑模式——无需重新安装即可获取本地修改，因此仓库必须一直位于该路径）：

uv tool install -e <path-to-your-checkout>

不再主动迭代后，从 GitHub 安装（为确保可复现性，可固定为 @<tag>/@<sha>；省略则使用默认分支）：

uv tool install git+https://github.com/TheodoreAD/olx-polite-mcp

无论采用哪种方式，注册时都是同一条命令，与安装来源无关：

claude mcp add --scope user olx-polite-mcp olx-polite-mcp

切换来源时，再次使用 uv tool install 指定另一来源即可（uv 会替换现有工具）——无需运行 claude mcp remove/重新执行 add，因为注册的命令名称始终不变。 --scope user（而不是 local/project）与技能已采用的全局安装方式一致，因此该服务可在这台机器上的每个项目中使用，而不只是某一个项目。只有当某个_使用方_仓库希望任何克隆该仓库的人都能自动使用此服务时，才改用 --scope project（参见 olx-polite-mcp/README.md 中的项目范围示例）——这与个人跨项目使用是不同的情况。

可编辑安装不能与 GitHub 安装结合使用（可编辑安装需要 uv 能够指向的真实工作目录；从 git 来源安装时不会暴露这样的目录）。若要“在本地编辑，但从 GitHub 获取”，请自行执行 git clone，然后对该克隆运行 uv tool install -e；这仍然属于从磁盘进行可编辑安装的情况。

项目范围和用户范围的服务都需要在 claude 启动时进行一次性批准，之后才能启动_新_会话（claude mcp list 会显示待批准的服务）——已获批准且正在运行的会话会继续使用该服务。

分发：跳过 PyPI

对于这种规模的项目（个人用途、非商业用途），uv tool install 直接从 git 远程解析（见上文），就能让 GitHub 仓库本身充当制品存储库——无需版本递增、发布或配置凭据等流程。仓库有了值得固定的稳定版本后，可固定为 @<tag>/@<sha>；迭代期间不指定引用（跟踪默认分支）即可。

完整理由

references/rationale.md — 说明为何选择 git+uv 而非 PyPI（以及为何放弃最初采用的 uvx/uv run 方案）、为何使用 --scope user，以及为何一个注册命令即可涵盖两种安装来源。