---
name: mcp-topo
description: |
  Design an MCP server's tool surface by analyzing an API and proposing interaction categories.
  Produces a plan consumable by /mob:swarm for implementation.
user-invocable: true
argument-hint: <openapi-spec.yaml | codebase-path | url> [--name <server-name>]
---

You are the orchestrator of an MCP server design session. Your job is to transform an API surface into a minimal set of intent-driven MCP tools organized by interaction categories.

The primary consumer of MCP tools is an AI model. AI models benefit from fewer, broader tools with clear intent over many narrow, endpoint-shaped tools. A 1:1 mapping of API endpoints to MCP tools is the default instinct and it is wrong — it forces the AI to understand the API's implementation topology instead of its problem domain.

This skill exists to do the design thinking that most teams skip. You will analyze an API surface, propose interaction categories discovered from the specific API (not from a fixed taxonomy like CRUD), and produce a plan that `/mob:swarm` can implement.

---

## Setup

### Parse Arguments

- First argument: the input source (required). One of:
  - Path to an OpenAPI/Swagger spec (`.yaml`, `.yml`, or `.json` file)
  - Path to a codebase directory
  - A URL (fetch with WebFetch to retrieve a spec or docs page)
- `--name <server-name>` (optional): name for the MCP server. Used in output filenames (`plans/mcp-<name>.md`). If omitted, infer from the input source or ask the user.

**This skill requires a concrete API surface.** Natural language descriptions ("a Slack-like messaging API") are not sufficient input. If the user provides a description instead of a spec, codebase, or URL, tell them: "I need an OpenAPI spec, a codebase with route definitions, or a URL to API documentation. A description alone doesn't give me the endpoint-level detail needed to design the tool surface."

**Detection logic:**
- Starts with `http://` or `https://` → URL. Fetch with WebFetch. If the response is an OpenAPI spec, parse it. If it's HTML, extract API information from the content. If the content doesn't contain enough endpoint-level detail, tell the user what's missing.
- Ends with `.yaml`, `.yml`, or `.json` → likely an OpenAPI spec. Read the file and verify it is an OpenAPI/Swagger document (look for `openapi:`, `swagger:`, or `paths:` at the top level). If the file is valid JSON/YAML but not an OpenAPI spec (e.g., `package.json`, `tsconfig.json`), tell the user: "This file is not an OpenAPI spec. If this is a codebase, point me at the project directory instead."
- Is a directory → codebase. Explore route definitions, controllers, handlers, API clients, README files.

### Check for Existing State

Look for `.mcp-topo-state.json` in the project root. If it exists:

- Read it and **validate integrity first**: verify the file is valid JSON with a `status` field whose value is one of the valid status values. For the current status, verify that the fields required by that phase exist (e.g., `"hypothesizing"` requires `capabilities`; `"reviewing"` requires `proposed_categories`). If the state file is malformed or missing required fields, tell the user: "The state file exists but is corrupted or incomplete. Would you like to restart from scratch, or should I attempt to recover from the last valid phase?" If they choose restart, delete the state file and begin at `"intake"`.
- If the state file references a different server name, warn the user before proceeding
- If `status` is `"complete"`, inform the user the design is finalized and ask if they want to revise
- If `status` is `"intake"`, present any captured context and ask if the user wants to continue or restart
- If `status` is `"scoping"`, check `endpoint_count` in the state file. If `endpoint_count` is present and ≤30, skip Phase 1.5 — set status to `"analyzing"` and proceed to Phase 2. Otherwise, check the `domains` field. If domains have been identified (`domains.all` is populated), present them and any scope decisions. If `domains` is null or `domains.all` is empty, domain identification hasn't completed — resume Phase 1.5 from the beginning.
- If `status` is `"analyzing"`, check if capabilities were captured. If so, proceed to Phase 3 (Hypothesis). If not, resume Phase 2 (Surface Analysis).
- If `status` is `"hypothesizing"`, check if proposed categories exist. If so, proceed to Phase 4 (Guided Review). If not, resume Phase 3.
- If `status` is `"reviewing"`, present the current proposal and any user feedback history. Ask the user how to proceed.
- If `status` is `"outputting"`, check if the plan file exists. If so, the design is complete — update status to `"complete"`. If not, resume Phase 5.

If no state file exists, create one now with `status: "intake"`.

---

## Phase 1: Intake

Understand the API surface and what the MCP server is for.

### Parse the Input

Based on the detected input type:

**OpenAPI spec:** Read the file. Extract all paths, HTTP methods, operation IDs, request/response schemas, parameter definitions, and descriptions. Note authentication schemes and base URLs.

**Codebase:** Explore the directory structure. Look for route definitions, controller/handler files, API client modules, service layers, and README files. Build a picture of the API surface from the code — what endpoints exist, what they accept, what they return.

**URL:** Fetch the URL with WebFetch. Handle failure cases:
- **Timeout or network error:** Tell the user the URL is unreachable and ask for an alternative (a local file or a different URL).
- **Authentication required (401/403):** Tell the user the URL requires authentication that WebFetch cannot provide. Ask them to download the spec locally and provide the file path instead.
- **Redirect chains:** Follow redirects. If the final response is unusable, report the final URL and ask for guidance.
- **Unusable content:** If the response is neither an OpenAPI spec nor HTML with identifiable API documentation (endpoint paths, methods, parameters), tell the user what was returned and ask for a better source. Do not guess at an API surface from ambiguous content.

If the response is structured (OpenAPI spec), parse as above. If it's HTML documentation with clear endpoint-level detail, extract endpoint descriptions, parameters, and response formats from the content.

### Mandatory Questions

Ask the user these two questions. Do not proceed without answers.

1. **"Who or what is the MCP consumer? What kind of agent or workflow will use these tools?"**

   This shapes everything. A coding assistant needs different tool groupings than a data analysis agent. A customer support bot needs different groupings than an autonomous deployment pipeline. The consumer's tasks determine the interaction categories.

2. **"What problems does this MCP server solve? What tasks should the consumer be able to accomplish?"**

   This anchors the design in intent rather than capability. The answer to "what tasks?" determines how capabilities get grouped. Without this, the design will drift toward entity-based grouping (which is 1:1 mapping with extra steps).

### Optional Follow-Ups

Based on what's unclear from the input and the user's answers, ask targeted follow-up questions. Do not over-interview — 2-3 exchanges maximum. The goal is to understand the consumer's tasks well enough to group capabilities by intent.

Useful follow-ups when needed:
- "Are there tasks that require multiple API calls in sequence? Which ones?"
- "Are there operations the consumer should never perform without explicit confirmation?"
- "Is there a subset of the API that the consumer will never need?"

### Update State

Write `.mcp-topo-state.json` with `status: "scoping"`. Store the input metadata, consumer context, and `endpoint_count` (the total number of endpoints detected from the input). The endpoint count is needed for deterministic recovery — it determines whether Phase 1.5 runs or is skipped.

---

## Phase 1.5: Scope Narrowing (Large APIs)

**When to run this phase:** If `endpoint_count` is more than 30, run this phase. If it is 30 or fewer, skip directly to Phase 2 and set status to `"analyzing"`.

Large APIs (GitHub, Stripe, AWS) span many domains. Analyzing 200+ endpoints as a flat list produces unusable results — the capabilities list overwhelms the context, the categories become too numerous, and the user can't meaningfully review the design.

### Identify Domains

Group the API surface into domains — high-level functional areas. For an API like GitHub, these might be: Repositories, Issues, Pull Requests, Actions/CI, Packages, Organizations, Teams, Code Search, Projects, Discussions, etc.

**How to identify domains from the input:**

**OpenAPI spec:** Look for tags (most specs group endpoints by tag), path prefixes (`/repos/`, `/issues/`, `/orgs/`), or the spec's own section organization.

**Codebase:** Explore the project structure for domain signals:
1. **Directory structure**: route/controller directories often mirror domains (`routes/repos/`, `handlers/issues/`, `controllers/billing/`)
2. **Module boundaries**: look for service layers, model files, or package organization that groups related functionality
3. **README or docs**: many projects describe their API surface by domain in documentation
4. **Import/dependency graphs**: modules that import each other heavily are likely in the same domain

If the domain boundaries are unclear from the code, default to grouping by the primary entity each endpoint operates on.

For each domain, note:
- Approximate number of endpoints
- Whether the user's consumer tasks (from Phase 1) reference this domain
- Whether this domain is a dependency of a referenced domain (e.g., the consumer needs PRs, and PRs depend on Repos)

### Present Scope Decision

Present the domains to the user:

```
## API Domains

This API spans the following domains:

| Domain | ~Endpoints | Referenced by consumer tasks? |
|--------|-----------|-------------------------------|
| Repositories | 25 | Yes (project setup) |
| Issues | 18 | Yes (bug tracking) |
| Pull Requests | 22 | Yes (code review) |
| Actions | 30 | No |
| Packages | 12 | No |
| ... | ... | ... |

Based on your consumer's tasks, I recommend including: Repositories, Issues, Pull Requests, [others].

Which domains should the MCP server cover?
```

The user selects domains. If they select everything, warn them that the tool surface will be large and suggest prioritizing.

### Update State

Write state with `status: "analyzing"`. Store the selected domains and the domain-endpoint mapping.

---

## Phase 2: Surface Analysis

This phase is internal work. Do not present results to the user — the raw capability list is not useful to them. The hypothesis (Phase 3) is what they need to see.

### Enumerate Capabilities

Extract every discrete capability from the API surface (within the selected domains, if Phase 1.5 was run) as a flat list. Each capability is one thing that can be done — one endpoint, one function, one operation.

For each capability, record:

| Field | Description |
|-------|-------------|
| `id` | Sequential identifier: CAP-1, CAP-2, etc. |
| `capability` | What it does in plain language: "create a repository", "list pull requests", "merge a branch" |
| `entity` | The domain object acted on: "repository", "pull request", "branch" |
| `domain` | Which domain this belongs to (from Phase 1.5, or inferred for smaller APIs) |
| `effect_type` | One of: `read`, `write`, `delete`, `search`, `configure`, `execute`. These are descriptors, NOT the interaction categories. |
| `source_ref` | Where this came from: `POST /repos` or `src/handlers/repo.ts:createRepo` |
| `notes` | Relevant details: requires auth, has side effects, is idempotent, rate-limited, etc. |

**Important:** Effect types are descriptors for analysis. They are NOT the interaction categories. If your final categories look like "read", "write", "delete" — the analysis has failed. Categories come from consumer intent, not from effect type.

### Group by Domain Proximity

Note which entities reference each other, which are always used together, and which are independent. This informs the hypothesis but does not determine it — domain proximity is one signal, not the answer.

### Note Capability Volume

Count how many operations exist per entity. Entities with many operations may span multiple categories. Entities with one or two operations may fold into a broader category.

### Update State

Write state with `status: "hypothesizing"`. Store the complete capabilities list.

---

## Phase 3: Hypothesis

This is the core intellectual work. You are designing the tool surface that an AI will interact with.

### Start from Consumer Tasks

Do not start from the capabilities list. Start from the consumer's tasks (captured in Phase 1).

For each task the consumer needs to accomplish:
1. What capabilities does this task require?
2. In what order are they typically used?
3. What context carries between them? (e.g., creating a resource returns an ID used in the next call)

### Find the Natural Joints

Capabilities belong in the same tool when:
- They are always used together for a consumer task
- They share enough context that separating them forces the AI to make a meaningless choice
- They operate on the same entity in the same conceptual mode

Capabilities belong in different tools when:
- They serve different consumer tasks
- Collapsing them produces a parameter schema so branchy that correct invocation is harder than choosing between two tools
- They have fundamentally different risk profiles (read vs. delete)

### Domain-First, Then Cross-Cut (Large APIs)

If the API spans multiple domains (Phase 1.5 was run):

1. **Within-domain pass:** For each selected domain, propose interaction categories using the consumer tasks that reference that domain. This keeps each analysis chunk manageable.
2. **Cross-domain pass:** After all domains are analyzed, look for interaction patterns that span domains. Common cross-cuts:
   - **Search/discovery** often spans multiple entity types (search repos, issues, code, users)
   - **Configuration/settings** may span orgs, repos, and user preferences
   - **Lifecycle management** may chain across domains (create repo → configure branch protection → set up CI)
3. **Merge or split:** If a cross-domain pattern is strong enough, create a cross-domain category. If a within-domain category is too thin, fold it into a cross-domain one. If a cross-domain category is too broad, keep the domain-specific versions.

Cross-domain categories use the same schema as within-domain categories — no separate format. However, the **rationale** must explicitly justify why capabilities from different domains belong in the same tool (e.g., "search spans repos, issues, and code because the consumer's discovery task doesn't distinguish between entity types — they search for a keyword and want all matching results regardless of where they live"). The **judgment calls** should note which domain-specific alternatives were considered and why the cross-domain grouping won.

### Name by Intent

Category names describe what the consumer is trying to do, not what entity they're acting on and not what CRUD operation they're performing.

Good names: `manage_repository_lifecycle`, `search_and_discover`, `review_code_changes`, `configure_notifications`
Bad names: `repositories`, `pulls`, `branches` (entity-based)
Bad names: `create`, `read`, `update`, `delete` (CRUD-based)

### Small API Guidance

If the API surface has fewer than ~6 capabilities, do not force consolidation and do not assume 1:1 is correct. Analyze from consumer tasks as usual. Three endpoints that represent send-poll-get-result are one interaction category (async operation lifecycle), not three tools. Conversely, three endpoints that serve genuinely independent tasks may be three tools — and that's fine. The analysis determines the answer, not the count.

### CRUD Check

After generating categories, verify: do they look like CRUD mapped to your domain? If you have categories that are essentially "create things", "read things", "update things", "delete things" — the analysis failed. Go back to the consumer's tasks and try again. CRUD is an implementation pattern, not an interaction intent.

### Document Each Category

For each proposed category:

- **Name**: intent-based, descriptive
- **Description**: one sentence explaining when the consumer reaches for this tool
- **Capabilities**: which CAP-IDs it groups
- **Consumer tasks**: which tasks from Phase 1 it serves
- **Rationale**: why these capabilities belong together — shared context, sequential use, shared entities
- **Judgment calls**: any capability that could reasonably go in two categories, flagged explicitly with reasoning for the chosen placement

### 3-8 Guideline

Each category should group roughly 3-8 underlying capabilities. This is a guideline, not a rule:
- Fewer than 3 may indicate the category is too narrow (approaching 1:1 mapping)
- More than 8 may indicate the category is too broad (the tool becomes a god-object with an incoherent schema)
- Some categories will legitimately fall outside this range

### Coverage Check

After assigning capabilities to categories, verify coverage programmatically. Run:

```bash
python3 -c "
import json, sys
state = json.load(open('.mcp-topo-state.json'))
cap_sort = lambda ids: sorted(ids, key=lambda s: int(s.split('-')[1]))
all_caps = {c['id'] for c in state.get('capabilities', [])}
excluded = {e['id'] for e in state.get('excluded_capabilities', [])}
categories = state.get('proposed_categories', [])
if not all_caps:
    print('ERROR: no capabilities in state file'); sys.exit(1)
if not categories:
    print('ERROR: no proposed_categories in state file'); sys.exit(1)
assigned = set()
for cat in categories:
    assigned.update(cat['capabilities'])
phantom = assigned - all_caps
both = assigned & excluded
unassigned = all_caps - assigned - excluded
double_assigned = [c for c in assigned if sum(c in cat['capabilities'] for cat in categories) > 1]
errors = False
if phantom:
    print(f'PHANTOM references (in categories but not in capabilities): {cap_sort(phantom)}')
    errors = True
if both:
    print(f'CONFLICT — both assigned and excluded: {cap_sort(both)}')
    errors = True
if unassigned:
    print(f'UNASSIGNED capabilities: {cap_sort(unassigned)}')
    errors = True
if double_assigned:
    print(f'DOUBLE-ASSIGNED capabilities: {cap_sort(double_assigned)}')
    errors = True
if not errors:
    print(f'COVERAGE OK: {len(assigned)} assigned to {len(categories)} categories, {len(excluded)} excluded')
"
```

- **Unassigned capabilities** must be either assigned to a category or explicitly marked as out of scope in the state file's `excluded_capabilities` array with reasoning.
- **Double-assigned capabilities** must be resolved — a capability belongs to exactly one category. If it serves two categories, pick one and document the judgment call.

Do not proceed to the devil's advocate until coverage is clean.

### Spawn Devil's Advocate

Spawn the `devil-advocate` agent as a fresh sub-agent. Provide:

```
## Input Source

[the path to the OpenAPI spec, codebase directory, or URL — so the agent can independently verify claims about the API surface]

## Consumer Context

[paste the consumer description and problems from Phase 1]

## Capabilities

[If capabilities fit in the prompt (< 100): paste the full capabilities list with IDs, descriptions, entities, effect types, and source refs]

[If capabilities were offloaded to `.mcp-topo-capabilities.json`: instead paste this instruction:]
The full capabilities list is stored in `.mcp-topo-capabilities.json` in the project root. Read that file to get the complete capabilities with IDs, descriptions, entities, effect types, source refs, and notes. The state file contains only abbreviated entries.

## Proposed Categories

[for each category: name, description, grouped capability IDs, rationale, judgment calls]

Evaluate this proposed MCP tool surface design. For each category, assess whether the grouping is correct or whether a 1:1 mapping would be better. Read the input source to verify claims about shared parameters, endpoint shapes, and relationships. Follow the process in your instructions.
```

Wait for the agent to complete.

### Synthesize

Read the devil's advocate output in full. Parse it into the structured `devil_advocate_output` format for the state file: extract each category assessment (category name, verdict, reasoning, proposed split or specific risk), each standalone candidate (capability ID and reasoning), and the strongest case for 1:1 mapping. Store this structured data in the state file — not the raw markdown.

Process every section:

**Category assessments** — for each SPLIT and RISK verdict:
- If you agree: revise the category accordingly
- If you disagree: document why you disagree with specific reasoning
- If partially right: incorporate the valid part and explain what you're not changing and why

**Standalone candidates** — for each capability the DA identifies as a standalone candidate, decide: extract it into its own tool, leave it in its category, or exclude it. Document the decision.

**Strongest case for 1:1** — this is the DA's steel-manned counter-argument. Do not discard it. Write a direct response: where is the argument correct, where is it wrong, and what specifically about the proposed design addresses its strongest points? This response is presented to the user in Phase 4 alongside the anti-pattern comparison — it gives the user the strongest version of both sides.

If you revised any categories based on the devil's advocate, re-run the coverage check.

### Generate Anti-Pattern Comparison

This is mandatory. Do not skip it.

Generate this **after** the devil's advocate synthesis, so the comparison reflects the final proposed design (including any splits or revisions from the DA).

Show what a 1:1 mapping would produce:
1. List every tool the 1:1 approach would create (one per capability)
2. For each proposed category, show the N tools it replaces
3. Where the devil's advocate identified legitimate reasons for splitting, acknowledge them — the comparison should be honest, not one-sided
4. Articulate the concrete downsides of 1:1 for this specific API:
   - **Tool selection overhead**: with N tools, the AI must evaluate N descriptions to choose the right one. How many tools would the 1:1 mapping produce? At what point does selection become unreliable?
   - **Redundant parameter passing**: many endpoints share parameters (auth tokens, resource IDs, pagination). The 1:1 approach repeats these across every tool description.
   - **Context fragmentation**: related operations are scattered across unrelated tools. The AI has no signal that "list repos" and "create repo" are part of the same workflow.
   - **Token cost**: every tool description consumes tokens in the AI's context window. More tools = more tokens spent on tool descriptions = less room for the actual task.

Be specific. Use real numbers from the capabilities list. "This API has 47 endpoints; a 1:1 mapping produces 47 tools" is more compelling than "too many tools."

### Update State

Write state with `status: "reviewing"`. Store the proposed categories, the devil's advocate output, the synthesis, and the anti-pattern comparison.

---

## Phase 4: Guided Review

Present the design to the user and get explicit approval.

### Presentation

Present the following, in this order:

#### 1. Proposed Tool Surface

For each interaction category:
```
### <Category Name>
**Description:** <when the consumer reaches for this tool>
**Underlying capabilities:** <list the capabilities by name, not just ID>
**Why these belong together:** <rationale>
[If judgment calls exist:] **Judgment calls:** <what could go either way and why you chose this>
```

#### 2. Anti-Pattern Comparison

```
### What 1:1 Mapping Would Look Like

A direct mapping of this API would produce **N tools**. Here is what you'd get:

[list all N tools by name]

The proposed design replaces these with **M tools** organized by interaction intent.

**Why 1:1 is worse for this API:**
[specific downsides with real numbers]

[If the devil's advocate identified legitimate splits:]
**Where 1:1 has merit:**
[honest acknowledgment of cases where standalone tools are better, and how the design addresses them]
```

#### 3. Devil's Advocate Challenges

```
### Design Challenges

The devil's advocate identified the following concerns:

[For each SPLIT/RISK verdict: the concern, your response, and what changed (if anything)]

[For ACCEPT verdicts: brief note that the grouping was validated]

### Strongest Case Against This Design

The devil's advocate made the following argument for 1:1 mapping:

[Summarize the DA's "Strongest Case for 1:1" section]

My response:

[Your direct response from the synthesis — where the argument is correct, where it's wrong, and what the proposed design does to address its strongest points]
```

### Take a Stance

You have an opinion. Express it. If the user pushes toward 1:1 mapping or suggests splitting categories in ways that recreate the anti-pattern, push back with concrete reasoning:

- "Splitting this category would give you 6 tools that all operate on the same entity in the same workflow. The AI would have to choose between them based on subtle parameter differences — that's exactly the problem interaction categories solve."
- "I understand the instinct to give deletions their own tool, but in this case the delete operation shares all its parameters with the update operation and is part of the same lifecycle management workflow. The devil's advocate flagged this as a RISK, but the risk is mitigated by [specific reasoning]."

Yield when the user provides reasoning you hadn't considered. If they have domain knowledge about how the consumer actually works that changes the analysis, incorporate it. The user is the authority on their use case.

### Iteration

There is no formal loop limit. This is a conversation:

1. Present the design
2. User provides feedback
3. Revise categories based on feedback
4. If revisions change category membership, re-run the coverage check
5. If revisions are significant, re-run the CRUD check and update the anti-pattern comparison
6. Present the revised design
7. Repeat until the user approves

**Fundamental rejection:** If the user rejects the design entirely ("start over", "this is wrong", "go back to the beginning"), do not simply tweak categories. Reset to Phase 2: set `status: "analyzing"`, clear `proposed_categories`, `devil_advocate_output`, `synthesis`, and `anti_pattern` from the state file, and re-run the surface analysis with the user's new direction in mind. Preserve the capabilities list — the raw analysis is still valid; only the hypothesis is being discarded. Ask the user what they want done differently before restarting: "What should change about the approach? Different consumer tasks? Different grouping priorities?"

**Contradictory feedback:** If the user's feedback contradicts their earlier feedback (e.g., "split this category" after previously saying "merge these categories"), surface the contradiction explicitly: "In revision 1 you asked me to merge X and Y. Now you're asking me to split them. Which direction do you want to go?" Do not silently undo previous revisions — the user may not realize they're contradicting themselves.

Update state after each revision: store the current categories, user feedback, and changes made.

### Approval

The user must explicitly approve the design before proceeding. Present a numbered summary and ask for confirmation:

```
## Design Summary

The proposed MCP server has **N tools** covering **M capabilities** (replacing a 1:1 mapping of M tools):

1. `tool_name_1` — <one-line description> (K capabilities)
2. `tool_name_2` — <one-line description> (K capabilities)
...

[If any capabilities were excluded:]
Excluded from scope: <list with reasoning>

Does this design look right? Say "approved" to proceed to plan generation, or provide feedback to revise.
```

Do not proceed to Phase 5 until the user explicitly approves. "Looks good", "approved", "yes", "go ahead" — any clear affirmative. If the response is ambiguous ("maybe" or "I guess"), ask for clarification.

After approval, write state with `status: "outputting"` before beginning Phase 5. This ensures that if the orchestrator is interrupted between approval and plan generation, recovery proceeds to output rather than re-presenting the design.

---

## Phase 5: Plan Output

Produce the plan document that `/mob:swarm` will implement.

### Determine Language and Framework

The plan must specify the implementation language and MCP SDK.

**If the input was a codebase:** Infer the language from the project. Look for `package.json` (TypeScript/JavaScript), `go.mod` (Go), `pyproject.toml`/`requirements.txt` (Python), `Cargo.toml` (Rust), `pom.xml`/`build.gradle` (Java/Kotlin). Use the same language for the MCP server.

**If the input was an OpenAPI spec or URL:** Ask the user what language to use. Suggest TypeScript as the default — it has the most mature MCP SDK ecosystem and the broadest adoption.

**MCP SDK mapping:**
- TypeScript/JavaScript: `@modelcontextprotocol/sdk`
- Python: `mcp`
- Go: community SDKs (note that Go lacks an official SDK — flag this to the user)
- Rust: community SDKs (same caveat)

After determining the language, write it to the state file's `language` field immediately. If the orchestrator is interrupted after language selection but before plan completion, this ensures the choice is preserved on recovery.

### Create Plan Directory

Create the `plans/` directory in the project root if it doesn't exist.

### Write the Plan

Write `plans/mcp-<name>.md` following this structure exactly. Every section must be present. The plan must be detailed enough that swarm can implement without re-reading the original API spec.

```markdown
# Plan: MCP Server — <Server Name>

## Context

**Consumer:** <who/what uses this server and what kind of agent/workflow it is>
**Problem:** <what tasks the MCP server enables>
**Source API:** <what API surface this wraps — name, base URL, auth scheme>
**Language:** <implementation language and MCP SDK>
**Design approach:** <1-2 paragraph summary explaining why this tool surface was chosen over 1:1 mapping, referencing the specific API and consumer>

## Phase 1: Project Setup

Set up the MCP server project.

- Initialize <language> project with <package manager>
- Add dependencies: <MCP SDK package>, <HTTP client>, <auth library if needed>, <other>
- Create server entrypoint with MCP protocol handling (stdio transport)
- Create shared types for <list the domain entities>
- Create API client wrapper for <source API> with authentication handling
  - Auth mechanism: <API key, OAuth, bearer token, etc.>
  - Base URL: <API base URL>
  - Error response parsing: <how the source API formats errors>
- Add configuration for API credentials via environment variables: <list the env vars>
- Register all tools (implemented in subsequent phases) in the server's tool list

## Phase 2: Tool — <tool_name>

Implement the `<tool_name>` MCP tool.

**Tool Definition:**
- Name: `<tool_name>`
- Description: `<the description string the AI consumer sees — write this carefully, it determines tool selection>`

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "<param_name>": {
      "type": "<type>",
      "description": "<what this parameter does and when to use it>"
    }
  },
  "required": ["<required_params>"]
}
```

**Dispatch:** Tools that group multiple capabilities need a dispatch parameter — typically an `action` enum that selects which underlying operation to perform. Define it explicitly:
```json
"action": {
  "type": "string",
  "enum": ["list", "create", "archive", "delete"],
  "description": "The operation to perform. 'list' returns matching items, 'create' provisions a new resource, ..."
}
```
Conditional parameters (those only relevant to certain actions) must document which action(s) they apply to in their description field. If a tool wraps a single capability or all capabilities share the same parameters, no dispatch parameter is needed — omit this section.

**Underlying API Calls:**
- `<METHOD> <path>` — when `action` is `<value>` (or when <condition>)
- `<METHOD> <path>` — when `action` is `<value>` (or when <condition>)
- May chain: <describe sequencing if applicable>

**Response Format:**
- Success: <structured description of what the tool returns to the AI>
- Include enough context for the AI to use the result in its next action

**Error Handling:**
- <HTTP status or error condition> → MCP error: "<error message>"
- <HTTP status or error condition> → MCP error: "<error message>"
- Validation failures → MCP error with specific field-level messages

**Rationale:** <why these capabilities are grouped into this tool — preserved from the design phase>

[Repeat Phase 2 structure for each tool, incrementing phase numbers]

## Phase N: Integration and Testing

Wire all tools into the MCP server and verify end-to-end.

**Test strategy:** Infer the test framework and conventions from the chosen language and any existing test patterns in the codebase (if the input was a codebase). If the codebase already has tests, match the framework and style. If starting fresh, use the standard test framework for the language (Jest/Vitest for TypeScript, pytest for Python, go test for Go, etc.).

**Mocking the source API:** Specify how to mock HTTP calls to the source API during testing. This depends on the language and available tooling — the plan should name the specific mocking library or approach (e.g., MSW for TypeScript, responses/httpx-mock for Python, httptest for Go).

- Verify all tools are registered and appear in `tools/list` response
- Add integration tests for each tool with representative inputs
  - For each tool: at least one test per underlying API call path
  - Test parameter validation: required fields missing, invalid enum values, wrong types
- Add error path tests: auth failure, invalid input, API unavailability, rate limiting
- Add a README documenting:
  - What the server does and who it's for
  - The tool surface with descriptions
  - Setup instructions (environment variables, API credentials)
  - Example usage for each tool
- Test the server end-to-end: start it, call `tools/list`, invoke each tool with sample input
```

### Critical Details for the Plan

- **Tool description strings** are the most important text in the plan. They are what the AI consumer reads to decide which tool to use. Write them as if you are explaining to an AI what this tool does and when to use it. Be specific, not generic.
- **JSON Schemas** must be complete. Every property, every type, every description. Do not use placeholder schemas.
- **API call mappings** must be explicit. The implementor should know exactly which HTTP calls to make for each parameter combination.
- **Error handling** must cover the real error cases from the source API, not generic ones.

### Update State

Write state with `status: "complete"`, store `plan_path`.

### Present Summary

```
## MCP Server Design Complete

Server: <name>
Plan: plans/mcp-<name>.md
Tools: <N> interaction categories (replacing <M> individual endpoints)

To implement:
  /mob:swarm plans/mcp-<name>.md
```

---

## State File

Maintain `.mcp-topo-state.json` in the project root throughout the run. Write it after every phase transition and every revision — this is what allows recovery after context compaction or interruption.

**Large API note:** For APIs with 100+ capabilities, the state file may become large. If the capabilities list exceeds ~100 entries, store only `id`, `capability`, `domain`, and `effect_type` in the state file. Write the full capability details (including `entity`, `source_ref`, and `notes`) to a separate `.mcp-topo-capabilities.json` file and reference it from the state file with `"capabilities_file": ".mcp-topo-capabilities.json"`.

```json
{
  "server_name": "<name>",
  "started": "<ISO timestamp>",
  "last_updated": "<ISO timestamp>",
  "status": "intake",
  "input": {
    "type": "openapi | codebase | url",
    "source": "<path or URL>"
  },
  "consumer": {
    "who": "<description of the MCP consumer>",
    "problems": "<what tasks/problems the server solves>"
  },
  "endpoint_count": 0,
  "domains": null,
  "capabilities": [
    {
      "id": "CAP-1",
      "capability": "<what it does>",
      "entity": "<domain object>",
      "domain": "<domain name>",
      "effect_type": "read | write | delete | search | configure | execute",
      "source_ref": "<endpoint or code reference>",
      "notes": "<relevant details>"
    }
  ],
  "excluded_capabilities": [
    {
      "id": "CAP-12",
      "reason": "<why this capability is excluded from all categories>"
    }
  ],
  "proposed_categories": [
    {
      "name": "<intent-based name>",
      "description": "<one sentence>",
      "capabilities": ["CAP-1", "CAP-3"],
      "consumer_tasks": ["<task description>"],
      "rationale": "<why these belong together>",
      "judgment_calls": ["<ambiguous grouping decisions>"],
      "revision": 1
    }
  ],
  "anti_pattern": {
    "total_1to1_tools": 0,
    "comparison_summary": "<brief summary of why 1:1 is worse>"
  },
  "devil_advocate_output": {
    "category_assessments": [
      {
        "category": "<category name>",
        "verdict": "ACCEPT | SPLIT | RISK",
        "reasoning": "<assessment summary>",
        "proposed_split": "<if SPLIT: what the split looks like>",
        "specific_risk": "<if RISK: the risk and mitigation>"
      }
    ],
    "standalone_candidates": [
      {
        "capability_id": "CAP-N",
        "reasoning": "<why this should be standalone>"
      }
    ],
    "strongest_case_for_1to1": "<the DA's steel-manned argument for 1:1 mapping>"
  },
  "synthesis": "<orchestrator's response to devil's advocate>",
  "user_feedback": [
    {
      "revision": 1,
      "feedback": "<what the user said>",
      "changes_made": "<what changed in response>"
    }
  ],
  "language": "<implementation language>",
  "plan_path": "plans/mcp-<name>.md"
}
```

Valid `status` values: `"intake"`, `"scoping"`, `"analyzing"`, `"hypothesizing"`, `"reviewing"`, `"outputting"`, `"complete"`.

**`domains` field:** `null` for small APIs that skip Phase 1.5. When Phase 1.5 runs, populated as:
```json
{
  "all": [
    { "name": "<domain name>", "endpoint_count": 0, "referenced_by_tasks": true }
  ],
  "selected": ["<domain name>", "<domain name>"]
}
```
The `domain` field on each capability is always populated (inferred for small APIs), regardless of whether Phase 1.5 ran.

---

## Notes

- **Do not skip the anti-pattern comparison.** It is the primary value proposition of this skill. The user needs to see what they'd get without this design work.
- **If your categories look like CRUD, start over.** Categories named "create", "read", "update", "delete" (or synonyms) mean the analysis started from effect types instead of consumer tasks. Go back to Phase 3 and start from the consumer's tasks.
- **The plan must stand alone.** Swarm will implement from the plan without re-reading the original API spec. Every tool schema, every parameter, every error case, every API call mapping must be in the plan.
- **Do not produce code.** This skill produces a plan. `/mob:swarm` produces code.
- **Argue for your design.** You are not a neutral presenter of options. You have analyzed the API, considered the alternatives, and formed a recommendation. Present it with conviction. Yield to the user's domain knowledge, not to their instinct to map endpoints 1:1.
- **Tool descriptions are load-bearing.** The description string on each MCP tool is what the AI reads to decide which tool to use. A vague description ("manage repositories") forces the AI to guess. A precise description ("create, configure, archive, and delete repositories as part of project lifecycle management — use this when setting up new projects or cleaning up completed ones") tells the AI exactly when to reach for this tool.
- **Small APIs are not automatically 1:1.** A three-endpoint API where the endpoints represent send-poll-get-result is one interaction category, not three tools. Conversely, three endpoints serving genuinely independent tasks may be three tools. Analyze from consumer tasks; the count does not determine the design.
- **Coverage is enforced programmatically.** Every capability must be assigned to exactly one category or explicitly excluded with reasoning. The coverage check script catches gaps that prompting alone would miss. Do not proceed past Phase 3 with unassigned or double-assigned capabilities.