muovi

@muovi/mcp-server

适用于 Muovi 的 Model Context Protocol (MCP) 服务——LATAM 以信任为先的本地服务市场。

这个软件包让支持 MCP 的客户端（Claude Desktop、Cursor、Claude Code 和任何其他 MCP 主机）能够查找 Muovi 上经过验证的 LATAM 服务专业人士、浏览服务目录和城市列表、阅读评价、通过深层链接将用户引导至平台内的任务创建流程，并保存由用户自行发布的任务草稿。它是 Muovi 公共 /v1 REST API 的轻量封装。

Stdio 模式。 该软件包提供可通过 npx 运行的二进制文件，使用 stdin/stdout 传输 JSON-RPC。托管式 HTTP/SSE 版本单独跟踪（Muovi MOB-142）。

提供的功能

除 muovi_create_task_draft（会在 Muovi 上保存草稿）外，所有工具均为只读：

工具	封装的接口	用途
muovi_search_professionals	GET /v1/professionals	为一个服务在一个 barrio 中最多查找 5 位专业人士。service 和 neighborhood 均为必填项；每条结果的服务范围都包含该 barrio，且 match 会列出搜索的服务、barrio 和城市。结果优先列出声明从事所查行业的专业人士，并按评价得分排序；身份验证、背景调查和 matrícula 均计入得分。注册业务属于其他行业的专业人士排在最后；不设评分或评价筛选。每条结果都包含一个 rating、一个 review_count、其 verifications、最多 3 个 portfolio 图片 URL、一个 id 和一个 profile_url（https://muovi.com.ar/profile/<id>），不包含 neighborhoods。
muovi_get_professional	GET /v1/professionals/{id}	根据搜索结果中的 id 获取单个专业人士的完整公开个人资料（简介、作品集、专长、验证信息）。也接受旧链接中的 ProSite slug。
muovi_list_services	GET /v1/services	完整的实时服务目录——家居服务（电气、管道、燃气、油漆、木工、锁匠、砌砖、锻铁、屋顶工）、清洁、园艺、空调，以及搬家/运输：mudanzas（搬家公司）和 fletes（轻型货运）。
muovi_list_cities	GET /v1/cities	Muovi 服务覆盖的所有阿根廷城市及其街区。
muovi_get_reviews	GET /v1/professionals/{id}/reviews	根据相同的 id 获取专业人士的分页评价，按时间从近到远排列。
muovi_create_task_link	（纯格式化器）	为一位专业人士（professional_id，即搜索结果中的 id）和一项服务生成 Muovi 自带的任务创建链接：https://muovi.com.ar/post-task/v2?pro=<id>&vertical=<service>&source=assistant-link。适用于所有搜索结果中的专业人士。参数缺失或格式错误时会返回工具错误。不发起 HTTP 请求。
muovi_get_service_requirements	GET /v1/services/{service_slug}/requirements	列出 Muovi 针对某项服务提出的问题（键、西班牙语问题、类型、可选答案，以及是否必填），让 Agent 能在保存草稿前询问用户。
muovi_create_task_draft	POST /v1/task-handovers	保存任务草稿（服务、描述、可选区域、首选时间和专业人士），并返回一个链接；若无人打开，该链接将在 24 小时后过期。用户打开链接、检查草稿、登录并发布；该工具不会发布任何内容。若提供 professional_id（即搜索结果中的 id），已发布的任务会优先发送给该专业人士 24 小时，之后再向所有人开放；若设为 open_to_others: true，任务会立即向所有人开放，同时仍会通知该专业人士。用户可以在审核表单中更改此选择。

防泄漏政策

Muovi 仅限平台内使用。公共 API 绝不会返回电话、邮箱或 WhatsApp 联系方式——消费者与专业人士只能通过 Muovi 应用内的对话流程联系，该流程可从每位专业人士的 profile_url 访问。

此服务会对该政策进行双重保护：

1. /v1 API 会在服务端剔除联系信息。
2. 此软件包中的每个工具响应也会经过本地防泄漏检测器（这是 Muovi 网站仓库中 src/lib/anti-leakage/detector.ts 的 Node 兼容镜像）。如果在 Agent 边界检测到泄漏，该工具会向大模型客户端返回固定错误，并拒绝暴露载荷。

集成此服务的宿主不得根据任何字段合成平台外的联系方式。引导用户前往 profile_url（可选附加深层链接查询字符串）是唯一获准的联系渠道。

安装与配置

Claude Desktop

打开 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），并在 mcpServers 下添加该服务：

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"]
    }
  }
}

如果你有 Muovi API 密钥（见下文身份验证（可选）），请通过 env 传入：

{
  "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）：

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"]
    }
  }
}

Claude Code

使用 Claude Code CLI 注册该服务：

claude mcp add muovi --command "npx" --args "-y" "@muovi/mcp-server"

也可以手动将其添加到 Claude Code 设置中：

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"]
    }
  }
}

手动 / 脚本

npx -y @muovi/mcp-server

该进程从 stdin 读取 JSON-RPC，并向 stdout 回复。所有日志输出都发送到 stderr。

身份验证（可选）

默认情况下，所有 /v1 端点都是公开且无需身份验证的。如果客户端获得了 Muovi API 密钥（可享受更高的速率限制），请在服务的环境中设置 MUOVI_API_KEY，该软件包会在每次请求中将其作为 X-API-Key 标头转发。

你也可以覆盖 API 基础 URL 以用于测试：

MUOVI_API_BASE_URL=https://staging.muovi.com.ar/api/v1 npx -y @muovi/mcp-server

如果 MUOVI_WEB_BASE_URL 是不带路径的 https 源，muovi_create_task_link 会基于该值构建链接；否则会使用 https://muovi.com.ar。

Agent 工作流示例

使用这些工具的典型 Claude 对话：

1. 用户询问“找一位持有正规执照的 Palermo 电工”。
2. Agent 调用 muovi_list_services，将“electrician”映射为 electricidad。
3. Agent 调用 muovi_list_cities，确认 palermo 是 caba 下的有效街区。
4. Agent 使用 { service: "electricidad", neighborhood: "palermo", has_matricula: true } 调用 muovi_search_professionals，最多获取 5 位专业人士。如果缺少服务和街区中的任意一项，该工具会报错并要求补充，因此 Agent 会先询问用户。
5. Agent 展示结果，并提供两种选择：为其中一位专业人士创建任务，或发布一般需求以获取多位专业人士的报价。
6. 对于某位专业人士，Agent 可以使用该结果的 id 调用 muovi_get_professional 和 muovi_get_reviews。
7. Agent 使用 { professional_id, service_slug: "electricidad" } 调用 muovi_create_task_link 并展示生成的 URL；或者使用 { service_slug: "electricidad", professional_id, description } 调用 muovi_create_task_draft，让用户进入已填写描述的草稿。如果是一般需求，则调用时不提供专业人士。
8. 用户点击链接进入 Muovi，查看草稿、登录，并通过平台内流程发布任务。

第 8 步——平台内流程——是发布任务的环节，也是付款和争议处理的环节。

本地开发

此软件包是独立的 muovi-latam/mcp-server 仓库。克隆仓库、安装依赖并运行测试：

git clone [email protected]:muovi-latam/mcp-server.git
cd mcp-server
npm install
npm test            # unit + integration + OpenAPI drift checks
npm run typecheck   # strict TypeScript
npm run build       # emits dist/

OpenAPI 漂移测试会解析 public/openapi.yaml，并断言每个工具的输入架构与对应操作的参数完全一致——向 /v1 添加查询参数时，必须同时更新对应的工具（反之亦然）。

发布

npm publish 不会接入 CI，这是有意为之。版本需从干净的标签手动发布：

npm version patch    # or minor / major
npm publish --access public
git push --follow-tags

任何发布之前，prepublishOnly 都会运行 clean + build + test。

MCP Registry (mcp-publisher)

除 npm 外，此服务还通过已提交的 server.json 清单列入 Model Context Protocol 注册表。向注册表发布是手动步骤——特意不设置 CI 自动发布（注册表发布频率较低，需要人工审核，且命名空间认证需要交互操作）。

已提交的命名空间： ar.com.muovi/mcp-server——muovi.com.ar 的反向 DNS 形式。此值同时位于 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 将拒绝该清单——请修正命名空间（两个文件中都要修改）或登录身份，不要强行发布。

发布步骤

mcp-publisher validate ./server.json   # checks against the live registry schema
mcp-publisher publish                   # publishes server.json under the authenticated namespace

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_create_task_draft 会返回“不可用”，因为服务器上的任务移交功能已关闭（TASK_HANDOVERS_ENABLED），这是默认设置。
• 在 MOB-263 部署底层 /v1 端点之前，muovi_get_professional 和 muovi_get_reviews 在生产环境中仍不可用。这些工具已注册且通过了漂移检查，但在部署之前，线上调用会失败。

许可证

MIT。

链接

• Muovi
• 公开的 /v1 API 规范
• Model Context Protocol
• 报告问题