MDMA

@mobile-reality/mdma-mcp

适用于 MDMA 的 MCP（Model Context Protocol）服务。向 AI 助手提供 MDMA 规范、创作提示词、软件包元数据和实时 GitHub 文档。

工具

工具	用途
get-spec	返回完整的 MDMA 规范（组件类型、JSON 架构、绑定语法、包含 { source, params } 引用和 rows / series / options 类型的外部数据源，以及创作规则）。
get-prompt	返回指定的 MDMA 提示词（mdma-author、mdma-reviewer、mdma-fixer）。对于 mdma-author，可选传入 variantId（例如 anthropic/sonnet-5.5、openai/gpt-6-sol）以返回针对模型优化的变体——使用 list-prompt-variants 查看所有可用 ID。
list-prompt-variants	返回所有可用的 MDMA_AUTHOR 提示词变体（ID、标签、说明），不包含提示词内容。使用该 ID 调用 get-prompt，即可获取针对模型优化的提示词。
build-system-prompt	根据结构化输入（领域、组件、字段、步骤、业务规则）生成自定义 MDMA 提示词。传入 dataSources（包含 rows / series / options 条目的外部数据源目录），即可获取包含该目录以及通过 { source, params } 引用数据规则的完整系统提示词。
validate-prompt	根据 MDMA 约定验证自定义提示词。
list-packages	返回所有 MDMA npm 软件包及其用途、安装命令、用法示例和类别。
list-docs	返回可从公开 GitHub 仓库获取的 MDMA 文档文件目录。
get-doc	从 raw.githubusercontent.com/MobileReality/mdma 获取最新版文档。支持可选的 ref（分支、标签或 SHA）。

安装

{
  "mcpServers": {
    "mdma": { "command": "npx", "args": ["@mobile-reality/mdma-mcp"] }
  }
}

发布渠道

MDMA 的 MCP 服务已发布或计划发布到的渠道。每个渠道都有自己的提交 / 更新流程——发布新版本时，请逐一检查。

渠道	标识符 / URL	备注
npm	@mobile-reality/mdma-mcp	使用 pnpm publish --access public --no-git-checks 发布。
Official MCP Registry	io.github.MobileReality/mdma	通过 mcp-publisher 发布。命名空间区分大小写——必须与 GitHub 上的规范大小写一致。
Glama	MobileReality/mdma	质量和安全评分会定期自动评估。Docker 构建配置位于 Glama 管理页面——升级版本时需要重新部署并重新发布。
awesome-mcp-servers	punkpeye/awesome-mcp-servers	条目按字母顺序列在 Developer Tools 下。
Smithery Skills	mobilereality/mdma	Skills 展示页面——不是 MCP 展示页面（Smithery 的 MCP 流程仅支持 HTTP，无法用于 stdio）。
MCP.so	mcp.so/server/mdma	由 Mateusz Sadowski 提交（公开页面显示为“Submitted by”），因此标题 / 描述 / 标签 / 内容需要通过该账号编辑。如果无法访问，请让 Mateusz Sadowski 编辑，或使用服务器名称旁的“Claim”按钮（需先登录；此处未记录 MCP.so 要求的验证方式）。该页面列出了工具和 npx @mobile-reality/mdma-mcp 命令，但未列出版本，因此除非工具集或描述发生变化，否则发布新版本时无需更新。
MCPB Desktop Extensions	Anthropic intake form	在 Anthropic 的合作伙伴队列中。本地构建捆绑包；不会随本仓库一同发布。

发布检查清单 — 升级版本时

每次发布新版本时都使用此检查清单（例如 0.2.4 → 0.2.5）。

1. 升级 + 测试

• 更新 package.json 中的 version。
• 更新 src/index.ts 中的 version 字符串（McpServer({ version: ... }) 调用）。
• 更新 server.json 中顶层的 version 以及 packages[0].version。
• 更新 manifest.json 中顶层的 version 以及 packages[0].version。
• 添加变更集：在仓库根目录运行 pnpm changeset。
• 在此软件包中运行 pnpm build && pnpm test && pnpm typecheck。
• 在此软件包中运行 pnpm smoke:pack — 它会打包、将 tarball 安装到干净目录，并通过 stdio 检查 tools/list 和 get-spec；发布前必须打印 PASS。

2. 发布到 npm

• 在此目录中运行 pnpm publish --access public --no-git-checks。
• 验证：npm view @mobile-reality/mdma-mcp version mcpName — 两项都应匹配。

3. 发布到 MCP Registry

• 确保 mcp-publisher 已通过身份验证：运行 mcp-publisher login github（如果令牌已过期，请重新验证）。
• 在此目录中运行 mcp-publisher publish。
  • 替代方案：在 npm 发布后，从 main 分支的 Actions 选项卡运行“Publish to MCP Registry”工作流。如果组织限制了 OAuth 应用，交互式 mcp-publisher login github 会失败；该工作流会改用 GitHub OIDC。
• 验证：curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.MobileReality/mdma" 应显示新版本。

不要提交 .mcpregistry_github_token / .mcpregistry_registry_token — 它们已列在 .gitignore 中。GitHub 的推送保护无论如何都会阻止推送；这里再提醒一次，以确保万无一失。

4. 为发布版本打标签

git tag '@mobile-reality/mdma-mcp@<version>'
git push origin '@mobile-reality/mdma-mcp@<version>'

5. 构建全新的 MCPB 捆绑包（仅在提交桌面扩展更新时）

pnpm 的虚拟存储（.pnpm/）会被 mcpb pack 清除，因此必须在通过 npm 干净安装的目录中构建捆绑包，否则会缺少传递依赖（例如 ajv）。

输出：<name>-<version>.mcpb。在 Claude Desktop 中测试安装，然后将其作为 GitHub Release 资源附件。

6. Glama — 如果工具描述或 Dockerfile 配置有变更

• 如果添加了工具、重命名了工具，或更改了工具描述：Glama 的质量评分会在下次定期扫描时重新评估，无需手动触发。
• 如果 packages[0].version 已升级：前往 Glama 管理页面 → 更新 Build steps（npm install -g @mobile-reality/mdma-mcp@<version>）→ Deploy → Make Release。

7. 下游同步

• 如果添加、重命名或移除了工具，请更新根目录 README.md 中的 MCP 工具表格。
• 按相同方式更新此软件包自身的工具表格（上方）。
• 如果工具有变更：更新 MCP.so 上的条目，该条目由另一个账户维护（参见 Distribution venues 中的 MCP.so 行）。
• 如果有破坏性变更：在变更集中注明；如有使用者依赖 createMdmaMcpServer()，请更新这些使用者。

故障排查

发布到 MCP Registry 时失败并返回 403 Forbidden

如果错误提示为 permission to publish: io.github.gitsad/*, io.github.MobileReality/*. Attempting to publish: io.github.mobilereality/mdma（大小写不匹配）：Registry 区分大小写，mcpName / server.json 中的 name 必须与 GitHub 的规范名称大小写完全一致，即 MobileReality。请修正这两个文件并重新发布到 npm（npm 上的版本不可更改）。

如果错误提示为 permission to publish: io.github.gitsad/*（组织信息完全缺失）：你的 MobileReality GitHub 成员身份设为私密。请在 https://github.com/orgs/MobileReality/people 将其设为公开，然后运行 mcp-publisher logout && mcp-publisher login github 以刷新 JWT。

MCPB .mcpb 在 Claude Desktop 中安装时崩溃

通常会在 Developer 标签页的日志中看到“缺少模块”错误。原因：打包时，pnpm 的嵌套 .pnpm/ 虚拟存储被剥离，导致缺少传递依赖。解决方法：从使用 npm 安装的干净目录构建捆绑包（参见上文第 5 步）。不要直接对 packages/mcp/node_modules 运行 mcpb pack。

密钥泄漏到捆绑包中

mcpb pack 不会遵循 .gitignore。打包时，清单旁边的任何 .mcpregistry_*_token 文件都会被打包进 .mcpb。打包前务必删除这些文件，并优先使用上文的 /tmp/mcpb-build 工作流，因为该目录中没有令牌。

此软件包中的文件

文件	用途	是否跟踪？
src/	服务和工具的 TypeScript 源代码。	✅
dist/	编译后的 JavaScript。	❌（已加入 gitignore）
tests/	用于测试工具逻辑的 Vitest 单元测试。	✅
package.json	包含 MCP Registry 所需的 mcpName 字段。	✅
server.json	由 mcp-publisher 使用的 MCP Registry 清单。	✅
manifest.json	MCPB（桌面扩展）清单。	✅
icon.png	用于提交 MCPB 的 1024×1024 方形图标。	✅
screenshots/	随 MCPB 一起打包的截图，用于 Claude Desktop 安装对话框。	✅
*.mcpb	构建后的桌面扩展捆绑包（构建产物）。	❌（已加入 gitignore）