mdma
This server gives AI assistants access to the MDMA spec, authoring/review/fix prompts, prompt-variant and prompt-building/validation utilities, npm package info, and live GitHub documentation.
get-spec— retrieve the full MDMA specification: component types, JSON schemas, binding syntax, external data-source refs ({ source, params },rows/series/optionskinds), and authoring rules.get-prompt— fetch a named MDMA prompt (mdma-author,mdma-reviewer,mdma-fixer), optionally with a model-specificvariantIdformdma-author.list-prompt-variants— list all availableMDMA_AUTHORvariants (id, label, description) to use withget-prompt.build-system-prompt— generate a custom MDMA prompt from structured input (domain, components, fields, steps, business rules), optionally returning a full system prompt when adataSourcescatalog is supplied.validate-prompt— check a custom prompt against MDMA conventions, returning warnings about anti-patterns and improvement suggestions.list-packages— list all MDMA npm packages with purpose, install command, usage example, and category.list-docs— browse the catalog of MDMA documentation files available (path, title, description).get-doc— fetch the latest content of a doc from the public GitHub repo (raw.githubusercontent.com/MobileReality/mdma), with an optionalreffor branch/tag/SHA.
Fetches MDMA documentation live from the public MobileReality/mdma GitHub repository via raw.githubusercontent.com, with tools to list the catalog of available docs (path, title, description) and retrieve any doc's contents, optionally pinned to a specific branch, tag, or commit SHA.
@mobile-reality/mdma-mcp
MCP (Model Context Protocol) server for MDMA. Exposes the MDMA spec, authoring prompts, package metadata, and live GitHub documentation to AI assistants.
Tools
Tool | Purpose |
| Returns the full MDMA specification (component types, JSON schemas, binding syntax, external data sources with |
| Returns a named MDMA prompt ( |
| Returns all available |
| Generates a custom MDMA prompt from structured input (domain, components, fields, steps, business rules). Pass |
| Validates a custom prompt against MDMA conventions. |
| Returns all MDMA npm packages with purpose, install command, usage example, and category. |
| Returns the catalog of MDMA documentation files available for fetching from the public GitHub repo. |
| Fetches the latest version of a doc from |
Related MCP server: mcp-docs
Install
{
"mcpServers": {
"mdma": { "command": "npx", "args": ["@mobile-reality/mdma-mcp"] }
}
}Distribution venues
Places where MDMA's MCP server is published or should be published. Each venue has its own submission / update flow — when releasing a new version, check each one.
Venue | Identifier / URL | Notes |
npm |
| Publish via |
Official MCP Registry |
| Published via |
Glama | Quality + Security scores auto-evaluated periodically. Docker build config lives in the Glama admin page — re-deploy + re-release when bumping. | |
awesome-mcp-servers |
| Entry sits under Developer Tools alphabetically. |
Smithery Skills |
| Skills surface — not the MCP surface (Smithery's MCP flow is HTTP-only, unusable for stdio). |
MCP.so | Submitted by Mateusz Sadowski (shown as "Submitted by" on the public page), so Title / Description / Tags / Content are edited from that account. Without access, ask Mateusz Sadowski to edit it, or use the "Claim" button next to the server name (sign in first; the verification MCP.so requires is not documented here). The page lists the tools and the | |
MCPB Desktop Extensions | Anthropic intake form | Partner queue at Anthropic. Bundle built locally; not shipped in this repo. |
Release checklist — when bumping the version
Use this checklist every time you publish a new version (0.2.4 → 0.2.5, etc.).
1. Bump + test
Update
versionin package.json.Update
versionstring in src/index.ts (theMcpServer({ version: ... })call).Update top-level
versionandpackages[0].versionin server.json.Update top-level
versionandpackages[0].versionin manifest.json.Add a changeset:
pnpm changesetat repo root.Run
pnpm build && pnpm test && pnpm typecheckin this package.Run
pnpm smoke:packin this package — it packs, installs the tarball into a clean directory and checkstools/listandget-specover stdio; it must printPASSbefore you publish.
2. Publish to npm
pnpm publish --access public --no-git-checksfrom this directory.Verify:
npm view @mobile-reality/mdma-mcp version mcpName— both should match.
3. Publish to the MCP Registry
Ensure
mcp-publisheris authenticated:mcp-publisher login github(re-auth if tokens expired).mcp-publisher publishfrom this directory.Alternative: run the "Publish to MCP Registry" workflow from the Actions tab on
mainafter the npm publish. Interactivemcp-publisher login githubfails when the organization restricts OAuth apps; the workflow uses GitHub OIDC instead.
Verify:
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.MobileReality/mdma"shows the new version.
Do not commit
.mcpregistry_github_token/.mcpregistry_registry_token— they are in .gitignore. GitHub's push protection will block the push anyway; this is a belt-and-braces reminder.
4. Tag the release
git tag '@mobile-reality/mdma-mcp@<version>'
git push origin '@mobile-reality/mdma-mcp@<version>'5. Build a fresh MCPB bundle (only if submitting a Desktop Extension update)
pnpm's virtual store (.pnpm/) gets stripped by mcpb pack, so you must build the bundle from a clean npm-installed directory or transitive deps (e.g. ajv) will be missing.
Output: <name>-<version>.mcpb. Test-install in Claude Desktop, then attach as a GitHub Release asset.
6. Glama — if tool descriptions or Dockerfile config changed
If you added / renamed / changed descriptions of tools: Glama's Quality score will re-evaluate on its next periodic scan. No manual trigger.
If
packages[0].versionbumped: go to the Glama admin page → update Build steps (npm install -g @mobile-reality/mdma-mcp@<version>) → Deploy → Make Release.
7. Downstream awareness
Update the MCP tools table in the root README.md if tools were added / renamed / removed.
Update this package's own tools table (above) the same way.
If tools changed: update the MCP.so listing, which is owned by another account (see the MCP.so row in Distribution venues).
If a breaking change: note in the changeset; update consumers of
createMdmaMcpServer()if any.
Troubleshooting
MCP Registry publish fails with 403 Forbidden
If the error says permission to publish: io.github.gitsad/*, io.github.MobileReality/*. Attempting to publish: io.github.mobilereality/mdma (lowercase mismatch): the registry is case-sensitive and your mcpName / server.json name must exactly match GitHub's canonical MobileReality capitalization. Fix both files and republish to npm (versions on npm are immutable).
If the error says permission to publish: io.github.gitsad/* (org missing entirely): your MobileReality GitHub membership is private. Make it public at https://github.com/orgs/MobileReality/people, then mcp-publisher logout && mcp-publisher login github to refresh the JWT.
MCPB .mcpb crashes on install in Claude Desktop
Usually "missing module" errors in the Developer tab logs. Cause: pnpm's nested .pnpm/ virtual store got stripped at pack time, so transitive deps are missing. Fix: build the bundle from a clean npm-installed directory (see step 5 above). Do not run mcpb pack directly against packages/mcp/node_modules.
Secrets leaking into the bundle
mcpb pack does not respect .gitignore. Any .mcpregistry_*_token file next to the manifest at pack time gets zipped into the .mcpb. Always delete these before packing, and prefer the /tmp/mcpb-build workflow above which has no tokens in its directory.
Files in this package
File | Purpose | Tracked? |
TypeScript source for the server + tools. | ✅ | |
Compiled JavaScript. | ❌ (gitignored) | |
Vitest unit tests for tool logic. | ✅ | |
Contains the | ✅ | |
MCP Registry manifest consumed by | ✅ | |
MCPB (Desktop Extension) manifest. | ✅ | |
1024×1024 square icon for the MCPB submission. | ✅ | |
Screenshots bundled with the MCPB for the Claude Desktop install dialog. | ✅ | |
| Built Desktop Extension bundle (build artifact). | ❌ (gitignored) |
Available Tools
8 toolsbuild-system-promptA
Generates a custom MDMA prompt from structured input (domain, components, fields, steps). Returns only the custom prompt part — use buildSystemPrompt({ customPrompt }) in code to combine it with the base MDMA spec. When dataSources (an external data-source catalog) is passed, returns the full system prompt instead: base MDMA spec, the data-source catalog with the rule to reference it via { source, params }, and the custom part.
Inputs: steps, domain, fields, components, +2 more.
get-docA
Fetches the latest version of an MDMA documentation file from the public GitHub repo (raw.githubusercontent.com/MobileReality/mdma) and returns its contents as text. Allowed paths: any entry from list-docs, plus any *.md file under "docs/" or "blueprints/". Defaults to the "main" branch.
Inputs: path (required), ref.
get-promptA
Returns a named MDMA prompt (mdma-author, mdma-reviewer, or mdma-fixer). For mdma-author, pass an optional variantId (e.g. "anthropic/sonnet-5.5", "openai/gpt-6-sol") to get the model-optimised variant — use list-prompt-variants to see all available ids.
Inputs: name (required), variantId.
get-specB
Returns the full MDMA specification: component types, schemas (as JSON Schema), binding syntax, external data sources ({ source, params } refs, the DataSourceDescriptor shape, and the rows / series / options kinds), and authoring rules
Inputs: no named parameters.
list-docsA
Returns the catalog of MDMA documentation files available for fetching from the public GitHub repo (path, title, description). Use this to discover what docs you can pass to get-doc.
Inputs: no named parameters.
list-packagesA
Returns all MDMA npm packages with their purpose, install command, usage example, and category
Inputs: no named parameters.
list-prompt-variantsA
Returns all available MDMA_AUTHOR prompt variants with their id, label, and description. Pass the id to get-prompt as variantId to retrieve the model-optimised prompt.
Inputs: no named parameters.
validate-promptA
Validates a custom prompt against MDMA conventions. Returns warnings for anti-patterns and suggestions for improvements.
Inputs: prompt (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools target clearly distinct resources (spec, prompt, docs catalog, doc contents, packages, variants). However, get-spec, get-prompt, and build-system-prompt all revolve around producing prompt/spec text and could be confused at a glance, though the detailed descriptions clarify when each applies.
All names follow a kebab-case verb_noun pattern (get-*, list-*, build-*, validate-*), which is predictable and readable. Minor deviation only in that some names extend to three tokens (list-prompt-variants, build-system-prompt), but the convention holds.
Eight tools is well-scoped for a prompt/spec authoring assistant. Each tool earns its place, covering retrieval, generation, validation, and discovery without redundancy.
The surface covers the authoring lifecycle well: discovering docs and packages, fetching the spec, retrieving/building/validating prompts, and reading documentation. Minor gaps exist (no direct component-listing or search tool, no way to actually render/execute MDMA output), but the core workflow is covered.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP-native collaborative markdown editor with real-time AI document editing
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to discover, fetch, and search through Tambo documentation from docs.tambo.co. Provides intelligent content parsing with caching for improved performance when accessing technical documentation.41MIT
- AlicenseNot gradedqualityDmaintenanceGeneric MCP server that exposes Markdown documentation to LLMs, enabling them to search and answer questions about any software documentation.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for structured document management of markdown and YAML files, with RBAC, git-based approval workflows, and semantic search, enabling agents to read, edit, and maintain documents under governance.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes one or more documentation folders (Markdown, MDX, TXT) to AI agents, enabling listing, reading, and searching of documentation files.-