faf-mcp 3.0.2 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +24 -1
  2. package/CLAUDE.md +2 -2
  3. package/README.md +17 -2
  4. package/dist/src/index.js +36 -0
  5. package/dist/src/index.js.map +1 -1
  6. package/package.json +8 -8
  7. package/project.faf +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <!-- faf: faf-mcp | TypeScript | mcp | The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for Cursor, VS Code, and every MCP-compatible IDE. IANA-registered application/vnd.faf+yaml. Start with "Use FAF". -->
2
- <!-- faf: doc=changelog | latest=v3.0.2 | canonical=project.faf | family=FAF -->
2
+ <!-- faf: doc=changelog | latest=v4.0.1 | canonical=project.faf | family=FAF -->
3
3
 
4
4
  # Changelog
5
5
 
@@ -8,6 +8,29 @@ All notable changes to faf-mcp will be documented in this file.
8
8
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
9
9
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
10
10
 
11
+ ## [4.0.1] - 2026-10-16
12
+
13
+ **`faf-mcp --version` and `--help` answer and exit. Before, both started the server.** 407 tests pass, 0 fail.
14
+
15
+ ### Fixed
16
+ - `--version` / `-v` / `-V` prints `faf-mcp 4.0.1` and exits 0; `--help` / `-h` prints usage and a client config and exits 0. Both used to start the server on stdio and print nothing. Any other argument still starts the server, so client configs don't change. New `tests/cli-flags.test.ts` runs each flag with stdin closed and a time limit. Closes #94.
17
+
18
+ ## [4.0.0] - 2026-09-26 — The Always33 Edition
19
+
20
+ **One engine, one number: faf-mcp 4 scores with faf-cli 8's always-33 kernel — the same score faf-cli, claude-faf-mcp 7 and faf-kernel give.** 402 tests.
21
+
22
+ **4.0.0 is a major release because scores can move.** A `.faf` without the 12 enterprise `slotignored` markers now counts them as empty (21 filled = 64%). Run `faf_auto` — it writes the markers and the score returns (a v3-era mcp-context-card file: 56% → 100%). Anything that gates on `faf_score` should re-check its threshold.
23
+
24
+ ### Changed
25
+ - **The always-33 engine.** faf-mcp composes **faf-cli ^8.0.0** (was ^7.12.0, which could never resolve 8.x). Every tool's score is faf-cli 8's: all 33 Mk4 slots, one Rust kernel (`faf-scoring-kernel` 3.0.0). Verified live: `faf_score` on faf-python-sdk 56, mcp-context-card 56, faf-cli ✪ 100 — identical to faf-cli 8.0.0 and claude-faf-mcp 7.0.0 (which ships first).
26
+ - **One kernel copy.** The direct `faf-scoring-kernel ^2.0.3` dependency is gone (nothing imported it); the only kernel in an install is faf-cli's own.
27
+ - **The 12 enterprise slots stay in view** — marked `slotignored` unless your app-type uses them. `faf_score` scores against all 33; `slotignored` slots drop out of the denominator.
28
+ - **faf-cli's owner rule for the blocks it writes** (faf-cli 7.13+, which npm installs of 3.0.2 already had): a block faf can prove is its own is replaced in place; an ambiguous one — a marker with trailing whitespace, a marker behind an unclosed or misread fence, a metastamp-only file — is left whole below a fresh block. Nothing is ever partly wiped.
29
+ - `tbd` and `todo` (any case) count as empty.
30
+
31
+ ### Tests
32
+ - The doctor fixtures carry the 12 enterprise markers; the injector tests assert the owner rule against faf-cli 8's actual output.
33
+
11
34
  ## [3.0.2] - 2026-09-10 — The Compose Edition
12
35
 
13
36
  **Tools that say what they do: `faf_git` scores with faf-cli and asks before overwriting, `faf_sync` previews each change, and imports say when nothing was written.**
package/CLAUDE.md CHANGED
@@ -25,12 +25,12 @@ The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for
25
25
  - **What:** The Cursor / IDE Edition — persistent context for Cursor, VS Code, and every MCP-compatible IDE — 29 MCP tools (15 essential shown by default), interop with AGENTS.md, .cursorrules, GEMINI.md
26
26
  - **Why:** Eliminate the 20-minute AI context tax — give AI instant project understanding in 30 seconds
27
27
  - **Where:** npm · MCP Registry · any MCP-compatible IDE — people get it how they wish
28
- - **When:** Production/Stable — v3.0.2 The Compose Edition, WJTTC certified
28
+ - **When:** Production/Stable — v4.0.1 The Always33 Edition, WJTTC certified
29
29
  - **How:** npx faf-mcp or npm install -g faf-mcp, then add to your MCP config
30
30
 
31
31
  ---
32
32
 
33
- *STATUS: BI-SYNC ACTIVE — 2026-09-10T20:10:15.531Z*
33
+ *STATUS: SYNC ACTIVE — 2026-10-16T16:57:57.556Z*
34
34
  <!-- faf:end -->
35
35
 
36
36
  ## Working here
package/README.md CHANGED
@@ -24,10 +24,25 @@
24
24
  [![CI](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml)
25
25
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
26
26
  [![project.faf](https://img.shields.io/badge/project.faf-inside-008B8B)](https://github.com/Wolfe-Jam/faf)
27
+ [![Business card · Get yours →](https://wolfe-jam.github.io/agent-business-card/badge.svg)](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/faf-mcp)
27
28
 
28
29
  ---
29
30
 
30
- ## What's New in 3.0.2 — The Compose Edition
31
+ ## What's New in 4.0.1
32
+
33
+ **`faf-mcp --version` and `--help` answer and exit. Before, both started the server.**
34
+
35
+ - `--version` (`-v`) prints the version; `--help` (`-h`) prints usage and a client config. Anything else starts the server as before, so your client config doesn't change.
36
+
37
+ ## 4.0.0 — The Always33 Edition
38
+
39
+ **One engine, one number: faf-mcp 4 scores with faf-cli 8's always-33 kernel — the same score faf-cli, claude-faf-mcp 7 and faf-kernel give.**
40
+
41
+ - **The always-33 engine.** Every tool scores with faf-cli 8.0.0 — all 33 Mk4 slots, one Rust kernel, one copy of it. Checked live: faf-python-sdk 56, mcp-context-card 56, faf-cli ✪ 100.
42
+ - **Your 21 slots, and the 12 enterprise slots in view.** The enterprise slots (infra, app, ops) are marked `slotignored` unless your app-type uses them. `faf_score` scores against all 33; `slotignored` slots drop out of the denominator.
43
+ - **Upgrading from 3.x:** a `.faf` without the 12 markers now scores against 33. **Run `faf_auto`** — it writes them and your score returns.
44
+
45
+ ## 3.0.2 — The Compose Edition
31
46
 
32
47
  **Tools that say what they do: `faf_git` scores with faf-cli and asks before overwriting, `faf_sync` previews each change, and imports say when nothing was written.**
33
48
 
@@ -125,7 +140,7 @@ faf_claude { all: true }
125
140
  faf_git { url: "https://github.com/facebook/react" }
126
141
  ```
127
142
 
128
- **Core tier:** 15 essential tools shown by default; set `FAF_TOOLS=all` for the full **29** (every tool stays callable by name either way) · **25 test suites** · **7 bundled parsers**
143
+ **Core tier:** 15 essential tools shown by default; set `FAF_TOOLS=all` for the full **29** (every tool stays callable by name either way) · **26 test suites** · **7 bundled parsers**
129
144
 
130
145
  ---
131
146
 
package/dist/src/index.js CHANGED
@@ -2,8 +2,44 @@
2
2
  "use strict";
3
3
  Object.defineProperty(exports, "__esModule", { value: true });
4
4
  const server_js_1 = require("./server.js");
5
+ const version_js_1 = require("./version.js");
6
+ const HELP = `faf-mcp — MCP server for FAF (project.faf, IANA application/vnd.faf+yaml)
7
+
8
+ Usage:
9
+ faf-mcp Serve MCP over stdio (what MCP clients run)
10
+ faf-mcp --version Print the version (-v, -V)
11
+ faf-mcp --help Print this help (-h)
12
+
13
+ Run on its own, it waits silently for an MCP client. That's correct; Ctrl+C to quit.
14
+
15
+ Add it to a client:
16
+ claude mcp add faf -- npx -y faf-mcp
17
+ { "mcpServers": { "faf": { "command": "npx", "args": ["-y", "faf-mcp"] } } }
18
+
19
+ https://github.com/Wolfe-Jam/faf-mcp`;
20
+ /**
21
+ * `--version` / `--help` answer and exit before the server starts, so stdout
22
+ * carries only the answer (#94). Any other argument starts the server as
23
+ * before, so existing client configs don't change.
24
+ */
25
+ function handleFlags(argv) {
26
+ const arg = argv[2];
27
+ if (arg === '--version' || arg === '-v' || arg === '-V') {
28
+ console.log(`faf-mcp ${(0, version_js_1.getVersion)()}`);
29
+ return 0;
30
+ }
31
+ if (arg === '--help' || arg === '-h') {
32
+ console.log(HELP);
33
+ return 0;
34
+ }
35
+ return null;
36
+ }
5
37
  // MCP servers run via stdio transport when launched by your MCP host
6
38
  async function main() {
39
+ const code = handleFlags(process.argv);
40
+ if (code !== null) {
41
+ process.exit(code);
42
+ }
7
43
  const server = new server_js_1.FafMcpServer({
8
44
  transport: 'stdio',
9
45
  fafEnginePath: 'faf'
package/dist/src/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAEA,2CAA2C;AAE3C,qEAAqE;AACrE,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,wBAAY,CAAC;QAC9B,SAAS,EAAE,OAAO;QAClB,aAAa,EAAE,KAAK;KACrB,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAEA,2CAA2C;AAC3C,6CAA0C;AAE1C,MAAM,IAAI,GAAG;;;;;;;;;;;;;qCAawB,CAAC;AAEtC;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAc;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACxD,OAAO,CAAC,GAAG,CAAC,WAAW,IAAA,uBAAU,GAAE,EAAE,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qEAAqE;AACrE,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,wBAAY,CAAC;QAC9B,SAAS,EAAE,OAAO;QAClB,aAAa,EAAE,KAAK;KACrB,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "faf-mcp",
3
- "version": "3.0.2",
3
+ "version": "4.0.1",
4
4
  "mcpName": "one.faf/faf-mcp",
5
5
  "description": ".FAF Context — persistent project context for Cursor, VS Code and every MCP-compatible IDE. IANA-registered .faf format. Curated core tools by default, full set via FAF_TOOLS=all.",
6
6
  "icon": "./assets/icons/faf-icon-256.png",
@@ -98,9 +98,9 @@
98
98
  },
99
99
  "dependencies": {
100
100
  "@modelcontextprotocol/sdk": "^1.30.0",
101
- "faf-cli": "^7.12.0",
102
- "faf-scoring-kernel": "^2.0.3",
103
- "yaml": "^2.4.1"
101
+ "faf-cli": "^8.0.0",
102
+ "yaml": "^2.4.1",
103
+ "zod": "^4.0"
104
104
  },
105
105
  "devDependencies": {
106
106
  "@types/jsonwebtoken": "^9.0.5",
@@ -113,9 +113,9 @@
113
113
  },
114
114
  "overrides": {
115
115
  "hono": ">=4.13.5",
116
- "fast-uri": ">=4.1.2",
117
- "ip-address": ">=10.3.1",
118
- "brace-expansion@1": "1.1.18",
119
- "brace-expansion@2": "2.1.4"
116
+ "fast-uri": ">=4.1.5",
117
+ "ip-address": ">=10.7.1",
118
+ "brace-expansion@1": "1.1.21",
119
+ "brace-expansion@2": "2.1.7"
120
120
  }
121
121
  }
package/project.faf CHANGED
@@ -2,7 +2,7 @@ faf_version: "3.0"
2
2
  project:
3
3
  name: faf-mcp
4
4
  title: .FAF Context
5
- version: 3.0.2
5
+ version: 4.0.1
6
6
  goal: The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for Cursor, VS Code, and every MCP-compatible IDE. IANA-registered application/vnd.faf+yaml. Start with "Use FAF".
7
7
  main_language: TypeScript
8
8
  type: mcp
@@ -33,7 +33,7 @@ human_context:
33
33
  what: The Cursor / IDE Edition — persistent context for Cursor, VS Code, and every MCP-compatible IDE — 29 MCP tools (15 essential shown by default), interop with AGENTS.md, .cursorrules, GEMINI.md
34
34
  why: Eliminate the 20-minute AI context tax — give AI instant project understanding in 30 seconds
35
35
  where: npm · MCP Registry · any MCP-compatible IDE — people get it how they wish
36
- when: Production/Stable — v3.0.2 The Compose Edition, WJTTC certified
36
+ when: Production/Stable — v4.0.1 The Always33 Edition, WJTTC certified
37
37
  how: npx faf-mcp or npm install -g faf-mcp, then add to your MCP config
38
38
  monorepo:
39
39
  packages_count: slotignored