内容
# @muovi/mcp-server
[](https://www.npmjs.com/package/@muovi/mcp-server)
**适用于 [Muovi](https://muovi.com.ar)** 的模型上下文协议（MCP）服务器 - 拉丁美洲值得信赖的本地服务市场。
该软件包允许支持MCP的客户端（Claude Desktop、Cursor、Claude Code以及其他MCP主机）发现Muovi验证的拉丁美洲服务专业人员，浏览服务目录和城市列表，阅读评论，并深度链接用户进入平台上的任务创建流程。它是Muovi公共 [`/v1` REST API](https://muovi.com.ar/openapi.yaml) 的一个薄的只读包装器。
**标准输入/输出模式。** 该软件包附带一个可通过 `npx` 运行的二进制文件，该文件通过标准输入/输出进行JSON-RPC通信。托管的HTTP/SSE变体单独跟踪（Muovi MOB-142）。
## 暴露的工具
六个工具，均只读：
| 工具 | 封装 | 目的 |
| --- | --- | --- |
| `muovi_search_professionals` | `GET /v1/professionals` | 按服务、城市、社区、验证状态、最低评分、最低评论数量搜索验证的专业人员。 |
| `muovi_get_professional` | `GET /v1/professionals/{slug}` | 获取单个专业人员的完整公开个人资料（简介、作品集、专长、验证）。 |
| `muovi_list_services` | `GET /v1/services` | 完整的实时服务目录。 |
| `muovi_list_cities` | `GET /v1/cities` | Muovi服务的所有阿根廷城市，包括社区。 |
| `muovi_get_reviews` | `GET /v1/professionals/{slug}/reviews` | 专业人员的分页评论，按最新评论优先。 |
| `muovi_create_task_link` | （纯格式化） | 构建规范的深度链接，用户应通过该链接启动与特定专业人员进行特定服务的任务。不会进行HTTP调用。 |
## 反泄露政策
Muovi仅限平台使用。 **公共API从不返回电话、电子邮件和WhatsApp联系方式** - 消费者和专业人员之间的联系仅通过Muovi的应用内对话流程实现，该流程可从每个专业人员的 `profile_url` 访问。
该服务器两次强制执行该政策：
1. `/v1` API在服务器端剥离联系数据。
2. 本软件包中的每个工具响应也会通过本地反泄露检测器（Muovi web存储库中的[`src/lib/anti-leakage/detector.ts`](https://github.com/muovi-latam/muovi-web/blob/main/src/lib/anti-leakage/detector.ts)的Node兼容镜像）运行。如果在代理边界检测到泄露，工具将向LLM客户端返回稳定错误并拒绝显示有效载荷。
集成本服务器的主机 **不得** 从任何字段合成平台外部的联系方式。引导用户到 `profile_url`（可选地带有深度链接查询字符串）是唯一被批准的联系渠道。
## 安装与配置
### Claude Desktop
打开 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows），并在 `mcpServers` 下添加服务器：
```json
{
"mcpServers": {
"muovi": {
"command": "npx",
"args": ["-y", "@muovi/mcp-server"]
}
}
}
```
如果您有Muovi API密钥（请参见下面的[身份验证（可选）](#authentication-optional)），请通过环境变量传递：
```json
{
"mcpServers": {
"muovi": {
"command": "npx",
"args": ["-y", "@muovi/mcp-server"],
"env": {
"MUOVI_API_KEY": "your-key-here"
}
}
}
}
```
编辑配置后重启Claude Desktop。
### Cursor
添加到 `~/.cursor/mcp.json`（或您的工作区 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"muovi": {
"command": "npx",
"args": ["-y", "@muovi/mcp-server"]
}
}
}
```
### Claude Code
通过Claude Code CLI注册服务器：
```bash
claude mcp add muovi --command "npx" --args "-y" "@muovi/mcp-server"
```
或手动添加到Claude Code设置中：
```json
{
"mcpServers": {
"muovi": {
"command": "npx",
"args": ["-y", "@muovi/mcp-server"]
}
}
}
```
### 手动/脚本
```bash
npx -y @muovi/mcp-server
```
该进程在标准输入上读取JSON-RPC，并在标准输出上进行回复。所有日志输出都发送到标准错误流。
## 身份验证（可选）
所有 `/v1` 端点默认均为公共且无需身份验证。如果您的客户端已获得Muovi API密钥（更高的速率限制层），请在服务器环境中设置 `MUOVI_API_KEY`，该软件包将把该密钥作为 `X-API-Key` 头部转发到每个请求中。
您也可以覆盖测试的API基本URL：
```bash
MUOVI_API_BASE_URL=https://staging.muovi.com.ar/api/v1 npx -y @muovi/mcp-server
```
## 代理工作流程示例
一个典型的Claude对话，使用这些工具：
1. 用户要求“巴勒莫的一个持牌电工”。
2. 代理调用 `muovi_list_services` 将“电工”映射到 `electricidad`。
3. 代理调用 `muovi_list_cities` 以确认 `palermo` 是 `caba` 下的有效社区。
4. 代理调用 `muovi_search_professionals`，参数为 `{ service: "electricidad", city: "caba", neighborhood: "palermo", has_matricula: true, min_rating: 4.5 }`。
5. 代理选择顶级专业人员，并调用 `muovi_get_professional` 获取完整的简介 + 作品集。
6. 代理可选地调用 `muovi_get_reviews` 以获取社会证明。
7. 代理调用 `muovi_create_task_link`，参数为 `{ professional_slug, service_slug: "electricidad" }`，并显示生成的URL。
8. 用户跟随链接，登陆Muovi，完成平台上的任务创建流程。
步骤8 - 平台流程 - 是Muovi执行信任、支付和纠纷的强制环节。MCP永远不会绕过它。
## 本地开发
该软件包是独立的 [`muovi-latam/mcp-server`](https://github.com/muovi-latam/mcp-server) 仓库。克隆、安装并运行测试：
```bash
git clone git@github.com:muovi-latam/mcp-server.git
cd mcp-server
npm install
npm test # 单元测试 + 集成测试 + OpenAPI 漂移检查
npm run typecheck # 严格的TypeScript
npm run build # 生成 dist/
```
OpenAPI漂移测试解析 `public/openapi.yaml` 并断言每个工具的输入模式与相应的操作的精确参数匹配 - 在 `/v1` 中添加查询参数需要更新相应的工具（反之亦然）。
## 发布
`npm publish` 被故意 **不** 绑定到CI。版本发布由干净的标签手动切割：
```bash
npm version patch # 或 minor / major
npm publish --access public
git push --follow-tags
```
`prepublishOnly` 在任何发布前运行 `clean + build + test`。
### MCP注册表（mcp-publisher）
除了npm，该服务器还通过提交的 [`server.json`](./server.json) 清单在 [Model Context Protocol注册表](https://registry.modelcontextprotocol.io) 中列出。发布到注册表是一个 **手动步骤** - 没有CI自动发布（注册表是一个低频率、人工控制的表面，命名空间身份验证是交互式的）。
**已提交命名空间：** `ar.com.muovi/mcp-server` - `muovi.com.ar` 的反DNS形式。该值存在于 **both** `server.json` （`name`）和 `package.json` （`mcpName`）中，两个必须 **保持字节相同** （`server-json`测试强制执行相等）。它还必须与您使用 `mcp-publisher` 身份验证的身份匹配（如下所述）。
#### 一次性命名空间所有权设置
在第一次发布之前证明 `ar.com.muovi` 命名空间的所有权：
- **DNS（首选）：** 将 `mcp-publisher login dns` 打印的TXT记录添加到 `muovi.com.ar` 区域，然后对该域进行身份验证。这将命名空间绑定到我们已经控制的域。
- **GitHub OAuth（备用）：** `mcp-publisher login github` - 通过 `muovi-latam` GitHub组织进行身份验证。仅在DNS验证不可用时使用；身份验证的身份仍必须与已提交的 `ar.com.muovi/mcp-server` 命名空间一致。
如果已提交的命名空间和身份验证的身份不一致，`mcp-publisher publish` 将拒绝清单 - 修复命名空间（在两个文件中）或登录，不要强制执行。
#### 发布步骤
```bash
mcp-publisher validate ./server.json # 检查与实时注册表模式的匹配
mcp-publisher publish # 在身份验证的命名空间下发布 server.json
```
`validate` 是确认清单与当前注册表模式版本匹配的步骤 - 每次运行； `server.json` 中固定的 `$schema` 是一个提示，而不是保证实时模式已移动。
#### 版本提升规则
`server-json` 测试断言四个版本字段一致。 **每次** 版本提升时，请同时更新所有字段，然后发布到npm和注册表：
1. `package.json` → `version`
2. `src/server.ts` → `PACKAGE_VERSION`
3. `server.json` → `version`
4. `server.json` → `packages[0].version`
#### 诚实的门控说明
清单宣传了尚未完全生效的功能。请牢记以下几点（不要向用户夸大）：
- **远程传输** (`remotes[].url` = `https://mcp.muovi.com.ar/`) 仅在该端点可靠地通过流式HTTP响应JSON-RPC `initialize` 时才是真实的。该托管界面在 **MOB-207** 中跟踪；在此之前，**stdio** 包（`npx @muovi/mcp-server`）是唯一实际工作的传输。
- **`muovi_get_professional`** 和 **`muovi_get_reviews`** 在 **MOB-263** 部署后端 `/v1` 端点之前仍然在生产环境中损坏。这些工具已注册并通过漂移检查，但实时调用将失败，直到那时。
## 许可证
[MIT](./LICENSE).
## 链接
- [Muovi](https://muovi.com.ar)
- [公共 `/v1` API 规范](https://muovi.com.ar/openapi.yaml)
- [模型上下文协议](https://modelcontextprotocol.io)
- [报告问题](https://github.com/muovi-latam/mcp-server/issues)
