add MCP server for runtime resource lookup

.gitignore

@@ -29,6 +29,8 @@ build/
 **/node_modules/
 !tools/loop-audit/dist/
 !tools/loop-cost/dist/
+!tools/loop-init/dist/
+!tools/mcp-server/dist/
 !tools/goal-audit/dist/
 *.egg-info/
 

examples/mcp/loop-engineering.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "loop-engineering": {
+      "command": "npx",
+      "args": ["-y", "@cobusgreyling/loop-mcp-server"],
+      "env": {
+        "LOOP_PROJECT_ROOT": "."
+      }
+    }
+  }
+}

package.json

@@ -8,8 +8,9 @@
     "test:loop-audit": "cd tools/loop-audit && npm test",
     "test:loop-init": "cd tools/loop-init && npm test",
     "test:loop-cost": "cd tools/loop-cost && npm test",
-    "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost",
-    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build"
+    "test:mcp-server": "cd tools/mcp-server && npm test",
+    "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:mcp-server",
+    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../mcp-server && npm run build"
   },
   "devDependencies": {
     "ajv": "^8.17.1",

scripts/ci-validate-gates.sh

@@ -33,4 +33,10 @@ node scripts/check-loop-init-sync.mjs
 cd tools/loop-init
 npm ci
 npm test
+
+echo "Building and testing mcp-server…"
+cd ../mcp-server
+npm ci
+npm test
+
 echo "validate gates passed ✓"

tools/mcp-server/README.md

@@ -0,0 +1,95 @@
+# @cobusgreyling/loop-mcp-server
+
+MCP (Model Context Protocol) server for **loop-engineering** — exposes patterns, skills, state, budget, and audit tools as runtime-queryable resources for AI agents.
+
+Instead of stuffing all loop documentation into the prompt, agents can query only what they need on-demand via MCP.
+
+## Quick Start
+
+```bash
+npx @cobusgreyling/loop-mcp-server
+```
+
+### Configure in Claude Code / Grok / any MCP client
+
+Add to your MCP config (`.mcp.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "loop-engineering": {
+      "command": "npx",
+      "args": ["-y", "@cobusgreyling/loop-mcp-server"],
+      "env": {
+        "LOOP_PROJECT_ROOT": "."
+      }
+    }
+  }
+}
+```
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `loop://registry` | Pattern registry (all 7 patterns with metadata, costs, phases) |
+| `loop://config` | LOOP.md — cadence, budget, gates, scheduling |
+| `loop://budget` | loop-budget.md — token caps, kill switch |
+| `loop://run-log` | loop-run-log.md — append-only run history |
+| `loop://safety` | Safety docs — denylists, auto-merge policy, MCP scopes |
+| `loop://patterns/{id}` | Full pattern documentation by ID |
+| `loop://skills/{name}` | Skill definition (SKILL.md) by name |
+| `loop://state/{file}` | State file content |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `loop_list_patterns` | List all patterns with goals, cadences, risk levels |
+| `loop_list_skills` | List available skills with locations |
+| `loop_list_state_files` | List state files in the project |
+| `loop_get_pattern` | Get full pattern docs + registry metadata |
+| `loop_get_skill` | Get SKILL.md content for a named skill |
+| `loop_get_state` | Read a state file for current loop status |
+| `loop_recommend_pattern` | Recommend patterns for a use case description |
+| `loop_estimate_cost` | Estimate daily token cost for a pattern at L1/L2/L3 |
+
+## Environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOOP_PROJECT_ROOT` | `cwd()` | Root directory of the project to serve |
+
+## Development
+
+```bash
+cd tools/mcp-server
+npm install
+npm run build
+npm test
+```
+
+## Architecture
+
+```
+Agent (Claude Code / Grok / Codex)
+  │
+  ├─ MCP Resource Read ──→ loop://patterns/daily-triage
+  ├─ MCP Tool Call ──→ loop_recommend_pattern("watch CI failures")
+  └─ MCP Tool Call ──→ loop_estimate_cost("ci-sweeper", "L2")
+  │
+  ▼
+loop-mcp-server (stdio transport)
+  │
+  ├─ resolver.ts ──→ reads patterns/, skills/, STATE.md, LOOP.md, etc.
+  └─ index.ts ──→ MCP protocol handlers
+```
+
+The server reads from the local filesystem at `LOOP_PROJECT_ROOT`. It is read-only — it never writes to the project.
+
+## See Also
+
+- [Loop Engineering Patterns](../../patterns/)
+- [MCP Examples](../../examples/mcp/)
+- [Primitives: Plugins & Connectors](../../docs/primitives.md)
+- [Safety: MCP Least Privilege](../../docs/safety.md)

tools/mcp-server/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+declare const server: McpServer;
+export { server };