rust-faf-mcp 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wolfe-James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+<!-- faf: rust-faf-mcp | Rust | mcp-server | RMCP — the Rust-native MCP server for FAF (Foundational AI-context Format). Single binary, stdio transport, 4.3 MB stripped. cargo install rust-faf-mcp. Built on the rmcp Rust MCP SDK + faf-rust-sdk. -->
+<!-- mcp-name: one.faf/rust-faf-mcp -->
+
+
+# rust-faf-mcp
+
+**Persistent Project Context for Rust MCP clients. Native. Fast. cargo install**
+
+**The one.faf Edition (v0.4.0)** — `one.faf/rust-faf-mcp` · **rmcp 3.0.1** (MCP Tier 1 foundation) · solid cargo-native Rust MCP for Rust devs
+
+**FAF defines. MD instructs. AI codes.**
+
+> Stop re-explaining your project to every AI session. One `.faf` file holds your persistent project context. Every AI reads it once and knows what you're building.
+
+[![Crates.io](https://img.shields.io/crates/v/rust-faf-mcp?style=flat-square)](https://crates.io/crates/rust-faf-mcp)
+[![FAF](https://mcpaas.live/badge/Wolfe-Jam/rust-faf-mcp.svg)](https://builder.faf.one)
+[![Tests](https://img.shields.io/badge/tests-112%20passing-brightgreen?style=flat-square)](https://github.com/Wolfe-Jam/rust-faf-mcp)
+[![IANA](https://img.shields.io/badge/IANA-registered-informational?style=flat-square)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
+[![License](https://img.shields.io/crates/l/rust-faf-mcp?style=flat-square)](LICENSE)
+
+Rust-native [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for [FAF](https://faf.one) — structured AI project context in YAML (`application/vnd.faf+yaml`). Single binary, stdio transport, 4.3 MB stripped. Built on [`rmcp`](https://crates.io/crates/rmcp) and [`faf-rust-sdk`](https://crates.io/crates/faf-rust-sdk).
+
+## Quickstart
+
+```bash
+# Rust toolchain:
+cargo install rust-faf-mcp
+
+# No Rust (downloads GH Release binary for darwin/linux x64):
+npx rust-faf-mcp
+```
+
+
+Then point any MCP client at it:
+
+```bash
+# Claude Code
+claude mcp add faf rust-faf-mcp
+```
+
+```jsonc
+// WARP / Cursor / Zed / Claude Desktop — any stdio MCP client
+{
+  "mcpServers": {
+    "faf": {
+      "command": "rust-faf-mcp"
+    }
+  }
+}
+```
+
+No flags, no config files, no network listener. Pure stdio JSON-RPC.
+
+Or via Homebrew (macOS, pre-built):
+
+```bash
+brew install Wolfe-Jam/faf/rust-faf-mcp
+```
+
+## One command, done forever
+
+`faf_auto` detects your project, creates a `.faf`, enhances it to max score, and syncs `CLAUDE.md` — in one shot:
+
+```
+faf_auto complete
+━━━━━━━━━━━━━━━━━
+Score: 0% → 85% (+85) ◇ BRONZE
+Steps:
+  1. Created project.faf
+  2. Second enhancement pass
+  3. Created CLAUDE.md
+
+Path: /home/user/my-project
+```
+
+What it produces:
+
+```yaml
+# project.faf — your project, machine-readable
+faf_version: "3.3"
+project:
+  name: my-api
+  goal: REST API for user management
+  main_language: Rust
+  version: "0.1.0"
+  license: MIT
+instant_context:
+  what_building: REST API for user management
+  tech_stack: Rust 2024
+  key_files:
+    - Cargo.toml
+    - src/main.rs
+    - README.md
+  commands:
+    build: cargo build
+    test: cargo test
+stack:
+  backend: Rust
+  build_tool: cargo
+```
+
+Every AI agent reads this once and knows exactly what you're building. No 20-minute onboarding. No wrong assumptions.
+
+## Tools
+
+### Create & Detect
+
+| Tool | What it does |
+|------|-------------|
+| `faf_auto` | Zero to AI context in one command — init, enhance, sync, score, done |
+| `faf_init` | Create or enhance `project.faf` from `Cargo.toml`, `package.json`, `pyproject.toml`, or `go.mod` |
+| `faf_git` | Generate `project.faf` from any GitHub repo URL — no clone needed |
+| `faf_discover` | Walk up the directory tree to find the nearest `project.faf` |
+
+### Score & Validate
+
+| Tool | What it does |
+|------|-------------|
+| `faf_score` | Score AI-readiness 0-100% with field-level breakdown |
+| `faf_sync` | Sync `project.faf` → `CLAUDE.md` (preserves existing content) |
+
+### Optimize
+
+| Tool | What it does |
+|------|-------------|
+| `faf_read` | Parse and display `project.faf` contents |
+| `faf_compress` | Compress `.faf` for token-limited contexts (`minimal` / `standard` / `full`) |
+| `faf_tokens` | Estimate token count at each compression level |
+
+`faf_init` is iterative — run it again and it fills in what's missing. Score goes up each time.
+
+## Architecture
+
+```
+src/
+├── main.rs      # ~20 lines — tokio entry, rmcp stdio transport
+├── server.rs    # FafServer: #[tool_router], ServerHandler, resources
+└── tools.rs     # Business logic — all 9 tools, pure functions returning Value
+```
+
+- **Runtime**: `tokio` single-threaded (`current_thread`)
+- **HTTP**: `reqwest` async (only used by `faf_git` for GitHub API)
+- **SDK**: `faf-rust-sdk` **1.3** (Cargo pin — parse / validate / compress / discover; foundation **3.x** lives in [faf-rust](https://github.com/Wolfe-Jam/faf-rust))
+- **Server**: **`rmcp` 3.0.1** with `#[tool_router]` / `#[tool_handler]` — JSON-RPC, schema generation, stdio transport (Tier-1 assessed SDK cut)
+
+Tools return `serde_json::Value`. The server adapts them to `Result<String, String>` for rmcp's `IntoCallToolResult`.
+
+## Testing
+
+112 tests across 6 files:
+
+```bash
+cargo test    # runs all 112
+
+# Full ship bar (same gates as GitHub CI — run before push)
+bash scripts/ci.sh
+# Optional: block push on red CI twin
+bash scripts/install-hooks.sh
+```
+
+| File | Tests | Coverage |
+|------|-------|----------|
+| `mcp_protocol.rs` | 9 | Init handshake, tools/list, resources, schema validation, ID preservation |
+| `tools_functional.rs` | 25 | All 9 tools — happy path, error paths, language detection |
+| `tier1_security.rs` | 12 | Path traversal, null bytes, shell injection, oversized input, malformed JSON |
+| `tier2_engine.rs` | 35 | Corrupt YAML, sync replacement, pipelines, dual manifests, legacy filenames, direct paths |
+| `tier3_edge_cases.rs` | 10 | Unicode, CJK, score boundaries, unknown fields, GitHub URL parsing |
+| `tier4_aero.rs` | 21 | Manifest structure, version sync, server.json, manifest-server cross-validation |
+
+Tests spawn the compiled binary as a subprocess and communicate via stdin/stdout JSON-RPC — true integration tests against the real server.
+
+## FAF Ecosystem
+
+One format, every AI platform.
+
+| Package | Platform | Registry |
+|---------|----------|----------|
+| **rust-faf-mcp** | **Rust** | **crates.io** |
+| [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 |
+| [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/) | Google | PyPI |
+| [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
+| [faf-cli](https://npmjs.com/package/faf-cli) | Universal | npm |
+
+## Build from source
+
+```bash
+git clone https://github.com/Wolfe-Jam/rust-faf-mcp
+cd rust-faf-mcp
+cargo build --release
+# Binary at target/release/rust-faf-mcp (4.3 MB)
+```
+
+**Edition**: 2024 | **LTO**: enabled | **Strip**: symbols
+
+If `rust-faf-mcp` has been useful, consider starring the repo — it helps others find it.
+
+## Links
+
+- [crates.io/crates/rust-faf-mcp](https://crates.io/crates/rust-faf-mcp)
+- [npmjs.com/package/rust-faf-mcp](https://www.npmjs.com/package/rust-faf-mcp) — `npx rust-faf-mcp` (no Rust toolchain; downloads GH Release binary)
+- [faf-rust-sdk](https://crates.io/crates/faf-rust-sdk) — the parser this depends on
+- [faf.one](https://faf.one) — FAF home
+- [IANA registration](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) — `application/vnd.faf+yaml`
+- MCP Registry name: `mcp-name: one.faf/rust-faf-mcp`
+- [CHANGELOG](CHANGELOG.md)
+
+## License
+
+MIT
+
+---
+
+Built by [@wolfe_jam](https://x.com/wolfe_jam) | [wolfejam.dev](https://wolfejam.dev)

package/lib/download.js

@@ -0,0 +1,202 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const https = require("https");
+const http = require("http");
+const { execFileSync } = require("child_process");
+const { resolveTarget } = require("./platform");
+
+const OWNER = "Wolfe-Jam";
+const REPO = "rust-faf-mcp";
+const APP = "rust-faf-mcp";
+
+/**
+ * Cache dir for downloaded binaries.
+ * @param {string} version
+ * @param {string} triple
+ */
+function cacheDir(version, triple) {
+  const base =
+    process.env.RUST_FAF_MCP_CACHE_DIR ||
+    path.join(os.homedir(), ".cache", "rust-faf-mcp");
+  return path.join(base, version, triple);
+}
+
+/**
+ * @param {string} url
+ * @param {string} dest
+ * @param {number} redirects
+ */
+function downloadFile(url, dest, redirects = 0) {
+  if (redirects > 10) {
+    throw new Error(`rust-faf-mcp: too many redirects fetching ${url}`);
+  }
+  return new Promise((resolve, reject) => {
+    const lib = url.startsWith("https:") ? https : http;
+    const req = lib.get(
+      url,
+      {
+        headers: {
+          "User-Agent": "rust-faf-mcp-npm-shim",
+          Accept: "application/octet-stream",
+        },
+      },
+      (res) => {
+        if (
+          res.statusCode &&
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume();
+          downloadFile(res.headers.location, dest, redirects + 1)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          reject(
+            new Error(
+              `rust-faf-mcp: download failed HTTP ${res.statusCode} for ${url}`
+            )
+          );
+          return;
+        }
+        const tmp = `${dest}.partial`;
+        const out = fs.createWriteStream(tmp);
+        res.pipe(out);
+        out.on("finish", () => {
+          out.close(() => {
+            fs.renameSync(tmp, dest);
+            resolve();
+          });
+        });
+        out.on("error", (err) => {
+          try {
+            fs.unlinkSync(tmp);
+          } catch {
+            /* ignore */
+          }
+          reject(err);
+        });
+      }
+    );
+    req.on("error", reject);
+  });
+}
+
+/**
+ * @param {string} archivePath
+ * @param {string} destDir
+ */
+function extractArchive(archivePath, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  execFileSync("tar", ["-xzf", archivePath, "-C", destDir], {
+    stdio: "inherit",
+  });
+}
+
+/**
+ * @param {string} root
+ * @param {string} binaryName
+ */
+function findBinary(root, binaryName) {
+  const direct = path.join(root, binaryName);
+  if (fs.existsSync(direct) && fs.statSync(direct).isFile()) {
+    return direct;
+  }
+  /** @type {string[]} */
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        stack.push(full);
+      } else if (ent.name === binaryName) {
+        return full;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Ensure native binary is on disk; return absolute path.
+ *
+ * GH asset naming from release.yml:
+ *   rust-faf-mcp-${VERSION}-${target}.tar.gz
+ * e.g. rust-faf-mcp-0.4.1-aarch64-apple-darwin.tar.gz
+ *
+ * @param {string} version
+ */
+async function ensureBinary(version) {
+  const { triple, binaryName } = resolveTarget();
+  const dir = cacheDir(version, triple);
+  const binPath = path.join(dir, binaryName);
+
+  if (fs.existsSync(binPath)) {
+    return binPath;
+  }
+
+  // Primary: versioned name from release.yml
+  // Fallbacks: unversioned / mcp-better-style layouts if ever added
+  const candidates = [
+    `${APP}-${version}-${triple}.tar.gz`,
+    `${APP}-v${version}-${triple}.tar.gz`,
+    `${APP}-${triple}.tar.gz`,
+  ];
+
+  fs.mkdirSync(dir, { recursive: true });
+  const extractRoot = path.join(dir, "_extract");
+  fs.rmSync(extractRoot, { recursive: true, force: true });
+  fs.mkdirSync(extractRoot, { recursive: true });
+
+  let lastErr = null;
+  for (const name of candidates) {
+    const url = `https://github.com/${OWNER}/${REPO}/releases/download/v${version}/${name}`;
+    const archivePath = path.join(dir, name);
+    try {
+      process.stderr.write(`rust-faf-mcp: downloading ${name}…\n`);
+      await downloadFile(url, archivePath);
+      extractArchive(archivePath, extractRoot);
+      const found = findBinary(extractRoot, binaryName);
+      if (!found) {
+        throw new Error(`archive ${name} did not contain ${binaryName}`);
+      }
+      fs.copyFileSync(found, binPath);
+      fs.chmodSync(binPath, 0o755);
+      try {
+        fs.unlinkSync(archivePath);
+      } catch {
+        /* ignore */
+      }
+      fs.rmSync(extractRoot, { recursive: true, force: true });
+      return binPath;
+    } catch (err) {
+      lastErr = err;
+      try {
+        fs.unlinkSync(archivePath);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  throw new Error(
+    `rust-faf-mcp: could not download a binary for ${triple} (v${version}). ` +
+      `Install Rust and run: cargo install rust-faf-mcp --version ${version}\n` +
+      `Last error: ${lastErr && lastErr.message ? lastErr.message : lastErr}`
+  );
+}
+
+module.exports = { ensureBinary, cacheDir };

package/lib/platform.js

@@ -0,0 +1,35 @@
+"use strict";
+
+/**
+ * Map Node process.platform/arch → Rust target triples used by
+ * rust-faf-mcp GitHub Release assets (release.yml).
+ *
+ * Supported matrix today (release.yml): darwin arm/x64 + linux x64 only.
+ */
+
+const TARGETS = {
+  "darwin-arm64": "aarch64-apple-darwin",
+  "darwin-x64": "x86_64-apple-darwin",
+  "linux-x64": "x86_64-unknown-linux-gnu",
+};
+
+/**
+ * @returns {{ triple: string, binaryName: string }}
+ */
+function resolveTarget() {
+  const key = `${process.platform}-${process.arch}`;
+  const triple = TARGETS[key];
+  if (!triple) {
+    const supported = Object.keys(TARGETS).join(", ");
+    throw new Error(
+      `rust-faf-mcp: unsupported platform ${key}. Supported npx hosts: ${supported}. ` +
+        `Use: cargo install rust-faf-mcp — or install an MCPB package.`
+    );
+  }
+  return {
+    triple,
+    binaryName: "rust-faf-mcp",
+  };
+}
+
+module.exports = { resolveTarget, TARGETS };

package/npm/rust-faf-mcp.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * npm shim for rust-faf-mcp — zero Rust toolchain required.
+ *
+ * Identity: one.faf/rust-faf-mcp (FAF product — not io.github).
+ * Downloads versioned GitHub Release assets from release.yml naming:
+ *   rust-faf-mcp-${VERSION}-${target}.tar.gz
+ */
+
+const { spawn } = require("child_process");
+const { ensureBinary } = require("../lib/download");
+
+const pkg = require("../package.json");
+const version = pkg.version;
+
+async function main() {
+  const override = process.env.RUST_FAF_MCP_BIN;
+  let bin;
+  if (override) {
+    bin = override;
+  } else {
+    bin = await ensureBinary(version);
+  }
+
+  const child = spawn(bin, process.argv.slice(2), {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  child.on("error", (err) => {
+    console.error(`rust-faf-mcp: failed to spawn ${bin}: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code == null ? 1 : code);
+  });
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "rust-faf-mcp",
+  "version": "0.4.1",
+  "mcpName": "one.faf/rust-faf-mcp",
+  "description": "Persistent project context — Rust-native MCP server. IANA-registered .faf format. npm shim downloads the native binary from GitHub Releases.",
+  "license": "MIT",
+  "author": "wolfejam <wolfejam@faf.one>",
+  "homepage": "https://faf.one",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wolfe-Jam/rust-faf-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wolfe-Jam/rust-faf-mcp/issues"
+  },
+  "keywords": [
+    "faf",
+    "mcp",
+    "model-context-protocol",
+    "rust",
+    "rmcp"
+  ],
+  "bin": {
+    "rust-faf-mcp": "npm/rust-faf-mcp.js"
+  },
+  "files": [
+    "npm/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}