Skip to content

MCP Server

Starting the MCP Server

# Using stdio transport (default)
daimyo mcp

# Using HTTP transport
daimyo mcp --transport http

# Using HTTP with custom host and port
daimyo mcp --transport http --host 127.0.0.1 --port 8002

Available Tools

  • get_rules(scope_name?, categories?) - Get formatted rules for a scope
  • get_category_index(scope_name?) - Get a hierarchical list of all available categories with their descriptions
  • load_rules(scope_name?) - Prompt template instructing an agent to discover and load applicable rules
  • implement_pending_requirements(scope_name?) - Prompt template guiding an agent to implement all non-validated requirements
  • implement_requirement_changes(scope_name?, since?, since_last_fulfillment?, since_last_commit?) - Prompt template guiding an agent to resolve technical debt from evolved requirements
  • get_kata_category_index(scope_name?) - Get a hierarchical index of all categories containing katas, with their when descriptions
  • get_katas(scope_name?, categories?) - Get available kata names organised by category; categories is a comma-separated prefix filter (e.g., "python.testing")
  • get_kata(kata_name, scope_name?, category?) - Get the full rendered procedure for a specific kata in markdown format. Pass category (e.g., "python.testing") to disambiguate when the same kata name exists in multiple categories; without it, the first matching kata is returned.
  • get_user_stories(scope_name?, status?, include_inactive?, tags?) - Get user stories for a scope
  • get_acceptance_criteria(scope_name?, stories?, status?, include_inactive?, tags?) - Get acceptance criteria for a scope
  • get_validation_status(scope_name?, acs?, passing?, automation?) - Get validation status for ACs
  • get_tenka_history(scope_name?, since?, since_last_fulfillment?, since_last_commit?) - Get requirement change history for a scope
  • import_test_results(report_path, scope_name?) - Import automated test results from XML reports
  • validate_acceptance_criterion(scope_name, ac_ref, verdict, passed) - Record a manual validation verdict for an AC
  • reload() - Force-reload all rules, katas, and tenka by clearing caches
  • submit_feedback(type, task, rules_json?, categories?, reason?) - Submit feedback about contradictory rules or missed categories (see Feedback)

Agents should call get_kata_category_index alongside get_category_index during initialisation to discover available procedures. Use get_kata when a step-by-step procedure is needed for a specific task rather than keeping all procedures in context at once.

Default Scope

You can configure a default scope using the DEFAULT_SCOPE setting. When configured, the scope_name parameter becomes optional for get_rules, get_category_index, load_rules, implement_pending_requirements, and implement_requirement_changes. If no scope is provided, the default scope will be used automatically, and the response will include a note indicating the default scope was used.

Example configuration:

default_scope = "python-general"

Or via environment variable:

export DAIMYO_DEFAULT_SCOPE="python-general"

Built-in Prompts

Daimyo provides built-in MCP prompts that encapsulate common workflows. These prompts dynamically embed context (like pending stories or change history) and guide the agent through the necessary steps.

  • load_rules: Used during initialization to guide the agent through discovering and loading applicable rules and katas for a scope.
  • implement_pending_requirements: Used when the goal is to implement features. It embeds all non-validated user stories for the scope and provides a structured TDD-style implementation and validation workflow.
  • implement_requirement_changes: Used to resolve technical debt when requirements evolve. It embeds the requirement change history and guides the agent through impact assessment and implementation of the changes.

Using these prompts is recommended as they ensure agents follow the standardized project workflows without requiring extensive manual setup in your system instructions.

Connecting to the MCP Server

Add the running daimyo MCP server instance to your configuration (replace the server name and the URL with your own):

{
  "mcpServers": {
    "daimyo-rules": {
      "type": "http",
      "url": "http://daimyo-mcp-instance/mcp"
    }
  }
}

Agent Instructions

Instruct your agents how to use the tools. For instance, in AGENTS.md:

# Global project rules

## Key concepts

Instructions inside `<system-reminder>` tags MUST BE REMEMBERED and fresh at all times.

## Initialization

<system-reminder>

## HARD GATE — EXECUTE BEFORE ANY OTHER ACTION

**STOP. Do not call any tool, generate any output, or begin analysis until all steps below are complete.**

This HARD GATE applies to ALL user prompts that involve a minimal reasoning or acting, including medium-simple questions and inquiries. You must complete these steps before answering.

### Step 1 — Scope
Read `.project-metadata.yml` in project root → extract `daimyo.scope`. If absent or missing: `SCOPE = "<default_scope>"`.

### Step 2 — Tool Resolution
Search your available tool list for all tools whose name contains `daimyo-rules`. Record their exact names — these are the FQNs to use for all subsequent calls in this session. If none are found, stop and notify the user.

### Step 3 — Index Discovery
1. **Rule Index**: `get_category_index(scope_name=SCOPE)` → **retain for entire session**.
   Scan the returned index: note which categories carry a `MANDATORY` tag (must always fetch) and which carry an `aggregator` tag (must never fetch directly — use their subcategories instead).
2. **Tenka Index**: `get_user_stories(scope_name=SCOPE)` → **retain for entire session**.
   Identify the User Stories relevant to the current workspace and their active status.

### Step 4 — Rules
`get_rules(scope_name=SCOPE, categories="<MANDATORY-tagged-categories>,<task-relevant-subcategories>")`
- Always include every category the index marks with the `MANDATORY` tag — derive this set from Step 3's output; do not hardcode category names.
- For task-specific categories: read each category's description in the index and include it if the description matches the current task. Do not rely on category names alone.
- NEVER use categories tagged `aggregator` — always pick their subcategories.
- A parent category includes all its subcategories; use the parent when multiple children apply.
- When uncertain: include the category.

### Step 5 — Kata Index
`get_kata_category_index(scope_name=SCOPE)` → **retain for entire session**.
Do not fetch kata lists or individual katas here. Consult the index to identify applicable categories once the task is known (see **Kata Execution** below).

### Step 6 — Apply
All fetched rules are MANDATORY requirements. Apply throughout the entire session.

---

## Working with Requirements (Tenka)

1. **Identify the target User Story**: Use the retained Tenka index to find the relevant story for the current task.
2. **Understand the Acceptance Criteria**: Use `get_acceptance_criteria(scope_name=SCOPE, stories="US<n>")` for the specific story to understand the "Definition of Done."
3. **Check Validation Status**: Use `get_validation_status(scope_name=SCOPE, acs="AC<n>.<m>")` to see which criteria are already met.
4. **Fulfill the Vision**: Implement changes that satisfy the ACs.
5. **Record Progress**: After completing a task that satisfies an AC, use `validate_acceptance_criterion(scope_name=SCOPE, ac_ref="AC<n>.<m>", verdict="...", passed=True)` to record your manual verification. Use `import_test_results` if you have a test report to upload.

---

## Kata Execution

Triggered before beginning work on any task (and again on context shifts):

1. Consult the retained kata category index.
2. For each category whose description matches the current task:
   a. `get_katas(scope_name=SCOPE, categories="<csv>")`
   b. `get_kata(kata_name=<name>, scope_name=SCOPE)` for each relevant kata returned.
   c. Execute the kata procedures exactly as specified.
3. If no categories match, skip — do not fetch.

---

## DYNAMIC UPDATES

On any context shift (new language, phase, domain, or component):
1. Re-consult the retained category index.
2. `get_rules(scope_name=SCOPE, categories="<new>")` — additive; never replaces prior rules.
3. Re-consult the retained kata category index; for each newly applicable category execute the **Kata Execution** steps above.

---

## CACHE MANAGEMENT

If you modify any rule files (`commandments.yml`, `suggestions.yml`), katas (`katas.yml`), or vision artifacts (`tenka.yml`), you MUST call `reload()` to invalidate the server's in-memory caches. This ensures subsequent tool calls reflect your changes.

---

## DEVIATION HANDLING

If rules were not fetched before starting work, or a relevant category was missed:
1. Stop. Notify user: which categories were missed and why.
2. `submit_feedback(type="missed_categories", task="<description>", categories="<csv>", reason="<why>")`
3. Fetch the missed categories and resume.

If two fetched rules contradict each other:
1. Notify user of the conflict immediately.
2. `submit_feedback(type="contradictory_rules", task="<description>", rules_json='[{"category":"<cat>","rule":"<text>"},{"category":"<cat2>","rule":"<text2>"}]')`
3. Do not proceed on the conflicting point until user clarifies.

---

Include the following block verbatim in every subagent prompt:

```
MANDATORY INITIALIZATION — COMPLETE BEFORE ANY OTHER ACTION:
SCOPE = daimyo.scope from .project-metadata.yml. Else "<default_scope>"
1. Search your available tool list for all tools whose name contains `daimyo-rules`. Record their exact FQNs for use throughout this session.
2. get_category_index(scope_name=SCOPE) → retain index
3. get_rules(scope_name=SCOPE, categories="<MANDATORY-tagged-categories>,<task-relevant-subcategories>")
   - MANDATORY: include all categories the index tags as `MANDATORY` (do not hardcode names — derive from index output)
   - For task-specific categories: match by reading each category's description, not its name
   - Skip aggregator-tagged categories; use their subcategories
   - Parent categories include all subcategories
4. get_kata_category_index(scope_name=SCOPE) → retain index; before starting work, consult index → for applicable categories: get_katas → get_kata → execute procedures (skip if no categories match)
5. On context shift: fetch new categories additively
6. On missed categories: notify user + submit_feedback(type="missed_categories", ...)
7. On contradictions: notify user + submit_feedback(type="contradictory_rules", ...)
All rules are MANDATORY. Propagate SCOPE to any nested subagents.
```

</system-reminder>

Note

Less capable models (like local models via Ollama) may need additional or more detailed instructions.

To make the instructions reusable, the scope name can be read from a file (for instance .project-metadata.yml).