claude-faf-mcp 5.7.0 → 5.7.2

package/CHANGELOG.md

@@ -1,5 +1,5 @@
 <!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude Desktop — persistent project context, 32 tools -->
-<!-- faf: doc=changelog | latest=v5.7.0 | canonical=project.faf | family=FAF -->
+<!-- faf: doc=changelog | latest=v5.7.2 | canonical=project.faf | family=FAF -->
 
 # Changelog
 
@@ -9,6 +9,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+
+**Interop now enhances your files.** The same solid, structured `.faf` data is prefixed to the top of your context files for rapid AI consumption upfront — and your Markdown stays in the instruction lane.
+
+### Changed
+
+- **Non-destructive interop.** `faf_agents`, `faf_gemini`, `faf_cursor`, and `faf_sync` now inject a structured `.faf` block at the top of AGENTS.md, GEMINI.md, .cursorrules, and CLAUDE.md and preserve everything you've written below. Re-runs update the block in place (idempotent); existing faf-generated files upgrade cleanly in one pass.
+
+## [5.7.2] - 2026-06-11 — The Canonical Edition
+
+### Security
+- **Path confinement on every caller-supplied `path` argument (CWE-22 / CWE-73 / CWE-200).** The shared `getProjectPath()` chokepoint (feeding the `.faf` tools) and the `faf_read` / `faf_write` file tools resolved a caller path straight into a filesystem read/write with no confinement — so an absolute path or `../` traversal could read any file the server process could read (e.g. `/etc/passwd`, `~/.ssh/id_rsa`) or write outside the project. New `safe-path.ts` confines reads to `.faf` / `.fafm` context files and general file ops to the project root (cwd + system temp; override with `FAF_ALLOWED_ROOTS`), canonicalizes through symlinks (closing the symlink bypass), and rejects traversal/absolute escapes; `callTool()` gains a central PATH-DENIED guard. Identified by the maintainers during a sibling-server audit prompted by the coordinated disclosure of the same class of issue in `grok-faf-mcp` by Zhihao Zhang (Worcester Polytechnic Institute). Adds a security regression suite (incl. symlink bypass).
+
+## [5.7.1] - 2026-06-10 — The Canonical Edition
+
+Typed structured output and one-click registry install — the reliability layer made machine-readable.
+
+### Added
+
+- **MCP `structuredContent` + `outputSchema`** on `faf_score` and `faf_status` — typed structured results (score, tier, populated/empty/ignored/total, next tier; status, filename, path) returned alongside the human-readable text on every path. Spec 2025-06-18; text retained for backward compatibility.
+- **`mcpb` registry package** in `server.json` — one-click Claude Desktop install from the MCP registry, pointing at the released `.mcpb` with its SHA-256.
+
+### Fixed
+
+- **README one-click link** pointed at `claude-faf-mcp-5.5.2.mcpb` (404 on the current release) → now the live bundle.
+
+### Changed
+
+- **No stale version references** — faf-cli bumped to `^6.8.0` (latest); `project.faf` `faf_version` corrected to `2.5.0` (matches the latest tooling / base tier, not the enterprise 33-slot marker); `docs/index.html` version badge and a hardcoded server-info version string now track the package version.
+
+
 ## [5.7.0] - 2026-06-09 — The Canonical Edition
 
 The original FAF MCP, made canonical: the registry remote now hits the live

package/CLAUDE.md

@@ -1,11 +1,11 @@
-<!-- faf: claude-faf-mcp | TypeScript | mcp | Universal FAF MCP Server for Claude Desktop - AI Context Intelligence -->
+<!-- faf: claude-faf-mcp | TypeScript | mcp | Persistent project context for Claude — define once, never re-explain -->
 <!-- faf: claim=project.faf | family=FAF -->
 
 # CLAUDE.md — claude-faf-mcp
 
 ## What This Is
 
-Universal FAF MCP Server for Claude Desktop - AI Context Intelligence
+Persistent project context for Claude — define once, never re-explain
 
 ## Stack
 
@@ -14,18 +14,18 @@ Universal FAF MCP Server for Claude Desktop - AI Context Intelligence
 - **Api Type:** MCP (stdio + Streamable HTTP)
 - **Runtime:** Node.js
 - **Hosting:** npm/Claude Desktop
-- **Build:** esbuild
+- **Build:** tsc
 - **Cicd:** GitHub Actions
 
 ## Context
 
-- **Who:** Claude Desktop users who want persistent AI project context
-- **What:** MCP server — 32 FAF tools for project DNA, scoring, and context sync
-- **Why:** Zero project re-explaining across AI sessions — define once, remember forever
-- **Where:** npm, Claude Desktop, MCP Registry (io.github.Wolfe-Jam/claude-faf-mcp)
-- **When:** v5.7.0 (The Canonical Edition), June 2026
-- **How:** npm install -g claude-faf-mcp
+- **Who:** Claude Desktop + Code devs
+- **What:** Persistent project-context MCP server
+- **Why:** Define once, never re-explain
+- **Where:** npm, Claude, MCP registry
+- **When:** Every coding session
+- **How:** One-click .mcpb install
 
 ---
 
-*STATUS: BI-SYNC ACTIVE — 2026-06-09T12:52:07.994Z*
+*STATUS: BI-SYNC ACTIVE — 2026-06-10T01:27:09.822Z*

package/README.md

@@ -26,7 +26,7 @@
 
 > ⚡ **New: `/faf` prompt** — type `/faf` in Claude Desktop. It checks your project, scores it, drives it to 100%, and syncs. Relentlessly. One command.
 
-> 🏆 **v5.7.0 — The Canonical Edition.** The original FAF MCP, made canonical: the registry remote now hits the live Cloudflare edge directly (no Vercel/SSE redirect), the redundant `faf_chat` shim is retired (the host is your chat) — consolidated into 32 must-have tools.
+> 🏆 **v5.7.2 — The Canonical Edition.** Security patch — caller-supplied `path` arguments are now confined: reads are restricted to `.faf` / `.fafm` context files and file ops to the project root (override with `FAF_ALLOWED_ROOTS`), closing an arbitrary local file read. Built on the Canonical foundation: typed structured output (`structuredContent` + output schemas), edge-direct remote, 32 must-have tools.
 
 32 MCP tools. IANA-registered formats (`application/vnd.faf+yaml` · `application/vnd.fafm+yaml`). 2,538 test executions per push.
 
@@ -82,7 +82,7 @@ Same `.faf`, every surface — Claude, Gemini, Grok, Cursor. **[faf-cli on npm
 
 **Click** — one-click `.mcpb`
 
-[**⬇ Download `claude-faf-mcp-5.5.2.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.5.2.mcpb)
+[**⬇ Download `claude-faf-mcp-5.7.2.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.7.2.mcpb)
 
 Double-click. **No terminal. No JSON config. 32 tools live in 10 seconds.**
 

package/dist/src/faf-core/commands/bi-sync.js

@@ -45,6 +45,7 @@ const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const file_utils_1 = require("../utils/file-utils");
 const agents_js_1 = require("./agents.js");
+const inject_1 = require("../inject");
 const cursor_js_1 = require("./cursor.js");
 const gemini_js_1 = require("./gemini.js");
 /**
@@ -134,7 +135,7 @@ async function syncBiDirectional(projectPath, _options = {}) {
         if (!claudeMdExists) {
             // Create CLAUDE.md from project.faf
             const claudeMdContent = fafToClaudeMd(fafContent);
-            await fs_1.promises.writeFile(claudeMdPath, claudeMdContent, 'utf-8');
+            await (0, inject_1.injectFafBlock)(claudeMdPath, claudeMdContent);
             result.success = true;
             result.direction = 'faf-to-claude';
             result.filesChanged.push('CLAUDE.md');
@@ -143,7 +144,7 @@ async function syncBiDirectional(projectPath, _options = {}) {
         else {
             // Both files exist - update CLAUDE.md from project.faf
             const claudeMdContent = fafToClaudeMd(fafContent);
-            await fs_1.promises.writeFile(claudeMdPath, claudeMdContent, 'utf-8');
+            await (0, inject_1.injectFafBlock)(claudeMdPath, claudeMdContent);
             result.success = true;
             result.direction = 'faf-to-claude';
             result.filesChanged.push('CLAUDE.md');

package/dist/src/faf-core/inject.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Block markers for the faf-managed front section. Markdown files use HTML
+ * comments; non-markdown files (.cursorrules) pass hash-comment markers.
+ */
+export declare const FAF_START = "<!-- faf:start -->";
+export declare const FAF_END = "<!-- faf:end -->";
+/**
+ * Non-destructively write a faf-managed block into a file.
+ *
+ *   - no file                                 -> create it with just the block
+ *   - markers present                         -> replace ONLY between them (update in place)
+ *   - legacy faf file (metastamp, no markers) -> reclaim in place (no duplication)
+ *   - genuine user file                       -> prefix the block; preserve everything below
+ *
+ * Idempotent: re-runs update the block, never duplicate or destroy user content.
+ * faf owns what's between the markers; the user owns everything else.
+ * Enhance, never replace.
+ */
+export declare function injectFafBlock(path: string, block: string, start?: string, end?: string): Promise<void>;

package/dist/src/faf-core/inject.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAF_END = exports.FAF_START = void 0;
+exports.injectFafBlock = injectFafBlock;
+const fs_1 = require("fs");
+/**
+ * Block markers for the faf-managed front section. Markdown files use HTML
+ * comments; non-markdown files (.cursorrules) pass hash-comment markers.
+ */
+exports.FAF_START = '<!-- faf:start -->';
+exports.FAF_END = '<!-- faf:end -->';
+/**
+ * faf's own metastamp fingerprint. Every faf-generated file begins with it and a
+ * user never hand-writes it — so a markerless file led by it is legacy faf output
+ * we can safely reclaim, never genuine user content.
+ */
+const FAF_METASTAMP = '<!-- faf:';
+/**
+ * Non-destructively write a faf-managed block into a file.
+ *
+ *   - no file                                 -> create it with just the block
+ *   - markers present                         -> replace ONLY between them (update in place)
+ *   - legacy faf file (metastamp, no markers) -> reclaim in place (no duplication)
+ *   - genuine user file                       -> prefix the block; preserve everything below
+ *
+ * Idempotent: re-runs update the block, never duplicate or destroy user content.
+ * faf owns what's between the markers; the user owns everything else.
+ * Enhance, never replace.
+ */
+async function injectFafBlock(path, block, start = exports.FAF_START, end = exports.FAF_END) {
+    const wrapped = `${start}\n${block.trim()}\n${end}`;
+    let existing = null;
+    try {
+        existing = await fs_1.promises.readFile(path, 'utf-8');
+    }
+    catch {
+        existing = null; // file does not exist yet
+    }
+    if (existing === null) {
+        await fs_1.promises.writeFile(path, `${wrapped}\n`, 'utf-8');
+        return;
+    }
+    const s = existing.indexOf(start);
+    const e = existing.indexOf(end);
+    if (s !== -1 && e !== -1 && e > s) {
+        await fs_1.promises.writeFile(path, existing.slice(0, s) + wrapped + existing.slice(e + end.length), 'utf-8');
+        return;
+    }
+    if (existing.trimStart().startsWith(FAF_METASTAMP)) {
+        // Legacy faf output — reclaim in place, no duplication.
+        await fs_1.promises.writeFile(path, `${wrapped}\n`, 'utf-8');
+        return;
+    }
+    // Genuine user file — prefix the block, preserve everything.
+    await fs_1.promises.writeFile(path, `${wrapped}\n\n${existing}`, 'utf-8');
+}
+//# sourceMappingURL=inject.js.map

package/dist/src/faf-core/parsers/agents-parser.js

@@ -23,6 +23,7 @@ exports.detectAgentsMd = detectAgentsMd;
 exports.detectGlobalAgentsMd = detectGlobalAgentsMd;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const inject_1 = require("../inject");
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -278,9 +279,9 @@ async function agentsExport(fafContent, outputPath) {
     lines.push('---');
     lines.push(`*Generated from project.faf by claude-faf-mcp — ${new Date().toISOString().split('T')[0]}*`);
     lines.push('');
-    // Write file
+    // Write file — non-destructive: inject/update the faf block, preserve the rest.
     const content = lines.join('\n');
-    await fs_1.promises.writeFile(outputPath, content);
+    await (0, inject_1.injectFafBlock)(outputPath, content);
     return {
         success: true,
         filePath: outputPath,

package/dist/src/faf-core/parsers/cursorrules-parser.js

@@ -25,6 +25,7 @@ exports.cursorExport = cursorExport;
 exports.detectCursorRules = detectCursorRules;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const inject_1 = require("../inject");
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -41,6 +42,9 @@ function parseCursorRules(content) {
     const rawLines = [];
     for (const line of lines) {
         rawLines.push(line);
+        // Skip faf's own block markers — they are not headings or content.
+        if (line.trim() === '# faf:start' || line.trim() === '# faf:end')
+            continue;
         // H1 = Project name
         const h1Match = line.match(/^#\s+(?:Project:\s*)?(.+)$/);
         if (h1Match) {
@@ -286,9 +290,9 @@ async function cursorExport(fafContent, outputPath) {
     lines.push('---');
     lines.push(`Generated from project.faf by claude-faf-mcp — ${new Date().toISOString().split('T')[0]}`);
     lines.push('');
-    // Write file
+    // Write file — non-destructive: inject/update the faf block (hash-comment markers), preserve the rest.
     const content = lines.join('\n');
-    await fs_1.promises.writeFile(outputPath, content);
+    await (0, inject_1.injectFafBlock)(outputPath, content, '# faf:start', '# faf:end');
     return {
         success: true,
         filePath: outputPath,

package/dist/src/faf-core/parsers/gemini-parser.js

@@ -23,6 +23,7 @@ exports.detectGeminiMd = detectGeminiMd;
 exports.detectGlobalGeminiMd = detectGlobalGeminiMd;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const inject_1 = require("../inject");
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -218,9 +219,9 @@ async function geminiExport(fafContent, outputPath) {
         }
         lines.push('');
     }
-    // Write file
+    // Write file — non-destructive: inject/update the faf block, preserve the rest.
     const content = lines.join('\n');
-    await fs_1.promises.writeFile(outputPath, content);
+    await (0, inject_1.injectFafBlock)(outputPath, content);
     return {
         success: true,
         filePath: outputPath,

package/dist/src/fafa/a2a-card.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `.fafa` → A2A AgentCard mapper.
+ *
+ * Maps CFM's FAF Agent Card (`.fafa`) to a conformant **A2A AgentCard**
+ * (A2A protocol v1.0, served at `/.well-known/a2a-agent-card`).
+ *
+ * Posture: `.fafa` is a PEER to the A2A AgentCard — **compatible + enhancing**.
+ * Every A2A field maps from `.fafa`; the enhancement is the **FAF context block**,
+ * which rides as an A2A extension (`one.faf/context`) — byte-equivalent to the MCP
+ * server-card `_meta["one.faf/context"]`. One context, every door.
+ *
+ * Pure mapper (testable). The live A2A *invocation* endpoint (JSON-RPC `message/send`)
+ * is served at the edge — this module produces the discovery card that points at it.
+ */
+export declare const A2A_PROTOCOL_VERSION = "1.0";
+export declare const A2A_WELL_KNOWN_PATH = "/.well-known/a2a-agent-card";
+export interface A2AAgentSkill {
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+export interface A2AAgentCard {
+    protocolVersion: string;
+    name: string;
+    description?: string;
+    url: string;
+    version?: string;
+    provider?: {
+        organization?: string;
+        url?: string;
+    };
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        extendedAgentCard: boolean;
+    };
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: A2AAgentSkill[];
+    extensions?: {
+        uri: string;
+        description?: string;
+        required: boolean;
+        params?: Record<string, unknown>;
+    }[];
+}
+/** Map a parsed `.fafa` document to a conformant A2A AgentCard. */
+export declare function fafaToA2ACard(fafa: any, opts: {
+    url: string;
+}): A2AAgentCard;

package/dist/src/fafa/a2a-card.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * `.fafa` → A2A AgentCard mapper.
+ *
+ * Maps CFM's FAF Agent Card (`.fafa`) to a conformant **A2A AgentCard**
+ * (A2A protocol v1.0, served at `/.well-known/a2a-agent-card`).
+ *
+ * Posture: `.fafa` is a PEER to the A2A AgentCard — **compatible + enhancing**.
+ * Every A2A field maps from `.fafa`; the enhancement is the **FAF context block**,
+ * which rides as an A2A extension (`one.faf/context`) — byte-equivalent to the MCP
+ * server-card `_meta["one.faf/context"]`. One context, every door.
+ *
+ * Pure mapper (testable). The live A2A *invocation* endpoint (JSON-RPC `message/send`)
+ * is served at the edge — this module produces the discovery card that points at it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A2A_WELL_KNOWN_PATH = exports.A2A_PROTOCOL_VERSION = void 0;
+exports.fafaToA2ACard = fafaToA2ACard;
+exports.A2A_PROTOCOL_VERSION = '1.0';
+exports.A2A_WELL_KNOWN_PATH = '/.well-known/a2a-agent-card';
+/** Map a parsed `.fafa` document to a conformant A2A AgentCard. */
+function fafaToA2ACard(fafa, opts) {
+    const agent = fafa?.agent ?? {};
+    const card = {
+        protocolVersion: exports.A2A_PROTOCOL_VERSION,
+        name: agent.name,
+        description: agent.description,
+        url: opts.url, // A2A service endpoint (JSON-RPC) — served at the edge
+        version: agent.version,
+        provider: { organization: agent.vendor, url: agent.homepage },
+        // CFM's tools are synchronous request/response; no streaming/push yet.
+        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+        defaultInputModes: ['text/plain', 'application/json'],
+        defaultOutputModes: ['text/plain', 'application/json'],
+        // A2A skill ≡ FAF capability ≡ MCP tool (per AGENT-FORMAT §3).
+        skills: (fafa?.capabilities ?? []).map((c) => ({
+            id: c.name,
+            name: c.name,
+            description: c.description,
+            tags: Array.isArray(c.tags) ? c.tags : [],
+        })),
+    };
+    // The enhancement: the FAF context block as an A2A extension (the durable middle).
+    if (fafa?.provenance) {
+        card.extensions = [{
+                uri: 'https://one.faf/context',
+                description: 'FAF context provenance — the durable context block (one context, every door).',
+                required: false,
+                params: fafa.provenance,
+            }];
+    }
+    return card;
+}
+//# sourceMappingURL=a2a-card.js.map

package/dist/src/fafm/faf-memory.d.ts

@@ -0,0 +1,72 @@
+export type Priority = 'ephemeral' | 'standard' | 'high' | 'critical';
+/** Normalise a priority string: map legacy aliases, default unknowns to `standard`. */
+export declare function canonicalPriority(p?: string | null): Priority;
+export interface Fact {
+    text: string;
+    id?: string;
+    type?: string;
+    priority: Priority;
+    tags: string[];
+    links: string[];
+    timestamp?: string;
+    source?: string;
+}
+export interface EtchInput {
+    text: string;
+    id?: string;
+    type?: string;
+    priority?: string;
+    tags?: string[];
+    links?: string[];
+    source?: string;
+}
+export interface RecallOpts {
+    query?: string;
+    tags?: string[];
+    type?: string;
+    minPriority?: string;
+    limit?: number;
+}
+/** A loaded `.fafm` knowledge soul + its basic offline memory ops. */
+export declare class Soul {
+    namepoint: string;
+    profile: string;
+    retention: string;
+    created: string;
+    last_etched: string;
+    private _facts;
+    private _byId;
+    constructor(namepoint: string, opts?: {
+        profile?: string;
+        facts?: Fact[];
+        retention?: string;
+        created?: string;
+    });
+    get facts(): Fact[];
+    static fromObj(o: any): Fact;
+    /** Load a `.fafm` soul from disk; namepoint defaults to the filename stem. */
+    static load(soulPath: string): Soul;
+    /** Load if the soul exists, else a fresh empty soul (offline-first, no account). */
+    static open(soulPath: string, namepoint?: string): Soul;
+    private factToObj;
+    toDoc(): Record<string, any>;
+    toYaml(): string;
+    save(soulPath: string): string;
+    /** Insert or update a Fact by id (O(1) dedup); else append. The merge primitive. */
+    add(fact: Fact): Fact;
+    /** Write a fact. If `id` matches an existing fact it's updated in place; else appended. */
+    etch(input: EtchInput): Fact;
+    /**
+     * Deterministic recall: case-insensitive substring on `text`, tag intersection,
+     * type equality, priority floor — ranked by priority, then recency, then
+     * insertion index (so the most-recently-etched fact always wins ties).
+     */
+    recall(opts?: RecallOpts): Fact[];
+    getFact(id: string): Fact | undefined;
+    /** The lean index — one-liners for always-loaded recall (`id — text`). */
+    index(): {
+        id: string;
+        text: string;
+        priority: Priority;
+    }[];
+}