Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

feat: expose loop-audit and circuit breaker over MCP (#360)

THRISHAL DOMAc2472796f625
diff --git a/tools/mcp-server/dist/index.js b/tools/mcp-server/dist/index.js
index e79e04c..ab9ed0b 100755
--- a/tools/mcp-server/dist/index.js
+++ b/tools/mcp-server/dist/index.js
@@ -3,7 +3,10 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import path from 'node:path';
+import { readFile } from 'node:fs/promises';
import { loadGateConfig, checkGate } from '@cobusgreyling/loop-gate';
+import { auditProject } from '@cobusgreyling/loop-audit/dist/auditor.js';
+import { checkCircuitBreaker, DEFAULT_BREAKER } from '@cobusgreyling/loop-context';
import { resolveProjectRoot, loadRegistry, loadPatternDoc, listSkills, loadSkill, loadState, listStateFiles, loadLoopConfig, loadBudget, loadRunLog, loadSafetyDoc, listPatternDocs, loadGatePolicy, } from './resolver.js';
const server = new McpServer({
name: 'loop-engineering',
@@ -294,9 +297,9 @@ server.tool('loop_estimate_cost', 'Estimate daily token cost for a pattern at a
}
const { cost } = pattern;
const mix = level === 'L1'
- ? { noop: 0.7, report: 0.3, action: 0 }
+ ? { noop: 0.6, report: 0.4, action: 0 }
: level === 'L2'
- ? { noop: 0.6, report: 0.25, action: 0.15 }
+ ? { noop: 0.5, report: 0.3, action: 0.2 }
: { noop: 0.4, report: 0.35, action: 0.25 };
const realisticPerRun = cost.tokens_noop * mix.noop
+ cost.tokens_report * mix.report
@@ -348,6 +351,57 @@ server.tool('loop_gate_check', 'Evaluate a proposed change against the static sa
}
return { content: [{ type: 'text', text: lines.join('\n') }] };
});
+server.tool('loop_audit_score', 'Audit the current project for Loop Readiness (L0-L3), cost observability, governance, and harness runtime signals.', { target: z.string().optional().describe('Target directory to audit (default: .)') }, async ({ target }) => {
+ const root = await resolveProjectRoot(target);
+ try {
+ const result = await auditProject(root);
+ const lines = [
+ `## Loop Readiness: ${result.score}/100 (${result.level})`,
+ result.assessment,
+ ''
+ ];
+ for (const f of result.findings) {
+ const icon = f.level === 'ok' ? '✅' : f.level === 'warn' ? '⚠️' : '❌';
+ lines.push(`- ${icon} ${f.message}`);
+ }
+ if (result.recommendations.length > 0) {
+ lines.push('', '## Recommendations');
+ for (const r of result.recommendations)
+ lines.push(`- ${r}`);
+ }
+ return { content: [{ type: 'text', text: lines.join('\n') }] };
+ }
+ catch (err) {
+ return { content: [{ type: 'text', text: `Error running loop-audit: ${err.message}` }] };
+ }
+});
+server.tool('loop_check_breaker', 'Check the current circuit breaker status to detect stagnation, frustration, or if the agent should hand off to a human.', {}, async () => {
+ const root = await resolveProjectRoot();
+ const ledgerPath = path.join(root, 'loop-ledger.json');
+ let ledgerContent;
+ try {
+ ledgerContent = await readFile(ledgerPath, 'utf8');
+ }
+ catch {
+ return { content: [{ type: 'text', text: 'No loop-ledger.json found. Circuit breaker is inactive.' }] };
+ }
+ let ledger;
+ try {
+ ledger = JSON.parse(ledgerContent);
+ }
+ catch (err) {
+ return { content: [{ type: 'text', text: `Error parsing loop-ledger.json: ${err.message}` }] };
+ }
+ const decision = checkCircuitBreaker(ledger, DEFAULT_BREAKER);
+ const lines = [
+ `## Circuit Breaker: ${decision.escalate ? '🛑 ESCALATE' : '✅ OK'}`,
+ `- **Trigger:** ${decision.trigger}`,
+ `- **Reason:** ${decision.reason}`,
+ `- **Iterations Used:** ${decision.iterations} / ${DEFAULT_BREAKER.maxIterations}`,
+ `- **Tokens Used:** ${decision.tokensUsed}`,
+ ];
+ return { content: [{ type: 'text', text: lines.join('\n') }] };
+});
// ── Start ──────────────────────────────────────────────────────────
async function main() {
const transport = new StdioServerTransport();
diff --git a/tools/mcp-server/package-lock.json b/tools/mcp-server/package-lock.json
index 64e11e7..1252b0c 100644
--- a/tools/mcp-server/package-lock.json
+++ b/tools/mcp-server/package-lock.json
@@ -9,6 +9,8 @@
"version": "1.1.0",
"license": "MIT",
"dependencies": {
+ "@cobusgreyling/loop-audit": "file:../loop-audit",
+ "@cobusgreyling/loop-context": "file:../loop-context",
"@cobusgreyling/loop-gate": "file:../loop-gate",
"@modelcontextprotocol/sdk": "^1.12.1",
"minimatch": "^10.2.5",
@@ -26,6 +28,42 @@
"node": ">=18"
}
},
+ "../loop-audit": {
+ "name": "@cobusgreyling/loop-audit",
+ "version": "1.7.0",
+ "license": "MIT",
+ "dependencies": {
+ "@cobusgreyling/readiness-core": "file:../readiness-core"
+ },
+ "bin": {
+ "loop-audit": "dist/cli.js"
+ },
+ "devDependencies": {
+ "@types/node": "^26.0.0",
+ "typescript": "^7.0.2"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "../loop-context": {
+ "name": "@cobusgreyling/loop-context",
+ "version": "1.5.0",
+ "license": "MIT",
+ "dependencies": {
+ "@cobusgreyling/loop-cost": "^1.1.0"
+ },
+ "bin": {
+ "loop-context": "dist/cli.js"
+ },
+ "devDependencies": {
+ "@types/node": "^20.0.0",
+ "typescript": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"../loop-gate": {
"name": "@cobusgreyling/loop-gate",
"version": "1.0.0",
@@ -45,6 +83,14 @@
"node": ">=18"
}
},
+ "node_modules/@cobusgreyling/loop-audit": {
+ "resolved": "../loop-audit",
+ "link": true
+ },
+ "node_modules/@cobusgreyling/loop-context": {
+ "resolved": "../loop-context",
+ "link": true
+ },
"node_modules/@cobusgreyling/loop-gate": {
"resolved": "../loop-gate",
"link": true
diff --git a/tools/mcp-server/package.json b/tools/mcp-server/package.json
index f4b948b..f634bc5 100644
--- a/tools/mcp-server/package.json
+++ b/tools/mcp-server/package.json
@@ -43,6 +43,8 @@
"access": "public"
},
"dependencies": {
+ "@cobusgreyling/loop-audit": "file:../loop-audit",
+ "@cobusgreyling/loop-context": "file:../loop-context",
"@cobusgreyling/loop-gate": "file:../loop-gate",
"@modelcontextprotocol/sdk": "^1.12.1",
"minimatch": "^10.2.5",
diff --git a/tools/mcp-server/src/index.ts b/tools/mcp-server/src/index.ts
index a304bf9..b150b90 100644
--- a/tools/mcp-server/src/index.ts
+++ b/tools/mcp-server/src/index.ts
@@ -4,7 +4,10 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import path from 'node:path';
+import { readFile } from 'node:fs/promises';
import { loadGateConfig, checkGate } from '@cobusgreyling/loop-gate';
+import { auditProject } from '@cobusgreyling/loop-audit/dist/auditor.js';
+import { checkCircuitBreaker, DEFAULT_BREAKER, Ledger } from '@cobusgreyling/loop-context';
import {
resolveProjectRoot,
loadRegistry,
@@ -483,6 +486,69 @@ server.tool(
},
);
+server.tool(
+ 'loop_audit_score',
+ 'Audit the current project for Loop Readiness (L0-L3), cost observability, governance, and harness runtime signals.',
+ { target: z.string().optional().describe('Target directory to audit (default: .)') },
+ async ({ target }) => {
+ const root = await resolveProjectRoot(target);
+ try {
+ const result = await auditProject(root);
+ const lines = [
+ `## Loop Readiness: ${result.score}/100 (${result.level})`,
+ result.assessment,
+ ''
+ ];
+ for (const f of result.findings) {
+ const icon = f.level === 'ok' ? '✅' : f.level === 'warn' ? '⚠️' : '❌';
+ lines.push(`- ${icon} ${f.message}`);
+ }
+ if (result.recommendations.length > 0) {
+ lines.push('', '## Recommendations');
+ for (const r of result.recommendations) lines.push(`- ${r}`);
+ }
+ return { content: [{ type: 'text' as const, text: lines.join('\n') }] };
+ } catch (err: any) {
+ return { content: [{ type: 'text' as const, text: `Error running loop-audit: ${err.message}` }] };
+ }
+ },
+);
+
+server.tool(
+ 'loop_check_breaker',
+ 'Check the current circuit breaker status to detect stagnation, frustration, or if the agent should hand off to a human.',
+ {},
+ async () => {
+ const root = await resolveProjectRoot();
+ const ledgerPath = path.join(root, 'loop-ledger.json');
+ let ledgerContent;
+ try {
+ ledgerContent = await readFile(ledgerPath, 'utf8');
+ } catch {
+ return { content: [{ type: 'text' as const, text: 'No loop-ledger.json found. Circuit breaker is inactive.' }] };
+ }
+
+ let ledger: Ledger;
+ try {
+ ledger = JSON.parse(ledgerContent);
+ } catch (err: any) {
+ return { content: [{ type: 'text' as const, text: `Error parsing loop-ledger.json: ${err.message}` }] };
+ }
+
+ const decision = checkCircuitBreaker(ledger, DEFAULT_BREAKER);
+
+ const lines = [
+ `## Circuit Breaker: ${decision.escalate ? '🛑 ESCALATE' : '✅ OK'}`,
+ `- **Trigger:** ${decision.trigger}`,
+ `- **Reason:** ${decision.reason}`,
+ `- **Iterations Used:** ${decision.iterations} / ${DEFAULT_BREAKER.maxIterations}`,
+ `- **Tokens Used:** ${decision.tokensUsed}`,
+ ];
+
+ return { content: [{ type: 'text' as const, text: lines.join('\n') }] };
+ },
+);
+
// ── Start ──────────────────────────────────────────────────────────
async function main() {
diff --git a/tools/mcp-server/test/server.test.mjs b/tools/mcp-server/test/server.test.mjs
index a64da88..c126081 100644
--- a/tools/mcp-server/test/server.test.mjs
+++ b/tools/mcp-server/test/server.test.mjs
@@ -383,7 +383,7 @@ test('server lists all tools over stdio', async () => {
try {
const res = await callServer(root, [{ id: 1, method: 'tools/list', params: {} }]);
const names = res.get(1).result.tools.map(t => t.name);
- assert.equal(names.length, 9);
+ assert.equal(names.length, 11);
assert.ok(names.includes('loop_list_patterns'));
assert.ok(names.includes('loop_estimate_cost'));
} finally {