This server provides AI assistants with access to the MDMA specification, authoring tools, package metadata, and live documentation.
Get the full MDMA spec (get-spec): Retrieve the complete specification including component types, JSON schemas, binding syntax, and authoring rules.
Retrieve authoring prompts (get-prompt): Fetch named prompts (mdma-author, mdma-reviewer, mdma-fixer) to guide AI in creating, reviewing, or fixing MDMA definitions. Supports model-optimised variants for mdma-author.
List prompt variants (list-prompt-variants): Discover all available variants of the MDMA_AUTHOR prompt (e.g. for Gemini, GPT-4, etc.) without fetching full content.
Build a custom system prompt (build-system-prompt): Generate a tailored MDMA prompt from structured inputs such as domain context, component types, form fields, multi-step flow definitions, and business rules.
Validate a custom prompt (validate-prompt): Check a custom prompt against MDMA conventions, receiving warnings for anti-patterns and suggestions for improvement.
List MDMA npm packages (list-packages): Browse all MDMA npm packages with their purpose, install commands, usage examples, and categories.
Discover documentation (list-docs): Get a catalog of available MDMA documentation files (paths, titles, descriptions) from the public GitHub repository.
Fetch live documentation (get-doc): Retrieve the latest content of any MDMA documentation file directly from GitHub, with optional support for a specific branch, tag, or commit SHA.
MCP (Model Context Protocol) server for MDMA. Exposes the MDMA spec, authoring prompts, package metadata, and live GitHub documentation to AI assistants.
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
{
"mcpServers": {
"mdma": { "command": "npx", "args": ["@mobile-reality/mdma-mcp"] }
}
}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 | Self-serve listing. Manual edit of Title / Description / Tags / Content on the Edit Server page. No versioned republish needed — just refresh the description if the tool set changes. | |
MCPB Desktop Extensions | Anthropic intake form | Partner queue at Anthropic. Bundle built locally; not shipped in this repo. |
Use this checklist every time you publish a new version (0.2.4 → 0.2.5, etc.).
Update version in package.json.
Update version string in src/index.ts (the McpServer({ version: ... }) call).
Update top-level version and packages[0].version in server.json.
Update top-level version and packages[0].version in manifest.json.
Add a changeset: pnpm changeset at repo root.
Run pnpm build && pnpm test && pnpm typecheck in this package.
Run pnpm smoke:pack in this package — it packs, installs the tarball into a clean directory and checks tools/list and get-spec over stdio; it must print PASS before you publish.
pnpm publish --access public --no-git-checks from this directory.
Verify: npm view @mobile-reality/mdma-mcp version mcpName — both should match.
Ensure mcp-publisher is authenticated: mcp-publisher login github (re-auth if tokens expired).
mcp-publisher publish from this directory.
Alternative: run the "Publish to MCP Registry" workflow from the Actions tab on main after the npm publish. Interactive mcp-publisher login github fails 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.
git tag '@mobile-reality/mdma-mcp@<version>'
git push origin '@mobile-reality/mdma-mcp@<version>'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.
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].version bumped: go to the Glama admin page → update Build steps (npm install -g @mobile-reality/mdma-mcp@<version>) → Deploy → Make Release.
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: refresh the manual listing on MCP.so (Edit Server → Description / Content).
If a breaking change: note in the changeset; update consumers of createMdmaMcpServer() if any.
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 crashes on install in Claude DesktopUsually "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.
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.
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) |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | No | Multi-step flow definitions — each step becomes a separate conversation turn | |
| domain | No | Domain context (e.g. "HR onboarding", "expense approval") | |
| fields | No | Form field definitions | |
| components | No | Component types to use (e.g. ["form", "approval-gate", "webhook"]) | |
| dataSources | No | External data-source catalog. Each entry: name, optional description, kind ("rows" for table.data, "series" for chart.data, "options" for form select options), optional columns [{ key, type: string|number|boolean|date, description?, sensitive? }], optional params [{ name, type: string|number|boolean, required?, allowed? }]. Names must be unique, but the same data may appear as a rows and a series entry under different names. The model is told to reference sources via { source, params } instead of generating rows. | |
| businessRules | No | Business rules or constraints |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Git ref (branch, tag, or commit SHA). Defaults to "main". | |
| path | Yes | Repo-relative path to the doc, e.g. "docs/getting-started/quick-start.md" or "blueprints/kyc-case/README.md" |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Prompt name: mdma-author, mdma-reviewer, or mdma-fixer | |
| variantId | No | Model-specific variant id for mdma-author (e.g. "google/gemini-2.5-pro", "openai/gpt-5"). Falls back to the default variant if omitted or unknown. |
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
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It effectively describes the tool's behavior: it returns a catalog with specific fields (path, title, description) from a public GitHub repository. However, it doesn't mention potential limitations like rate limits, authentication requirements, or pagination behavior, which would be valuable for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does and what it returns, the second explains when to use it. There is zero wasted language or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation with no annotations and no output schema, the description provides good context about what the tool returns (catalog with path, title, description) and its relationship to other tools. However, without an output schema, additional details about the return format structure would be helpful for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline would be 4. The description appropriately doesn't waste space discussing parameters that don't exist, maintaining focus on the tool's purpose and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Returns the catalog'), resource ('MDMA documentation files'), and scope ('available for fetching from the public GitHub repo'). It explicitly distinguishes from its sibling 'get-doc' by explaining this tool is for discovery while 'get-doc' is for fetching specific documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Use this to discover what docs you can pass to get-doc') and names the alternative tool ('get-doc') for the subsequent action. This clearly establishes the workflow relationship between these two tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns all MDMA npm packages with their purpose, install command, usage example, and category
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it states what data is returned, it doesn't describe important behavioral aspects like whether results are paginated, sorted, filtered, or cached. It also doesn't mention performance characteristics, error conditions, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a zero-parameter tool and front-loads the essential information about what the tool returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation with no output schema, the description adequately covers what data is returned. However, it lacks important contextual information about the return format (array structure, field types), potential limitations (number of packages, sorting), and how this tool relates to sibling tools in the MDMA ecosystem.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't waste space discussing non-existent parameters, though it could theoretically mention that no filtering options are available.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Returns') and resource ('all MDMA npm packages'), including the exact data fields returned (purpose, install command, usage example, category). It distinguishes itself from siblings like 'list-docs' by focusing specifically on npm packages rather than documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate versus using 'get-doc' or 'list-docs', nor does it specify any prerequisites or contextual constraints for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Validates a custom prompt against MDMA conventions. Returns warnings for anti-patterns and suggestions for improvements.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The custom prompt text to validate |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2build-system-prompt4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dataSourcesAdded value: +{
+ "description": "External data-source catalog. Each entry: name, optional description, kind (\"rows\" for table.data, \"series\" for chart.data, \"options\" for form select options), optional columns [{ key, type: string|number|boolean|date, description?, sensitive? }], optional params [{ name, type: string|number|boolean, required?, allowed? }]. Names must be unique, but the same data may appear as a rows and a series entry under different names. The model is told to reference sources via { source, params } instead of generating rows.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "columns": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "key": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "sensitive": {
+ "default": false,
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "date"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "key",
+ "type"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "description": {
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "options",
+ "rows",
+ "series"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "params": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "allowed": {
+ "items": {
+ "type": [
+ "string",
+ "number",
+ "boolean"
+ ]
+ },
+ "type": "array"
+ },
+ "name": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "required": {
+ "default": false,
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "type"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "name",
+ "kind"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Input schema / properties / fields / items / additionalPropertiesAdded value: +falseInput schema / properties / steps / items / additionalPropertiesAdded value: +falseget-doc1 field changedInput schema / additionalPropertiesAdded value: +falseget-prompt2 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / variantIdAdded value: +{
+ "description": "Model-specific variant id for mdma-author (e.g. \"google/gemini-2.5-pro\", \"openai/gpt-5\"). Falls back to the default variant if omitted or unknown.",
+ "type": "string"
+}list-prompt-variantsvalidate-prompt1 field changedInput schema / additionalPropertiesAdded value: +falsev0.1.0build-system-promptget-docget-promptget-speclist-docslist-packagesvalidate-promptScored across 7 tools
Each tool has a distinct, non-overlapping purpose: build-system-prompt creates prompts, get-doc fetches documentation, get-prompt retrieves named prompts, get-spec provides the full specification, list-docs catalogs available docs, list-packages lists npm packages, and validate-prompt validates custom prompts. The descriptions clearly differentiate their functions, eliminating ambiguity.
All tools follow a consistent verb_noun naming pattern (e.g., build-system-prompt, get-doc, list-docs, validate-prompt). The naming is uniform across all seven tools, with no mixing of conventions like camelCase or snake_case, making it highly predictable and readable.
With 7 tools, the count is well-scoped for the MDMA domain, covering key operations like prompt generation, documentation retrieval, specification access, and validation. Each tool serves a clear purpose without redundancy, and the set feels complete yet not overwhelming for the server's scope.
The tool set provides comprehensive coverage for MDMA-related tasks, including prompt building, documentation access, specification retrieval, and validation. Minor gaps exist, such as no tools for updating or deleting prompts or docs, but agents can work around this using the available tools for core workflows like authoring and reviewing.
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.
