@mandujs/mcp

<p align="center">
  <img src="https://raw.githubusercontent.com/konamgil/mandu/main/mandu_only_simbol.png" alt="Mandu" width="200" />
</p>

<h1 align="center">@mandujs/mcp</h1>

<p align="center">
  <strong>Mandu MCP Server</strong><br/>
  Model Context Protocol server for AI agent integration
</p>

<p align="center">
  English | <a href="./README.ko.md"><strong>한국어</strong></a>
</p>

## What is MCP?

MCP (Model Context Protocol) enables AI agents to directly interact with the Mandu framework. Instead of generating code blindly, agents can:

- Query current project structure
- Add/modify routes with validation
- Write business logic with auto-correction
- Check architecture rules before making changes
- Receive real-time violation notifications

## Setup

### Claude Code / Claude Desktop

Add to your MCP configuration (`.mcp.json` or `.claude.json`):

```json
{
  "mcpServers": {
    "mandu": {
      "command": "bunx",
      "args": ["mandu-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

> **Note**: Use `mandu-mcp` (not `@mandujs/mcp`) to avoid conflicts with Python's `mcp` CLI on PATH (#174).

### Direct Execution

```bash
cd /path/to/project
bunx mandu-mcp
```

### Tool Profiles

Filter available tools via the `MANDU_MCP_PROFILE` env var:

| Profile | Tools | Use Case |
|---------|-------|----------|
| `minimal` | ~15 | Read-only operations, safe for autonomous agents |
| `standard` | ~50 | Default — most common operations |
| `full` | 85+ | All tools including destructive operations |

```bash
MANDU_MCP_PROFILE=minimal bunx mandu-mcp
```

### Global Mode

Run MCP without project auto-detection (use current directory):

```bash
bunx @mandujs/mcp --global
```

Optional: target a specific root directory:

```bash
bunx @mandujs/mcp --root /path/to/project
```

---

## Tools (85+)

### Spec Management

| Tool | Description |
|------|-------------|
| `mandu_list_routes` | List all routes with details |
| `mandu_get_route` | Get specific route by ID |
| `mandu_add_route` | Add new route (scaffolds app/ files) |
| `mandu_delete_route` | Remove route from manifest |
| `mandu_validate_manifest` | Validate manifest schema |

### Code Generation

| Tool | Description |
|------|-------------|
| `mandu_generate` | Generate code from manifest |

### Transaction Management

| Tool | Description |
|------|-------------|
| `mandu_begin` | Start transaction with snapshot |
| `mandu_commit` | Finalize changes |
| `mandu_rollback` | Restore from snapshot |
| `mandu_tx_status` | Get transaction state |

### Slot Management

| Tool | Description |
|------|-------------|
| `mandu_read_slot` | Read slot file content |
| `mandu_write_slot` | Write slot file (with auto-correction) |
| `mandu_validate_slot` | Validate slot syntax |

### Guard & Architecture

| Tool | Description |
|------|-------------|
| `mandu_guard_check` | Run all guard checks |
| `mandu_guard_heal` | Self-Healing Guard - detect + auto-fix suggestions |
| `mandu_explain_rule` | Explain architecture rule with examples |
| `mandu_check_location` | Validate file location before creating |
| `mandu_check_import` | Validate imports against architecture rules |
| `mandu_get_architecture` | Get project architecture rules |

### Decision Memory (RFC-001) 🆕

| Tool | Description |
|------|-------------|
| `mandu_search_decisions` | Search ADRs by tags or status |
| `mandu_save_decision` | Save new architecture decision |
| `mandu_check_consistency` | Check decision-implementation consistency |

### Semantic Slots (RFC-001) 🆕

| Tool | Description |
|------|-------------|
| `mandu_get_slot_constraints` | Get recommended slot constraint presets |

### Architecture Negotiation (RFC-001) 🆕

| Tool | Description |
|------|-------------|
| `mandu_negotiate` | AI-Framework negotiation dialog |
| `mandu_generate_scaffold` | Generate structure scaffold |
| `mandu_analyze_structure` | Analyze existing project structure |

### Brain & Monitoring

| Tool | Description |
|------|-------------|
| `mandu_doctor` | Analyze failures + suggest patches |
| `mandu_watch_start` | Start file watcher with notifications |
| `mandu_watch_status` | Get watcher status |
| `mandu_watch_stop` | Stop file watcher |

### Project & Dev

| Tool | Description |
|------|-------------|
| `mandu_init` | Initialize new Mandu project (init + optional install) |
| `mandu_dev_start` | Start dev server (bun run dev) |
| `mandu_dev_stop` | Stop dev server |

### Hydration & Build

| Tool | Description |
|------|-------------|
| `mandu_build` | Build client bundles |
| `mandu_build_status` | Get bundle statistics |
| `mandu_list_islands` | List routes with hydration |
| `mandu_set_hydration` | Configure hydration strategy |
| `mandu_add_client_slot` | Create client slot for route |

### History

| Tool | Description |
|------|-------------|
| `mandu_list_changes` | View change history |
| `mandu_prune_history` | Clean old snapshots |

### ATE (Automation Test Engine) — 9 tools

| Tool | Description |
|------|-------------|
| `mandu.ate.extract` | Extract interaction graph from codebase |
| `mandu.ate.generate` | Generate Playwright test scenarios |
| `mandu.ate.run` | Execute Playwright tests with artifacts |
| `mandu.ate.report` | Generate test summary report |
| `mandu.ate.heal` | Auto-suggest fixes for failed tests |
| `mandu.ate.impact` | Compute affected routes (subset testing) |
| `mandu.ate.auto_pipeline` | Run full pipeline (extract → generate → run → report → heal) |
| `mandu.ate.feedback` | Analyze failures with 7-category classification |
| `mandu.ate.apply_heal` | Apply heal diffs safely (with backup) |

### Test Selection (Phase 5) — 3 tools 🆕

| Tool | Description |
|------|-------------|
| `mandu.test.smart` | Smart test selection from git diff with priority scoring |
| `mandu.test.coverage` | Detect coverage gaps in interaction graph |
| `mandu.test.precommit` | Pre-commit hook: should we test before committing? |

### Composite — 7 tools

| Tool | Description |
|------|-------------|
| `mandu.feature.create` | Scaffold full feature (route + contract + slot + island) |
| `mandu.diagnose` | Multi-aspect project health check |
| `mandu.island.add` | Add interactive island to route |
| `mandu.middleware.add` | Add middleware to route |
| `mandu.test.route` | Quick smoke test for a route |
| `mandu.deploy.check` | Pre-deploy production readiness check |
| `mandu.cache.manage` | Manage ISR/SWR cache (list, invalidate, stats) |

---

## Resources (4)

| URI | Description |
|-----|-------------|
| `mandu://routes` | Current routes manifest |
| `mandu://config` | Parsed `mandu.config.ts` settings |
| `mandu://errors` | Recent build and runtime errors |
| `mandu://activity` | **NEW**: Recent observability events + 5-minute stats from EventBus |

---

## Real-Time Notifications

When `mandu_watch_start` is active, the agent receives real-time push notifications for architecture violations:

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "warning",
    "logger": "mandu-watch",
    "data": {
      "type": "watch_warning",
      "ruleId": "GENERATED_DIRECT_EDIT",
      "file": "apps/server/generated/routes/home.route.ts",
      "message": "Generated file was directly modified",
      "timestamp": "2026-02-02T10:15:00.000Z"
    }
  }
}
```

### Watched Rules

| Rule | Description |
|------|-------------|
| `GENERATED_DIRECT_EDIT` | Manual edits to generated files |
| `WRONG_SLOT_LOCATION` | Slot files outside `spec/slots/` |
| `SLOT_NAMING` | Slot files not ending with `.slot.ts` |
| `CONTRACT_NAMING` | Contract files not ending with `.contract.ts` |
| `FORBIDDEN_IMPORT` | Dangerous imports in generated files |

---

## Activity Monitor (JSON Schema)

The MCP server writes activity logs to `.mandu/activity.log` (pretty) or `.mandu/activity.jsonl` (JSON).  
JSON lines follow a stable schema with `schemaVersion`:

```json
{
  "schemaVersion": "1.0",
  "ts": "2026-02-02T12:34:56.789Z",
  "type": "tool.call",
  "severity": "info",
  "source": "tool",
  "message": "",
  "actionRequired": false,
  "fingerprint": "tool:call:mandu_guard_check",
  "count": 1,
  "data": {
    "tool": "mandu_guard_check",
    "tag": "GUARD",
    "args": {}
  }
}
```

Common `type` values: `tool.call`, `tool.result`, `tool.error`, `watch.warning`, `guard.summary`, `guard.violation`, `routes.change`, `system.event`, `monitor.summary`.

Default config is auto-created at `.mandu/monitor.config.json` on first run.

---

## Agent Workflow Examples

### Adding a New API Route

```
Agent:
1. mandu_begin({ message: "Add users API" })
   → Creates snapshot

2. mandu_check_location({ path: "spec/slots/users.slot.ts" })
   → Validates location is allowed

3. mandu_add_route({
     id: "users-list",
     pattern: "/api/users",
     kind: "api",
     methods: ["GET", "POST"],
     slotModule: "spec/slots/users.slot.ts"
   })
   → Adds route to manifest and scaffolds app/ files

4. mandu_generate()
   → Creates route handlers

5. mandu_write_slot({
     routeId: "users-list",
     content: "...",
     autoCorrect: true
   })
   → Writes business logic

6. mandu_guard_check()
   → Validates architecture

7. mandu_commit()
   → Finalizes changes
```

### Checking Before Writing

```
Agent:
1. mandu_get_architecture()
   → Gets folder rules, import rules, naming rules

2. mandu_check_location({ path: "src/features/user/api.ts" })
   → Checks if location is valid

3. mandu_check_import({
     sourceFile: "src/features/user/api.ts",
     imports: ["../../entities/product"]
   })
   → Checks if imports are allowed

4. Proceed with writing if all checks pass
```

### Monitoring Architecture

```
Agent:
1. mandu_watch_start()
   → Starts watching with notifications

2. (Agent receives real-time warnings)

3. mandu_watch_status()
   → Gets current status and recent warnings

4. mandu_doctor()
   → Analyzes violations and suggests fixes

5. mandu_watch_stop()
   → Stops watching
```

### ATE E2E Testing Workflow

```mermaid
graph TD
    A[mandu.ate.extract] -->|interaction-graph.json| B[mandu.ate.generate]
    B -->|Playwright specs| C[mandu.ate.run]
    C -->|Test results| D{Success?}
    D -->|Yes| E[mandu.ate.report]
    D -->|No| F[mandu.ate.heal]
    F -->|Suggestions| G[Apply fixes]
    G --> C

    H[mandu.ate.impact] -->|Affected routes| B

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#fff4e1
    style D fill:#ffe1e1
    style E fill:#e1ffe1
    style F fill:#ffe1e1
    style H fill:#f5e1ff
```

**Example: Full ATE Pipeline**

```typescript
// 1. Extract interaction graph
await mandu.ate.extract({
  repoRoot: process.cwd(),
  routeGlobs: ["app/**/page.tsx"]
});

// 2. Optional: Compute impact for subset testing
const impact = mandu.ate.impact({
  repoRoot: process.cwd(),
  base: "main",
  head: "HEAD"
});

// 3. Generate test scenarios
mandu.ate.generate({
  repoRoot: process.cwd(),
  oracleLevel: "L1",
  onlyRoutes: impact.selectedRoutes  // Subset testing
});

// 4. Run tests
const result = await mandu.ate.run({
  repoRoot: process.cwd(),
  baseURL: "http://localhost:3333",
  ci: true
});

// 5. Generate report
await mandu.ate.report({
  repoRoot: process.cwd(),
  runId: result.runId,
  startedAt: result.startedAt,
  finishedAt: result.finishedAt,
  exitCode: result.exitCode,
  oracleLevel: "L1"
});

// 6. Heal if failed
if (result.exitCode !== 0) {
  const healing = mandu.ate.heal({
    repoRoot: process.cwd(),
    runId: result.runId
  });

  console.log("Healing suggestions:");
  healing.suggestions.forEach(s => console.log(s.diff));
}
```

**ATE Use Cases:**

- 🤖 **Agent-driven testing**: Claude Code generates and runs E2E tests
- 🔄 **Self-healing tests**: Auto-suggest selector fixes when tests fail
- 🎯 **Impact-based testing**: Run only tests affected by code changes
- 📊 **Multi-oracle validation**: L0 (smoke) → L1 (structure) → L2 (behavior) → L3 (domain)
- 🚀 **CI/CD ready**: GitHub Actions, GitLab CI integration

**Learn More**: [ATE MCP Integration Guide](../ate/docs/mcp-integration.md)

---

## Architecture Integration

The MCP server integrates with Mandu Guard to enforce architecture rules:

```
┌─────────────────────────────────────────────────────────────┐
│                     AI Agent (Claude)                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   Before writing code:                                       │
│   1. mandu_get_architecture()    → Get rules                 │
│   2. mandu_check_location()      → Validate placement        │
│   3. mandu_check_import()        → Validate dependencies     │
│                                                              │
│   While writing:                                             │
│   - mandu_watch_start()          → Real-time notifications   │
│                                                              │
│   After writing:                                             │
│   - mandu_guard_check()          → Full validation           │
│   - mandu_doctor()               → Get fix suggestions       │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

---

## Requirements

- Bun >= 1.0.0
- @mandujs/core >= 0.13.0

## Related Packages

- [@mandujs/core](https://www.npmjs.com/package/@mandujs/core) - Core runtime
- [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI tool

## License

MPL-2.0