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
fix(mcp-server): path traversal guards + discoverability docs (#72)
Cobus Greyling5003275a85cd
diff --git a/README.md b/README.mdindex bfae230..0f1425c 100644--- a/README.md+++ b/README.md@@ -75,6 +75,7 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.4 + activity detection) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README || [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` || [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |+| [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `node tools/mcp-server/dist/index.js` (repo v1; npm pending) || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | Companion: Grok Build `/goal` — run-until-done objectives (`npx @cobusgreyling/goal-audit`) || [Stories](stories/) | Real wins and honest failures |diff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex 5770aa3..77f5755 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -12,6 +12,8 @@ Tool-agnostic loop design: the **capability** is what matters, not the product n| **Sub-agents** | Maker / checker split | `Task` tool with `subagent_type`, worktree isolation | Task subagents in `.claude/agents/`, agent teams | Subagents as TOML in `.codex/agents/` | `agents.list` multi-agent routing; isolated cron subagent orchestration; separate verifier agent id | Multi-agent mode, review mode, custom agents in `.cursor/agents/` | Multiple Cascades in parallel; workflow-orchestrated implementer → reviewer steps || **State / Memory** | Track what's done across runs | `STATE.md`, todos, durable scheduler state | `AGENTS.md`, progress files, Linear via MCP | Markdown or Linear via connector | `STATE.md`, `HEARTBEAT.md` in workspace; cron persisted in Gateway SQLite; Skill Workshop for skill proposals | `STATE.md`, `LOOP.md`, Cloud Agent memories | `STATE.md`, Cascade **Memories**, workflow run notes |+**Reference MCP server:** this repo ships [`tools/mcp-server/`](../tools/mcp-server/) — patterns, skills, state, budget, and safety docs as runtime-queryable MCP resources (reduces prompt stuffing). Config example: [`examples/mcp/loop-engineering.mcp.json`](../examples/mcp/loop-engineering.mcp.json).+## Scheduling Quick Reference| Use case | Grok | Claude Code | Codex | OpenClaw | Cursor | Windsurf |diff --git a/examples/README.md b/examples/README.mdindex 4d02edb..f4d24b1 100644--- a/examples/README.md+++ b/examples/README.md@@ -9,7 +9,7 @@ Same patterns, different tools. Skills and state schemas are shared; only schedu| Codex App | [codex/](./codex/) || OpenClaw | [openclaw/](./openclaw/) || GitHub Actions | [github-actions/](./github-actions/) |-| MCP connectors | [mcp/](./mcp/) |+| MCP connectors | [mcp/](./mcp/) — config example; reference server in [tools/mcp-server/](../tools/mcp-server/) |Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilities.diff --git a/tools/mcp-server/README.md b/tools/mcp-server/README.mdindex 99c0e48..554aa22 100644--- a/tools/mcp-server/README.md+++ b/tools/mcp-server/README.md@@ -6,10 +6,15 @@ Instead of stuffing all loop documentation into the prompt, agents can query onl## Quick Start+**v1 ships from this repo** (npm publish pending). From a cloned `loop-engineering` repo:+```bash-npx @cobusgreyling/loop-mcp-server+cd tools/mcp-server && npm ci && npm test+node dist/index.js```+Set `LOOP_PROJECT_ROOT` to your target project (defaults to `cwd`).+### Configure in Claude Code / Grok / any MCP clientAdd to your MCP config (`.mcp.json` or equivalent):diff --git a/tools/mcp-server/dist/resolver.d.ts b/tools/mcp-server/dist/resolver.d.tsindex 939d647..17d238e 100644--- a/tools/mcp-server/dist/resolver.d.ts+++ b/tools/mcp-server/dist/resolver.d.ts@@ -1,3 +1,5 @@+/** Reject path segments that could escape the project root. */+export declare function assertSafeSegment(name: string, label: string): void;export declare function fileExists(p: string): Promise<boolean>;export declare function resolveProjectRoot(hint?: string): Promise<string>;export declare function readFileIfExists(filePath: string): Promise<string | null>;diff --git a/tools/mcp-server/dist/resolver.js b/tools/mcp-server/dist/resolver.jsindex 4766860..551cc01 100644--- a/tools/mcp-server/dist/resolver.js+++ b/tools/mcp-server/dist/resolver.js@@ -1,5 +1,26 @@import { readdir, readFile, stat } from 'node:fs/promises';import path from 'node:path';+const STATE_FILE_CANDIDATES = [+ 'STATE.md',+ 'pr-babysitter-state.md',+ 'ci-sweeper-state.md',+ 'post-merge-state.md',+ 'dependency-sweeper-state.md',+ 'changelog-drafter-state.md',+ 'issue-triage-state.md',+];+/** Reject path segments that could escape the project root. */+export function assertSafeSegment(name, label) {+ if (!name || name.includes('\0') || name.includes('..') || name.includes('/') || name.includes('\\')) {+ throw new Error(`Invalid ${label}: ${name}`);+ }+}+async function allowedPatternIds(root) {+ const registry = await loadRegistry(root);+ if (registry)+ return new Set(registry.patterns.map((p) => p.id));+ return new Set(await listPatternDocs(root));+}export async function fileExists(p) {try {await stat(p);@@ -33,6 +54,15 @@ export async function loadRegistry(root) {return parse(content);}export async function loadPatternDoc(root, patternId) {+ try {+ assertSafeSegment(patternId, 'patternId');+ }+ catch {+ return null;+ }+ const allowed = await allowedPatternIds(root);+ if (!allowed.has(patternId))+ return null;const filePath = path.join(root, 'patterns', `${patternId}.md`);return readFileIfExists(filePath);}@@ -69,20 +99,19 @@ export async function loadSkill(root, skillName) {}export async function loadState(root, stateFile) {const target = stateFile ?? 'STATE.md';+ try {+ assertSafeSegment(target, 'stateFile');+ }+ catch {+ return null;+ }+ if (!STATE_FILE_CANDIDATES.includes(target))+ return null;return readFileIfExists(path.join(root, target));}export async function listStateFiles(root) {- const candidates = [- 'STATE.md',- 'pr-babysitter-state.md',- 'ci-sweeper-state.md',- 'post-merge-state.md',- 'dependency-sweeper-state.md',- 'changelog-drafter-state.md',- 'issue-triage-state.md',- ];const found = [];- for (const f of candidates) {+ for (const f of STATE_FILE_CANDIDATES) {if (await fileExists(path.join(root, f)))found.push(f);}diff --git a/tools/mcp-server/src/resolver.ts b/tools/mcp-server/src/resolver.tsindex 8e85bd5..d5bed35 100644--- a/tools/mcp-server/src/resolver.ts+++ b/tools/mcp-server/src/resolver.ts@@ -1,6 +1,29 @@import { readdir, readFile, stat } from 'node:fs/promises';import path from 'node:path';+const STATE_FILE_CANDIDATES = [+ 'STATE.md',+ 'pr-babysitter-state.md',+ 'ci-sweeper-state.md',+ 'post-merge-state.md',+ 'dependency-sweeper-state.md',+ 'changelog-drafter-state.md',+ 'issue-triage-state.md',+] as const;++/** Reject path segments that could escape the project root. */+export function assertSafeSegment(name: string, label: string): void {+ if (!name || name.includes('\0') || name.includes('..') || name.includes('/') || name.includes('\\')) {+ throw new Error(`Invalid ${label}: ${name}`);+ }+}++async function allowedPatternIds(root: string): Promise<Set<string>> {+ const registry = await loadRegistry(root);+ if (registry) return new Set(registry.patterns.map((p) => p.id));+ return new Set(await listPatternDocs(root));+}+export async function fileExists(p: string): Promise<boolean> {try {await stat(p);@@ -69,6 +92,13 @@ export async function loadRegistry(root: string): Promise<RegistryData | null> {}export async function loadPatternDoc(root: string, patternId: string): Promise<string | null> {+ try {+ assertSafeSegment(patternId, 'patternId');+ } catch {+ return null;+ }+ const allowed = await allowedPatternIds(root);+ if (!allowed.has(patternId)) return null;const filePath = path.join(root, 'patterns', `${patternId}.md`);return readFileIfExists(filePath);}@@ -106,21 +136,18 @@ export async function loadSkill(root: string, skillName: string): Promise<SkillIexport async function loadState(root: string, stateFile?: string): Promise<string | null> {const target = stateFile ?? 'STATE.md';+ try {+ assertSafeSegment(target, 'stateFile');+ } catch {+ return null;+ }+ if (!(STATE_FILE_CANDIDATES as readonly string[]).includes(target)) return null;return readFileIfExists(path.join(root, target));}export async function listStateFiles(root: string): Promise<string[]> {- const candidates = [- 'STATE.md',- 'pr-babysitter-state.md',- 'ci-sweeper-state.md',- 'post-merge-state.md',- 'dependency-sweeper-state.md',- 'changelog-drafter-state.md',- 'issue-triage-state.md',- ];const found: string[] = [];- for (const f of candidates) {+ for (const f of STATE_FILE_CANDIDATES) {if (await fileExists(path.join(root, f))) found.push(f);}return found;diff --git a/tools/mcp-server/test/server.test.mjs b/tools/mcp-server/test/server.test.mjsindex 24c9c2b..294502c 100644--- a/tools/mcp-server/test/server.test.mjs+++ b/tools/mcp-server/test/server.test.mjs@@ -327,6 +327,29 @@ test('loadPatternDoc returns null for missing pattern', async () => {}});+test('loadPatternDoc rejects path traversal pattern ids', async () => {+ const root = await setup();+ try {+ assert.equal(await loadPatternDoc(root, '../README'), null);+ assert.equal(await loadPatternDoc(root, 'daily-triage/..'), null);+ assert.equal(await loadPatternDoc(root, '..\\README'), null);+ } finally {+ await cleanup();+ }+});++test('loadState rejects path traversal state files', async () => {+ const root = await setup();+ try {+ assert.equal(await loadState(root, '../LOOP.md'), null);+ assert.equal(await loadState(root, 'STATE.md/../../LOOP.md'), null);+ const state = await loadState(root, 'STATE.md');+ assert.ok(state?.includes('Fix CI'));+ } finally {+ await cleanup();+ }+});+// ── Integration: real server over stdio ────────────────────────────test('server lists all tools over stdio', async () => {