Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@maid-runner-mcp validate the manifest for task-013"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol server for MAID Runner validation tools.
MAID Runner MCP exposes MAID Runner validation capabilities via the Model Context Protocol (MCP), enabling seamless integration with AI development tools like Claude Code, Aider, and custom AI agents.
MAID Runner MCP is a bridge between AI agents and MAID Runner's validation framework. It provides:
MCP Tools: Programmatic access to maid validate, maid snapshot, maid test, and other commands
MCP Resources: Access to manifests, schemas, validation results, and system architecture
MCP Prompts: Workflow guidance for AI agents through MAID methodology phases
Think of it as an API layer that lets AI agents interact with MAID Runner using standardized MCP protocol instead of subprocess calls.
Related MCP server: mcp_server_for_claudes_toolbox
🚧 Alpha Release - Under active development.
This is part of the MAID ecosystem and follows the MAID methodology itself (self-dogfooding).
# Install from PyPI
pip install maid-runner-mcp
# Or with uv
uv pip install maid-runner-mcp# Start MCP server (stdio transport)
maid-runner-mcp
# Or with uv
uv run maid-runner-mcpAdd to your .claude/mcp.json:
{
"mcpServers": {
"maid-runner": {
"command": "uv",
"args": ["run", "maid-runner-mcp"],
"env": {
"MAID_MANIFEST_DIR": "manifests"
}
}
}
}Now Claude Code can:
Validate manifests via maid_validate tool
Generate snapshots via maid_snapshot tool
Access manifest content via manifest:// resources
Get workflow guidance via prompts
AI Agents (Claude, GPT-4, etc.)
↓
MCP Protocol (JSON-RPC)
↓
maid-runner-mcp (MCP Server)
↓
MAID Runner (Validation Core)maid_validate - Validate manifests (structural + behavioral + implementation)
maid_snapshot - Generate manifest snapshots from existing code
maid_snapshot_system - Generate system-wide architecture snapshot
maid_list_manifests - Find manifests referencing a file
maid_init - Initialize MAID project structure
maid_get_schema - Get manifest JSON schema
maid_generate_stubs - Generate test stubs from manifest
maid_files - Check file tracking status
manifest://{name} - Access manifest content
schema://manifest - Get manifest JSON schema
validation://{name}/result - Access cached validation results
snapshot://system - Get system-wide architecture snapshot
graph://query - Query manifest knowledge graph
file-tracking://analysis - Get file tracking status
plan-task - Guide AI through manifest creation
implement-task - Guide AI through implementation
refactor-code - Guide AI through safe refactoring
review-manifest - Guide AI through manifest review
Component | Role | What It Does |
MAID Runner | Validation framework | CLI tool for validating MAID manifests |
MAID Runner MCP | MCP interface | Exposes MAID Runner to AI agents via MCP |
MAID Runner MCP doesn't replace the CLI—it complements it:
CLI (maid): For humans and shell scripts
MCP (maid-runner-mcp): For AI agents and programmatic access
Both use the same underlying validation logic.
AI agents can validate code as they generate it:
# AI agent workflow
result = await session.call_tool("maid_validate", {
"manifest_path": "manifests/task-013.manifest.json",
"use_manifest_chain": true
})
if not result["success"]:
# Fix issues based on errors
...AI agents can understand system architecture:
# Get system snapshot
snapshot = await session.read_resource("snapshot://system")
# Query knowledge graph
results = await session.read_resource(
"graph://query?type=class&name=EmailValidator"
)Custom agents can automate MAID workflow:
# Get planning guidance
prompt = await session.get_prompt("plan-task", {
"goal": "Add email validation"
})
# Follow prompt to create manifest
...# Clone repository
git clone https://github.com/mamertofabian/maid-runner-mcp
cd maid-runner-mcp
# Install dependencies
uv pip install -e ".[dev]"
# Run tests
pytest tests/ -vmake install # Install package
make test # Run tests
make lint # Check code style
make format # Format code
make validate # Validate MAID manifestsThis project follows the MAID methodology itself:
All changes have manifests in manifests/
All features have behavioral tests in tests/
Validation enforced via maid validate --use-manifest-chain
See CLAUDE.md for development guidelines.
See CONTRIBUTING.md for development workflow and guidelines.
MIT License - see LICENSE file.
MAID Runner - Core validation framework
MAID Agents - Claude Code automation
Get file-level tracking status using MAID Runner.
When to use:
Project health check: See which files lack manifests
Onboarding: Identify files that need to be brought under MAID
Compliance audit: Ensure all source files are tracked
Status categories:
undeclared: Files not referenced in any manifest (needs attention)
registered: Files in manifests but with potential issues
tracked: Files fully compliant with MAID methodology
Tips:
Use issues_only=True to focus on problem files
Filter by status="undeclared" to find files needing manifests
Run periodically to maintain MAID compliance
Args: manifest_dir: Directory containing manifests (default: "manifests") issues_only: If True, only show files with issues status: Filter by status (e.g., "undeclared", "registered", "tracked")
Returns: FileTrackingResult with categorized files
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_dir | No | manifests | |
| issues_only | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| undeclared | Yes | |
| registered | Yes | |
| tracked | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It describes the return categories and suggests periodic use, implying a read-only non-destructive operation. However, it does not explicitly state whether the tool modifies any state or requires specific permissions, but the context suggests a safe query.
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 well-structured with headers, bullet points, and an args list. It is concise yet informative, with no redundant sentences. Could be slightly tighter, but overall efficient.
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?
Given the moderate complexity (3 optional params, output schema exists), the description covers purpose, usage, parameters, and return values. It lacks explicit error handling or edge cases but is sufficient for an AI agent.
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?
With 0% schema description coverage, the description compensates by explaining all three parameters in the 'Args' section: manifest_dir, issues_only, and status. It provides defaults and the effect of each parameter, adding meaning beyond the schema types.
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 verb 'Get' and the resource 'file-level tracking status using MAID Runner'. The status categories are explained, distinguishing it from sibling tools like maid_list_manifests or maid_validate.
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?
Explicit 'When to use' section with specific scenarios (project health check, onboarding, compliance audit) plus tips on filtering. This provides strong guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate test stubs from a manifest using MAID Runner.
When to use:
Phase 2 (Planning): After creating manifest, generate test file skeleton
Jumpstarting tests: Create boilerplate test structure from manifest
Consistency: Ensure test file naming matches manifest conventions
What it generates:
Test file with naming pattern: tests/test_task_XXX_*.py
Test class structure based on expectedArtifacts
Import statements for artifacts being tested
Placeholder test methods for each artifact
Tips:
Run after creating/updating a manifest
Generated stubs are starting points - add assertions
Test file is added to manifest's readonlyFiles automatically
Args: ctx: MCP context containing session and roots information manifest_path: Path to the manifest JSON file
Returns: GenerateStubsResult with generation outcome
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_path | Yes |
| Name | Required | Description |
|---|---|---|
| success | Yes | |
| manifest_path | Yes | |
| generated_files | Yes | |
| errors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes what is generated (naming, class structure, imports, placeholder methods) and that the test file is automatically added to the manifest's readonlyFiles. Lacks details on error handling but is sufficiently transparent.
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?
Well-structured with clear sections (When to use, What it generates, Tips, Args, Returns). Every sentence adds value; no wasted words.
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?
Given the output schema exists, the description appropriately explains the generation outcome. The tool's single parameter is well-contextualized, and the usage guidance makes it easy for an agent to decide when to use this 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 coverage is 0%, but the description includes an 'Args' section that explains 'manifest_path: Path to the manifest JSON file', adding meaning beyond the schema's type-only definition.
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 'Generate test stubs from a manifest using MAID Runner.' It specifies the verb and resource, and the tool's purpose is distinct from sibling tools like 'maid_validate' or 'maid_snapshot'.
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 lists when to use (Phase 2 Planning, jumpstarting tests, consistency) and provides tips (run after creating/updating manifest). Differentiates itself well without needing to list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the MAID manifest JSON schema.
When to use:
Phase 2 (Planning): Understand manifest structure before creating one
Debugging: Verify manifest fields are correctly named and typed
Learning: Explore available manifest options
Key information in schema:
Required fields: goal, readonlyFiles, expectedArtifacts/systemArtifacts
File lists: creatableFiles, editableFiles, readonlyFiles
Artifact types: function, class, attribute, etc.
Validation commands: validationCommand or validationCommands
Tips:
Review schema before writing your first manifest
Use schema to validate manifest structure
Check artifact type options for expectedArtifacts.contains[]
Args: ctx: MCP context for accessing client roots
Returns: SchemaResult with the manifest schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| success | Yes | |
| json_schema | Yes | |
| errors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the return type (SchemaResult with manifest schema) but does not explicitly confirm it is read-only or safe. However, the tool's purpose implies no side effects, so the description is adequate but not thorough.
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 well-structured with clear sections for usage, key information, and tips. It is slightly longer than necessary but every sentence adds useful context. Front-loading with the main purpose is effective.
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?
Given the tool's simplicity (no parameters, output schema exists), the description covers all necessary aspects: when to use, what the schema contains, and tips. It is complete for an agent to understand and invoke the tool correctly.
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 input schema has zero parameters, and the description provides no parameter details (none needed). According to the baseline rule for 0 params, the score is 4. The description adds value by explaining the return content and context.
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 tool retrieves the MAID manifest JSON schema, with a specific verb and resource. It distinguishes itself from siblings by explaining its role in understanding manifest structure before other operations like validation or creation.
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 explicitly lists when to use the tool in Phase 2 (Planning), debugging, and learning contexts. Although it doesn't state when not to use it, the context is clear and aligns with typical use cases for a schema retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a MAID project using MAID Runner.
When to use:
Starting a new project: Set up MAID directory structure
Onboarding existing project: Add MAID support to existing codebase
Resetting: Use force=True to reinitialize
What it creates:
manifests/ directory for task manifests
.maid/ directory for MAID configuration
Basic MAID project structure
Tips:
Run once at project setup
Use force=True only if you need to reset MAID configuration
Args: target_dir: Directory to initialize (defaults to current directory) force: Whether to force initialization even if already initialized
Returns: InitResult with initialization outcome
| Name | Required | Description | Default |
|---|---|---|---|
| target_dir | No | . | |
| force | No |
| Name | Required | Description |
|---|---|---|
| success | Yes | |
| target_dir | Yes | |
| errors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully handles behavioral disclosure, detailing what it creates (directories), tips (run once), and return type. Could expand on potential side effects of force=True.
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 well-structured with clear sections, concise sentences, and no redundant information. Every sentence adds value.
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?
Despite no annotations and a low schema coverage, the description covers purpose, usage, effects, parameters, and return type comprehensively. Output schema exists but its absence in the prompt doesn't reduce 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?
Schema description coverage is 0%, but the description adds meaningful explanations for both parameters (target_dir, force) beyond the schema's defaults and types, aiding correct invocation.
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 tool initializes a MAID project, listing its verb-init, resource-project, and scope. It distinguishes from siblings by focusing on initialization vs. file listing or validation.
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?
Provides explicit when-to-use scenarios (starting new project, onboarding, resetting) and when to use force=True. However, it doesn't explicitly mention when NOT to use it or compare with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List manifests that reference a file using MAID Runner.
When to use:
Before editing: Check if a file already has manifests
Understanding history: See how a file has evolved through manifests
Planning edits: Find related manifests to understand context
Result categories:
created_by: Manifests where file is in creatableFiles
edited_by: Manifests where file is in editableFiles
read_by: Manifests where file is in readonlyFiles
Tips:
Use before creating a new manifest for an existing file
If file is in creatableFiles, it was first created by that manifest
Use --use-manifest-chain in maid_validate for files with history
Args: file_path: Path to the file to check manifest_dir: Directory containing manifests (default: "manifests")
Returns: ListManifestsResult with manifest information
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| manifest_dir | No | manifests |
| Name | Required | Description |
|---|---|---|
| file_path | Yes | |
| total_manifests | Yes | |
| created_by | Yes | |
| edited_by | Yes | |
| read_by | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains result categories (created_by, edited_by, read_by) but does not mention any side effects, permissions, or rate limits. For a read-only listing tool, this is acceptable but not thorough.
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 concise (about 10 lines) and well-structured with headings for purpose, usage, result categories, tips, and arguments. Every sentence adds value, and the most important information is front-loaded.
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?
The description is reasonably complete for a list tool: it explains what the tool returns (ListManifestsResult) and categorizes results. The presence of an output schema is acknowledged. However, it could mention pagination or handling of missing files.
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 input schema has 0% description coverage, but the description's Args section adds brief but sufficient meaning: 'file_path: Path to the file to check' and 'manifest_dir: Directory containing manifests (default: manifests)'. This compensates for the schema 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?
The description clearly states 'List manifests that reference a file', specifying both the action (list) and the resource (manifests referencing a file). This is distinct from sibling tools like maid_files or maid_validate, making it easy for an agent to select the correct tool.
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 'When to use' bullets covering before editing, understanding history, and planning edits. While it does not state when NOT to use or name specific alternatives, the context is clear and helpful for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a manifest snapshot from existing code using MAID Runner.
When to use:
Onboarding existing code: Create manifests for pre-existing files
Before refactoring: Capture current state as a baseline
Documentation: Generate manifest to document existing APIs
Key behavior:
Analyzes source file to extract public artifacts (functions, classes)
Creates a manifest with expectedArtifacts matching current code
Optionally generates test stub file for the manifest
Tips:
Use before making changes to existing code without manifests
The generated manifest serves as a "snapshot" of current state
Review and adjust the generated manifest as needed
Args: file_path: Path to the source file to generate a snapshot for output_dir: Directory to output the manifest (default: "manifests") force: Whether to overwrite existing manifest files skip_test_stub: Whether to skip generating test stub file
Returns: SnapshotResult with generation outcome
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| output_dir | No | manifests | |
| force | No | ||
| skip_test_stub | No |
| Name | Required | Description |
|---|---|---|
| success | No | |
| manifest_path | No | |
| test_stub_path | No | |
| superseded_manifests | No | |
| errors | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It details key behaviors: analyzing source files, extracting artifacts, creating manifests, and optionally generating test stubs. This fully discloses the tool's actions.
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 well-structured with sections, bullet points, and a clear 'Args' list. Every sentence adds value, and the length is appropriate for the tool's complexity.
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?
Given the output schema exists, return values are briefly covered. The description covers usage, behavior, and parameters comprehensively. Minor omission: no mention of prerequisites (e.g., MAID Runner installation) or error handling, but overall complete for an agent to use correctly.
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?
With 0% schema description coverage, the description compensates fully by listing each parameter (file_path, output_dir, force, skip_test_stub) with clear explanations of their purpose and defaults. This adds significant meaning beyond the raw schema.
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 tool generates a manifest snapshot from existing code using MAID Runner. It specifies the resource (manifest snapshot) and action (generate), and differentiates from siblings like maid_snapshot_system by focusing on per-file snapshots.
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?
Provides an explicit 'When to use' section with three concrete scenarios (onboarding, refactoring, documentation) and 'Tips' with actionable advice. This gives clear guidance on when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a system-wide manifest snapshot using MAID Runner.
When to use:
Documentation: Create a comprehensive view of all project artifacts
Architecture review: See all public APIs across the codebase
Dependency analysis: Understand cross-file relationships
What it creates:
Aggregated manifest combining all individual manifests
System-wide view of all tracked artifacts
Uses systemArtifacts (array) instead of expectedArtifacts (object)
Tips:
Run periodically to update system documentation
Useful for onboarding new team members
Compare snapshots over time to track API evolution
Args: output: Path to the output system manifest file (default: "system.manifest.json") manifest_dir: Directory containing individual manifests (default: "manifests") quiet: Whether to suppress progress output (default: True)
Returns: SystemSnapshotResult with generation outcome
| Name | Required | Description | Default |
|---|---|---|---|
| output | No | system.manifest.json | |
| manifest_dir | No | manifests | |
| quiet | No |
| Name | Required | Description |
|---|---|---|
| success | Yes | |
| output_path | Yes | |
| errors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes output as aggregated manifest using systemArtifacts array instead of expectedArtifacts object, and mentions return type. No annotations exist, so description carries burden; it does not disclose side effects, auth needs, or potential destructive actions, but given nature of tool, likely non-destructive.
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?
Well-organized with headings, bullet points, and sections. The Args section duplicates schema info without adding value, slightly reducing conciseness.
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?
Covers purpose, usage, and high-level output. Lacks parameter details and behavioral nuances. Output schema exists but not described, so completeness is adequate but not thorough.
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 coverage is 0%, so description should compensate. Args are listed with defaults but no additional explanation of formats, constraints, or how they affect behavior. Barely adds meaning beyond schema.
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?
Clearly states it generates a system-wide manifest snapshot. Use cases like documentation, architecture review, and dependency analysis distinguish it from siblings like maid_snapshot (per-file) and maid_list_manifests.
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?
Provides explicit 'When to use' section with three bullet points. Also includes tips for periodic runs and onboarding. Lacks explicit when-not-to-use, but usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a MAID manifest using MAID Runner.
When to use:
Phase 2 (Planning): After creating/updating a manifest, validate it passes
Phase 3 (Implementation): After writing code, verify it matches the manifest
Before committing: Ensure all manifests are valid
Validation modes:
implementation: Checks that code artifacts match manifest expectedArtifacts
behavioral: Checks that tests exist and reference the expected artifacts
schema: Checks that the manifest structure conforms to the JSON schema
Use manifest chain when:
Editing existing files (taskType: "edit")
The file has previous manifests that define its history
You need to verify the full history of changes is valid
Args: manifest_path: Path to the manifest JSON file validation_mode: Validation mode (implementation, behavioral, or schema) use_manifest_chain: Whether to use manifest chain for validation manifest_dir: Directory containing manifests (optional) quiet: Whether to suppress verbose output ctx: MCP context for accessing working directory
Returns: ValidateResult with validation outcome
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_path | Yes | ||
| validation_mode | No | implementation | |
| use_manifest_chain | No | ||
| manifest_dir | No | ||
| quiet | No |
| Name | Required | Description |
|---|---|---|
| success | No | |
| mode | No | |
| manifest | No | |
| target_file | No | |
| used_chain | No | |
| errors | No | |
| file_tracking | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses validation modes, behavior for editing files, and return type. Lacks mention of side effects, but validation is likely read-only. Good transparency overall.
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?
Well-structured with headings and bullet points, but some redundancy (e.g., 'Validation modes' could be tighter). Still concise and easy to scan.
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?
Covers all necessary aspects: purpose, usage guidelines, parameter explanations, and return value. With output schema present, the description is complete for an agent to use correctly.
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 0%, but the description explains each parameter: manifest_path, validation_mode (with options), use_manifest_chain, manifest_dir, quiet. Adds significant meaning beyond the schema.
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 'Validate a MAID manifest using MAID Runner', specifying the verb and resource. It distinguishes from siblings like maid_files and maid_init, which have different purposes.
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?
Explicit guidance on when to use: Phase 2 and 3, before committing. Also covers validation modes and manifest chain usage, providing clear context for selection.
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.2.0maid_filesmaid_generate_stubsmaid_get_schemamaid_initmaid_list_manifestsmaid_snapshotmaid_snapshot_systemmaid_validateScored across 8 tools
Each tool has a clearly distinct purpose: file tracking, stub generation, schema retrieval, initialization, manifest listing per file, snapshot of a single file, system-wide snapshot, and validation. There is no overlapping functionality.
All tools follow the 'maid_' prefix with a verb_noun pattern (e.g., maid_generate_stubs, maid_list_manifests). The naming is consistent, descriptive, and predictable across all 8 tools.
With 8 tools, the server is well-scoped for the MAID domain. It covers initialization, analysis, validation, stubbing, and tracking without being overly numerous or sparse.
The tools cover the core MAID workflow (init, snapshot, validate, generate stubs, track files, list manifests). However, there is no tool to list all manifests (only per file) or to delete/clean up manifests, which are minor gaps.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Build, validate, and manage API simulations in WireMock Cloud from MCP-compatible AI agents.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
