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/options kinds), and authoring rules.
get-prompt — fetch a named MDMA prompt (mdma-author, mdma-reviewer, mdma-fixer), optionally with a model-specific variantId for mdma-author.
list-prompt-variants — list all available MDMA_AUTHOR variants (id, label, description) to use with get-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 a dataSources catalog 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 optional ref for 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.
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 | 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. |
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: 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.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does most of it: it discloses the two possible return shapes (custom part only vs. full system prompt including base spec and catalog) and the downstream combinination step. It omits failure modes, input validation behavior, or any side effects, which would round out a no-annotation mutation-free generator.
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?
Purpose and inputs are front-loaded in the first clause, followed by two compact sentences covering the two return modes and the in-code combination step. Every sentence carries distinct information with no restatement of the tool name or filler.
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?
There is no output schema, so the description must explain return values — and it does so precisely for both branches (custom-only vs. full prompt with base spec and catalog). With all parameters documented at 100% coverage and the integration contract spelled out, an agent has everything needed to invoke and consume the result.
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?
Schema description coverage is 100%, so the schema already documents all six parameters in depth, including the dataSources catalog semantics and the { source, params } reference rule. The description adds framing ('external data-source catalog') and the behavioral consequence of passing it, but no syntax or format detail beyond the schema, so the baseline 3 applies.
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?
States a specific verb and resource ('Generates a custom MDMA prompt') and enumerates the structured inputs (domain, components, fields, steps) plus the conditional dataSources input. The generative framing clearly separates it from sibling read-style tools such as get-prompt and list-prompt-variants without the agent needing to open a schema.
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?
Gives concrete integration guidance ('use buildSystemPrompt({ customPrompt }) in code to combine it with the base MDMA spec') and a conditional usage rule (pass dataSources to get the full prompt instead). It never explicitly states when to prefer this over get-prompt or validate-prompt, so it stops short of naming alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the fetch target (raw.githubusercontent.com/MobileReality/mdma), that the repo is public (implying no auth), the allowed path whitelist, the 'latest version' semantics, and that content comes back as text. It omits failure behavior for a disallowed or missing path and any size/rate considerations.
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?
Three sentences, front-loaded with the verb and source, then constraints, then the default. No filler. Slightly dense but every clause carries information.
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?
No output schema exists, and the description compensates by stating the return is raw text content. Path restrictions and branch default are covered. Remaining gap is error/edge-case behavior on invalid paths, which is minor for a read-only fetch tool.
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?
Schema description coverage is 100%, so the schema already documents both 'ref' and 'path' including the 'main' default. The description restates the default branch and adds the allowed-path constraint, but adds no format or syntax detail beyond what the schema provides. Baseline 3 applies.
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?
States a specific verb and resource ('Fetches the latest version of an MDMA documentation file') plus the source location and return format. It implicitly separates itself from get-spec/get-prompt by scoping to documentation files, but never names those siblings explicitly, so differentiation requires a small inference.
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?
Gives real selection context: allowed paths are 'any entry from list-docs, plus any *.md file under docs/ or blueprints/', which routes the agent to list-docs for discovery. Missing an explicit 'use get-spec instead when you need a spec' exclusion, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden, yet it discloses almost nothing beyond the identity of the resource — no error behavior for an unknown name, no note on caching, auth, or whether the returned prompt is text or a structured object. The fallback-on-unknown-variant behavior is present only in the schema, not the description.
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?
Two tight sentences, front-loaded with the core purpose, then the conditional variant guidance. Every clause earns its place and nothing is padded.
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 simple two-parameter retrieval tool with full schema coverage and no output schema, the description covers purpose, valid inputs, and the sibling needed for variant discovery. Only the shape of the returned prompt is left unstated, which is a minor gap.
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?
Schema description coverage is 100%, so both parameters are already documented, including the fallback rule; the description largely restates this with different example variant ids. Baseline 3 is warranted because it adds little beyond the structured field text.
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?
States a specific verb and resource ('Returns a named MDMA prompt') and enumerates the three valid names, so the agent knows exactly what it fetches without opening the schema. It also implicitly distinguishes itself from retrieval siblings like get-doc/get-spec by naming the MDMA prompt domain.
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?
Gives a clear conditional rule: pass variantId only when name is mdma-author, and routes the agent to list-prompt-variants to discover valid ids. There is no explicit when-not/exclusion guidance, but the conditional covers the main decision point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the return is the full spec (unfiltered, complete) and enumerates its sections, which implies a safe read-only retrieval, but it says nothing about size or caching behavior. For a zero-parameter, zero-risk retrieval tool this is adequate but thin.
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?
A single front-loaded sentence that leads with the return value and then lists contents. The nested parenthesis with DataSourceDescriptor and the rows/series/options kinds is dense but every item earns its place as an inventory of the spec.
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?
With no output schema, the description effectively substitutes for one by enumerating the spec's sections, which is the key information an agent needs. For a parameterless reference-retrieval tool this is nearly complete; only the response format/size is unspecified.
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 takes no parameters, so there is nothing to document; baseline 4 applies. The description correctly implies no input is needed by describing only the returned content.
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?
Names a specific resource (the MDMA specification) and enumerates exactly what it contains: component types, JSON Schemas, binding syntax, DataSourceDescriptor, and authoring rules. It is distinguishable from get-doc/list-docs by content, though it never explicitly contrasts itself with those siblings.
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?
No when-to-use guidance, no prerequisites, and no mention of alternatives such as get-doc or list-docs. The agent must infer that this is the reference-spec lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a safe read-only listing and discloses the return shape, but says nothing about authentication, result size, or whether ordering is guaranteed. Adequate but thin for a listing 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?
Two sentences, zero waste. The purpose and return content come first, and the follow-up call to get-prompt is placed after, which is the right ordering.
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?
There is no output schema, so the description's enumeration of returned fields (id, label, description) is genuinely valuable. Combined with the explicit handoff to get-prompt, an agent has what it needs; only pagination/edge-case behavior is unaddressed.
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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description does not need to compensate for any parameter gap.
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?
States a specific verb (Returns) and a well-scoped resource (MDMA_AUTHOR prompt variants) and enumerates the returned fields (id, label, description). It is distinguishable from siblings like list-docs and list-packages by resource, though it does not explicitly name what it is not.
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?
Explicitly routes the agent to the next step: pass the returned id to get-prompt as variantId. That gives clear context for when to call this tool. It stops short of naming exclusions or when not to use it versus related listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the return shape (warnings for anti-patterns, suggestions for improvements) and, given there is no output schema, that is genuine added value. However it never confirms the operation is non-mutating, states failure/error behavior, or says whether validation blocks anything.
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?
Two tight sentences with the core action front-loaded and the return behavior second. Nothing is redundant, and the second sentence earns its place because no output schema exists.
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 simple single-parameter, read-style validation tool with no output schema, the description covers both what it does and what it returns, which is most of what an agent needs. It could be fuller on failure modes and on how the prompt input should be sourced.
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?
There is a single parameter and schema description coverage is 100%, so the schema already defines 'prompt' as the custom prompt text to validate. The description adds no format, size, or syntax detail beyond that, so the baseline 3 applies.
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?
States a specific verb (validates) and resource (custom prompt) and names the standard being checked (MDMA conventions), which distinguishes it from the get-prompt/build-system-prompt siblings. It stops short of explicitly contrasting itself with those siblings, so it is clear but not maximally differentiated.
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 implies usage — call it to check a prompt for anti-patterns — but never states when to use it versus alternatives like get-prompt or build-system-prompt, nor any prerequisites or exclusions. Usage is inferable from the verb but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 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.
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.
