Skip to content

feat: add MCP server for native Claude Code tool integration #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
darko-mijic merged 7 commits into from
Mar 14, 2026
Merged

feat: add MCP server for native Claude Code tool integration #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
eb74072
feat: add MCP server with 25 tools for native Claude Code integration
darko-mijic Mar 14, 2026
f0a9916
fix: address 4 MCP server issues found during first integration test
darko-mijic Mar 14, 2026
5838edc
fix: address 13 PR #37 review comments — server architecture, error h…
darko-mijic Mar 14, 2026
c091bdf
style: format CLAUDE.md with prettier
darko-mijic Mar 14, 2026
0c2a711
docs: add modular CLAUDE.md module for MCP server tools reference
darko-mijic Mar 14, 2026
46ff2b8
fix: resolve remaining PR #37 review threads — version, config fallba…
darko-mijic Mar 14, 2026
2678c3e
fix: address 4 remaining PR #37 review threads — sequence tags, idemp…
darko-mijic Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"mcpServers": {
"delivery-process": {
"command": "npx",
"args": ["tsx", "src/cli/mcp-server.ts", "--watch"]
}
}
}
124 changes: 124 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,130 @@ See the **Context Gathering Protocol** section above for mandatory session start
- Output modifiers (`--names-only`, `--count`, `--fields`) compose with any list/query command.
- `pnpm` outputs a banner to stdout. For clean JSON piping, use `npx tsx src/cli/process-api.ts` directly.

### MCP Server — Native AI Context Tools

When the MCP server is running, **use `dp_*` tools instead of CLI commands** (`pnpm process:query --`). The MCP server keeps the MasterDataset in memory — tool calls dispatch in sub-milliseconds vs 2-5 seconds for CLI subprocess invocations. All 25 tools wrap the same ProcessStateAPI methods available via CLI.

#### Session Start (MCP Protocol)

Use these tools at the start of every PR or implementation session, in order:

| Step | MCP Tool | What You Get | CLI Equivalent |
| ---- | ------------------- | ------------------------------------------- | ------------------------------------------------- |
| 1 | `dp_overview` | Project health, active phases, blockers | `pnpm process:query -- overview` |
| 2 | `dp_scope_validate` | Pre-flight: FSM violations, missing deps | `pnpm process:query -- scope-validate <p> <type>` |
| 3 | `dp_context` | Curated context bundle for the session | `pnpm process:query -- context <p> --session <t>` |
| 4 | `dp_files` | File reading list with implementation paths | `pnpm process:query -- files <p> --related` |

Steps 1-2 can run in parallel (no dependencies between them).

#### Tool Reference

**Session-Aware Tools** — text output, use for workflow:

| Tool | Input | Description |
| ------------------- | ------------------- | ---------------------------------------------- |
| `dp_overview` | _(none)_ | Progress %, active phases, blocking chains |
| `dp_context` | `name`, `session?` | Curated context (planning/design/implement) |
| `dp_files` | `name` | Ordered file list with roles |
| `dp_dep_tree` | `name`, `maxDepth?` | Dependency chain with status per dep |
| `dp_scope_validate` | `name`, `session` | PASS/BLOCKED/WARN pre-flight verdict |
| `dp_handoff` | `name`, `session?` | Session-end state for multi-session continuity |

**Data Query Tools** — JSON output, use for structured lookups:

| Tool | Input | Description |
| -------------- | -------------------------------------------------------- | -------------------------------------------------- |
| `dp_status` | _(none)_ | Pattern counts by status, completion % |
| `dp_pattern` | `name` | Full metadata: deliverables, relationships, shapes |
| `dp_list` | `status?`, `phase?`, `category?`, `namesOnly?`, `count?` | Filtered pattern listing |
| `dp_search` | `query` | Fuzzy name search with similarity scores |
| `dp_rules` | `pattern?`, `onlyInvariants?` | Business rules from Gherkin Rule: blocks |
| `dp_tags` | _(none)_ | Tag usage counts across all sources |
| `dp_sources` | _(none)_ | File inventory by type (TS, Gherkin, stubs) |
| `dp_stubs` | `unresolved?` | Design stubs with resolution status |
| `dp_decisions` | `name?` | AD-N/DD-N design decisions from stubs |

**Architecture Tools** — JSON output, use for dependency and structure analysis:

| Tool | Input | Description |
| ---------------------- | -------- | ------------------------------------------- |
| `dp_arch_context` | `name?` | Bounded contexts with member patterns |
| `dp_arch_layer` | `name?` | Architecture layers with member patterns |
| `dp_arch_neighborhood` | `name` | Uses, used-by, same-context peers |
| `dp_arch_blocking` | _(none)_ | Patterns blocked by incomplete dependencies |
| `dp_arch_dangling` | _(none)_ | Broken references to nonexistent patterns |
| `dp_arch_coverage` | `path?` | Annotation coverage % and unused taxonomy |
| `dp_unannotated` | `path?` | Files missing @libar-docs annotations |

**Server Management:**

| Tool | Description |
| ------------ | ------------------------------------------------------ |
| `dp_rebuild` | Force dataset rebuild from current source files |
| `dp_config` | Show source globs, base dir, build time, pattern count |
| `dp_help` | List all available tools with descriptions |

#### Common Recipes

| Goal | Tools |
| ---------------------------------- | ------------------------------------------------------------------ |
| What patterns are blocking? | `dp_arch_blocking` |
| Understand a pattern before coding | `dp_context` (name, session) + `dp_scope_validate` (name, session) |
| Find business rules for a feature | `dp_rules` with `pattern` filter |
| Check annotation gaps | `dp_arch_coverage` or `dp_unannotated` |
| Explore a bounded context | `dp_arch_context` with name |
| Find what depends on a pattern | `dp_arch_neighborhood` with name |
| List all roadmap patterns | `dp_list` with `status: "roadmap"` |
| Search by partial name | `dp_search` with query |

#### Configuration

The MCP server is configured via `.mcp.json` in the project root:

```json
{
"mcpServers": {
"delivery-process": {
"command": "npx",
"args": ["dp-mcp-server", "--watch"]
}
}
}
```

For monorepo setups with explicit source globs:

```json
{
"mcpServers": {
"delivery-process": {
"command": "npx",
"args": [
"dp-mcp-server",
"--watch",
"--input",
"packages/core/src/**/*.ts",
"--input",
"packages/api/src/**/*.ts",
"--features",
"specs/**/*.feature"
]
}
}
}
```

The `--watch` flag enables auto-rebuild when `.ts` or `.feature` files change (500ms debounce). Without it, use `dp_rebuild` after annotation changes.

#### Tips

- `dp_rules` without a `pattern` filter returns a compact summary (totals + rule names + per-area counts) — unfiltered output is capped to prevent context overflow.
- `dp_pattern` returns full metadata (~66KB for completed patterns) — prefer `dp_context` with a session type for interactive sessions.
- `dp_search` uses fuzzy matching — partial names work (e.g., "MCP" matches all MCP-related patterns).
- `dp_list` filters compose: `status` + `phase` + `category` narrow results cumulatively.
- Session-aware tools return formatted text (like CLI output). Data and architecture tools return JSON.

---

## Architecture
Expand Down
123 changes: 123 additions & 0 deletions _claude-md/api/mcp-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
### MCP Server — Native AI Context Tools

When the MCP server is running, **use `dp_*` tools instead of CLI commands** (`pnpm process:query --`). The MCP server keeps the MasterDataset in memory — tool calls dispatch in sub-milliseconds vs 2-5 seconds for CLI subprocess invocations. All 25 tools wrap the same ProcessStateAPI methods available via CLI.

#### Session Start (MCP Protocol)

Use these tools at the start of every PR or implementation session, in order:

| Step | MCP Tool | What You Get | CLI Equivalent |
| ---- | ------------------- | ------------------------------------------- | ------------------------------------------------- |
| 1 | `dp_overview` | Project health, active phases, blockers | `pnpm process:query -- overview` |
| 2 | `dp_scope_validate` | Pre-flight: FSM violations, missing deps | `pnpm process:query -- scope-validate <p> <type>` |
| 3 | `dp_context` | Curated context bundle for the session | `pnpm process:query -- context <p> --session <t>` |
| 4 | `dp_files` | File reading list with implementation paths | `pnpm process:query -- files <p> --related` |

Steps 1-2 can run in parallel (no dependencies between them).

#### Tool Reference

**Session-Aware Tools** — text output, use for workflow:

| Tool | Input | Description |
| ------------------- | ------------------- | ---------------------------------------------- |
| `dp_overview` | _(none)_ | Progress %, active phases, blocking chains |
| `dp_context` | `name`, `session?` | Curated context (planning/design/implement) |
| `dp_files` | `name` | Ordered file list with roles |
| `dp_dep_tree` | `name`, `maxDepth?` | Dependency chain with status per dep |
| `dp_scope_validate` | `name`, `session` | PASS/BLOCKED/WARN pre-flight verdict |
| `dp_handoff` | `name`, `session?` | Session-end state for multi-session continuity |

**Data Query Tools** — JSON output, use for structured lookups:

| Tool | Input | Description |
| -------------- | -------------------------------------------------------- | -------------------------------------------------- |
| `dp_status` | _(none)_ | Pattern counts by status, completion % |
| `dp_pattern` | `name` | Full metadata: deliverables, relationships, shapes |
| `dp_list` | `status?`, `phase?`, `category?`, `namesOnly?`, `count?` | Filtered pattern listing |
| `dp_search` | `query` | Fuzzy name search with similarity scores |
| `dp_rules` | `pattern?`, `onlyInvariants?` | Business rules from Gherkin Rule: blocks |
| `dp_tags` | _(none)_ | Tag usage counts across all sources |
| `dp_sources` | _(none)_ | File inventory by type (TS, Gherkin, stubs) |
| `dp_stubs` | `unresolved?` | Design stubs with resolution status |
| `dp_decisions` | `name?` | AD-N/DD-N design decisions from stubs |

**Architecture Tools** — JSON output, use for dependency and structure analysis:

| Tool | Input | Description |
| ---------------------- | -------- | ------------------------------------------- |
| `dp_arch_context` | `name?` | Bounded contexts with member patterns |
| `dp_arch_layer` | `name?` | Architecture layers with member patterns |
| `dp_arch_neighborhood` | `name` | Uses, used-by, same-context peers |
| `dp_arch_blocking` | _(none)_ | Patterns blocked by incomplete dependencies |
| `dp_arch_dangling` | _(none)_ | Broken references to nonexistent patterns |
| `dp_arch_coverage` | `path?` | Annotation coverage % and unused taxonomy |
| `dp_unannotated` | `path?` | Files missing @libar-docs annotations |

**Server Management:**

| Tool | Description |
| ------------ | ------------------------------------------------------ |
| `dp_rebuild` | Force dataset rebuild from current source files |
| `dp_config` | Show source globs, base dir, build time, pattern count |
| `dp_help` | List all available tools with descriptions |

#### Common Recipes

| Goal | Tools |
| ---------------------------------- | ------------------------------------------------------------------ |
| What patterns are blocking? | `dp_arch_blocking` |
| Understand a pattern before coding | `dp_context` (name, session) + `dp_scope_validate` (name, session) |
| Find business rules for a feature | `dp_rules` with `pattern` filter |
| Check annotation gaps | `dp_arch_coverage` or `dp_unannotated` |
| Explore a bounded context | `dp_arch_context` with name |
| Find what depends on a pattern | `dp_arch_neighborhood` with name |
| List all roadmap patterns | `dp_list` with `status: "roadmap"` |
| Search by partial name | `dp_search` with query |

#### Configuration

The MCP server is configured via `.mcp.json` in the project root:

```json
{
"mcpServers": {
"delivery-process": {
"command": "npx",
"args": ["dp-mcp-server", "--watch"]
}
}
}
```

For monorepo setups with explicit source globs:

```json
{
"mcpServers": {
"delivery-process": {
"command": "npx",
"args": [
"dp-mcp-server",
"--watch",
"--input",
"packages/core/src/**/*.ts",
"--input",
"packages/api/src/**/*.ts",
"--features",
"specs/**/*.feature"
]
}
}
}
```

The `--watch` flag enables auto-rebuild when `.ts` or `.feature` files change (500ms debounce). Without it, use `dp_rebuild` after annotation changes.

#### Tips

- `dp_rules` without a `pattern` filter returns a compact summary (totals + rule names + per-area counts) — unfiltered output is capped to prevent context overflow.
- `dp_pattern` returns full metadata (~66KB for completed patterns) — prefer `dp_context` with a session type for interactive sessions.
- `dp_search` uses fuzzy matching — partial names work (e.g., "MCP" matches all MCP-related patterns).
- `dp_list` filters compose: `status` + `phase` + `category` narrow results cumulatively.
- Session-aware tools return formatted text (like CLI output). Data and architecture tools return JSON.
5 changes: 5 additions & 0 deletions _claude-md/metadata.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,11 @@
"path": "api/data-api-cli.md",
"tags": ["core"],
"description": "Data API CLI for querying delivery process state"
},
{
"path": "api/mcp-server.md",
"tags": ["core"],
"description": "MCP server tools for native AI agent access to ProcessStateAPI"
}
]
},
Expand Down
Loading
Loading