meridian-mcp

@meridiantoolkit/mcp

适用于 Meridian 商业服务平台的 MCP 服务。将服务、服务请求、工作流步骤、付款和会议作为 Model Context Protocol 工具和资源公开。MCP 是一种协议，而非特定宿主的插件格式——此服务无需修改即可在 Claude Code、Codex CLI、Claude Desktop、pi 或任何其他兼容 MCP 的客户端中运行。

已列入官方 MCP Registry，名称为 io.github.meridian-silkdev/meridian-mcp，也已列入 Glama。

安装

cd meridian-mcp
npm install
npm run build

或在发布后：

npx @meridiantoolkit/mcp

配置

复制 .env.example，或直接设置环境变量：

变量	说明	默认值
MERIDIAN_API_URL	Meridian 应用的基础 URL	http://localhost:3000
MERIDIAN_API_KEY	用于 REST 调用的 mrd_ API 密钥（Better Auth）	（无——设置之前，工具会返回占位提示）
DATABASE_URL	可选的直接数据库访问回退项
MERIDIAN_MCP_LOG_LEVEL	debug/info/warn/error	info

更多信息：/.well-known/agent-configuration 提供 Agent Auth 发现功能（基于能力、短期 JWT、设备认证/CIBA 审批）。Agent 可以使用长期有效的 mrd_ 密钥或范围受限的 Agent Auth 授权——请参阅 meridian-skills 的 meridian-api 技能。

未设置 MERIDIAN_API_KEY 时，每个工具仍会响应——它会说明将调用哪个端点以及需要配置什么，因此该服务可安全地在试运行/演示模式下运行。

运行

npm start            # stdio MCP server
npm run dev          # watch mode via tsx

Claude Code

claude mcp add meridian -- node /absolute/path/to/meridian-mcp/dist/index.js
# or, once published:
claude mcp add meridian -- npx -y @meridiantoolkit/mcp

或者在项目根目录中放置 .mcp.json（可与团队共享并提交到 git）：

{
  "mcpServers": {
    "meridian": {
      "command": "npx",
      "args": ["-y", "@meridiantoolkit/mcp"],
      "env": {
        "MERIDIAN_API_URL": "http://localhost:3000",
        "MERIDIAN_API_KEY": "..."
      }
    }
  }
}

Codex CLI

Codex 从 ~/.codex/config.toml 读取 MCP 服务（也可以为受信任的项目使用项目级 .codex/config.toml）：

[mcp_servers.meridian]
command = "npx"
args = ["-y", "@meridiantoolkit/mcp"]
env = { MERIDIAN_API_URL = "http://localhost:3000", MERIDIAN_API_KEY = "..." }

也可以通过 CLI 添加：codex mcp add meridian -- npx -y @meridiantoolkit/mcp。Codex CLI、IDE 扩展和 ChatGPT 桌面应用共用相同的配置。

Codex 没有插件/技能系统（不同于 Claude Code 和 pi）——与 meridian-plugin/meridian-skills 等效的方式，就是使用此 MCP 服务并提供项目指南。将 AGENTS.md.example 复制到项目的 AGENTS.md，即可获得与其他技能包相同的工具使用指南。

Claude Desktop / pi

将其添加到 MCP 配置中（Claude Desktop：claude_desktop_config.json；pi：.pi/settings.json → mcpServers，或使用 pi --mcp）：

{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/absolute/path/to/meridian-mcp/dist/index.js"],
      "env": {
        "MERIDIAN_API_URL": "http://localhost:3000",
        "MERIDIAN_API_KEY": "..."
      }
    }
  }
}

pi --mcp meridian-mcp/dist/index.js
# or via npx after publish
npx @meridiantoolkit/mcp

工具

工具	说明
meridian_status	检查 API 连接/配置，并列出可用工具/资源。无参数。在所有客户端中的行为相同——此工具取代了 meridian-plugin 中仅限 pi 的 meridian_status 扩展工具，避免状态检查与某个宿主绑定。
list_services	列出服务（筛选条件：categorySlug、isActive、countryCode）
get_service	根据 id/slug 获取服务及其 formConfig
list_categories	列出服务类别
list_service_requests	列出请求（筛选条件：status、customerId、providerId、limit）
get_service_request	根据 id 获取请求及其步骤
create_service_request	创建请求（serviceId、answers、customTitle）
update_request_status	更新请求状态（优先使用 advance_step）
get_workflow_status	当前阶段和所有 requestSteps
advance_step	完成当前步骤 → 进入下一步骤
list_request_steps	按顺序列出所有 RequestSteps
get_payment_status	获取请求对应的付款记录
verify_payment	在服务端通过 Flouci（突尼斯本地）或 Stripe（国际）验证付款
list_meetings	列出会议（筛选条件：serviceRequestId、status）
create_meeting	创建 Teams 会议并发送邀请
respond_to_meeting	回复会议邀请：接受/拒绝/待定

资源

URI	描述
meridian://services	服务目录 JSON
meridian://workflow	工作流骨干 + 阶段

开发

npm run typecheck
npm run build
npm test          # spawns the built server over stdio and exercises every tool/resource

发布

首次发布（手动，仅需一次 — 作用域包在注册表中创建之前无法使用 Trusted Publishing）：

npm login                     # once per machine
npm publish --access public

CI/CD

• .github/workflows/ci.yml — 每次推送到 main 以及每个 PR 都会运行：npm ci、类型检查、构建、npm test（真实的 stdio 冒烟测试套件）。
• .github/workflows/publish.yml — 在 GitHub Release 发布时触发，重新运行完整测试套件，检查发布标签是否与 package.json 的版本一致，然后：
  1. 通过 npm 的 Trusted Publishing (OIDC) 执行 npm publish --provenance — 无需创建或轮换 NPM_TOKEN 密钥。
  2. 通过 mcp-publisher login github-oidc + mcp-publisher publish 在官方 MCP Registry 中发布/更新条目（同样使用 OIDC，无需密钥）。server.json 的版本会自动与发布标签同步。此步骤设置了 continue-on-error: true — 注册表明确处于预览阶段，因此即使这一步出错，也不会阻止实际的 npm 发布。

mcpName 要求：package.json 中有一个 "mcpName": "io.github.meridian-silkdev/meridian-mcp" 字段 — 注册表的包验证器需要此字段，以确认 npm 包和经 GitHub 验证的服务身份由同一所有者发布。如果你以后在 server.json 中重命名服务，也要更新此字段，否则发布会返回 400。

**已知的上游错误，现已规避：**通过 GitHub 组织命名空间发布时，交互式 mcp-publisher login github 设备授权流程会稳定地返回 403（已确认公开的组织成员身份、Owner 角色也无济于事 — 参见 modelcontextprotocol/registry#1537，截至本文撰写时仍未解决）。在组织自己的仓库中运行的 GitHub Actions 工作流内使用 github-oidc 可完全绕过此问题，因为它验证的是工作流的仓库身份，而不是检查个人账号的组织列表。因此，注册表发布步骤放在 CI 中，而不是作为手动本地命令。

**首次手动发布后的一次性设置：**进入该包在 npmjs.com 上的页面 → Settings → Trusted Publisher → GitHub Actions，并将其指向 meridian-silkdev/meridian-mcp，工作流选择 publish.yml。此后，发布新版本只需：

npm version patch   # or minor/major — bumps package.json + creates a git tag
git push --follow-tags
gh release create v0.1.3 --generate-notes   # publishing this release triggers both the npm and MCP Registry publish steps