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.

fix(mcp-server): path traversal guards + discoverability docs (#72)

Cobus Greyling5003275a85cd
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.md
index 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 client
Add 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.ts
index 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.js
index 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.ts
index 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<SkillI
export 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.mjs
index 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 () => {