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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
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.jsindex 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/mcimport { 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.jsonindex 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": truediff --git a/tools/mcp-server/package.json b/tools/mcp-server/package.jsonindex 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.tsindex 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/mcimport { 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.mjsindex 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 {