@mfdaves/okf-mcp 0.9.1 → 0.13.0-rc.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 (115) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +452 -26
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  5. package/okf/okf-mcp/index.md +2 -1
  6. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  7. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  8. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  9. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  10. package/okf/okf-mcp/policies/authoring-safety.md +28 -5
  11. package/okf/okf-mcp/runtime/indexer.md +14 -1
  12. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  13. package/okf/okf-mcp/specs/producer-api.md +16 -2
  14. package/package.json +17 -5
  15. package/server.json +38 -2
  16. package/src/assets.js +165 -73
  17. package/src/authoring/candidates.js +434 -0
  18. package/src/authoring/git-preflight.js +225 -0
  19. package/src/authoring/git-publish.js +783 -0
  20. package/src/authoring/live.js +757 -0
  21. package/src/authoring/paths.js +112 -0
  22. package/src/authoring/policy-hook.js +221 -0
  23. package/src/authoring/proposal-policy.js +159 -0
  24. package/src/authoring/receipts.js +373 -0
  25. package/src/authoring/render.js +38 -0
  26. package/src/authoring/shared.js +75 -0
  27. package/src/authoring/staging.js +216 -0
  28. package/src/authoring.js +386 -287
  29. package/src/cache/files.js +147 -0
  30. package/src/cache/lock.js +201 -0
  31. package/src/cache/paths.js +197 -0
  32. package/src/cache/store.js +703 -0
  33. package/src/catalog-text.js +19 -0
  34. package/src/cli/commands.js +448 -0
  35. package/src/cli/http-options.js +193 -0
  36. package/src/cli/options.js +554 -0
  37. package/src/cli/usage.js +96 -0
  38. package/src/cli.js +18 -932
  39. package/src/computation.js +99 -61
  40. package/src/context/assemble.js +567 -0
  41. package/src/context/cli-options.js +88 -0
  42. package/src/context/score.js +234 -0
  43. package/src/context/sections.js +274 -0
  44. package/src/embed/interface.js +160 -0
  45. package/src/embed/openai.js +715 -0
  46. package/src/embed/prepare.js +182 -0
  47. package/src/embed/units.js +96 -0
  48. package/src/error-details.js +53 -0
  49. package/src/git-source.js +112 -52
  50. package/src/graph.js +95 -37
  51. package/src/http-server.js +36 -17
  52. package/src/index.js +15 -0
  53. package/src/indexer/assemble.js +566 -0
  54. package/src/indexer/build.js +290 -0
  55. package/src/indexer/cache.js +81 -0
  56. package/src/indexer/edges.js +430 -0
  57. package/src/indexer/index.js +44 -0
  58. package/src/indexer/paths.js +178 -0
  59. package/src/indexer/resolve.js +282 -0
  60. package/src/indexer/update.js +720 -0
  61. package/src/indexer.js +3 -1068
  62. package/src/live-authoring.js +4 -2329
  63. package/src/markdown.js +21 -16
  64. package/src/mcp/auth.js +409 -0
  65. package/src/mcp/http.js +317 -0
  66. package/src/mcp/principal.js +59 -0
  67. package/src/mcp/registry.js +356 -0
  68. package/src/mcp/resources.js +45 -0
  69. package/src/mcp/server.js +567 -0
  70. package/src/mcp/tools/catalog.js +247 -0
  71. package/src/mcp/tools/computation.js +83 -0
  72. package/src/mcp/tools/context.js +133 -0
  73. package/src/mcp/tools/graph.js +167 -0
  74. package/src/mcp/tools/live-authoring.js +316 -0
  75. package/src/mcp/tools/migration.js +86 -0
  76. package/src/mcp/tools/producers.js +79 -0
  77. package/src/mcp/tools/proposals.js +225 -0
  78. package/src/mcp/tools/provenance.js +87 -0
  79. package/src/mcp/tools/remote.js +79 -0
  80. package/src/mcp/tools/search.js +242 -0
  81. package/src/mcp-server.js +3 -1611
  82. package/src/migration.js +431 -253
  83. package/src/parser.js +245 -130
  84. package/src/plugins.js +71 -48
  85. package/src/policy/write-policy.js +713 -0
  86. package/src/producer-publisher.js +202 -78
  87. package/src/producers.js +311 -103
  88. package/src/project.js +346 -93
  89. package/src/remote.js +96 -61
  90. package/src/search/cli-options.js +107 -0
  91. package/src/search/confidence.js +61 -0
  92. package/src/search/dense.js +304 -0
  93. package/src/search/embedding-cli.js +57 -0
  94. package/src/search/embedding-config.js +217 -0
  95. package/src/search/fusion.js +249 -0
  96. package/src/search/hybrid.js +526 -0
  97. package/src/search/languages.js +200 -0
  98. package/src/search/lexical.js +695 -0
  99. package/src/search/query.js +620 -0
  100. package/src/search/stem/among.js +43 -0
  101. package/src/search/stem/base-stemmer.js +311 -0
  102. package/src/search/stem/en-regions.js +456 -0
  103. package/src/search/stem/en-suffixes.js +664 -0
  104. package/src/search/stem/en-tables.js +176 -0
  105. package/src/search/stem/en.js +238 -0
  106. package/src/search/stem/it-regions.js +459 -0
  107. package/src/search/stem/it-suffixes.js +471 -0
  108. package/src/search/stem/it-tables.js +257 -0
  109. package/src/search/stem/it.js +155 -0
  110. package/src/search-index.js +2 -81
  111. package/src/search.js +2 -252
  112. package/src/store.js +134 -81
  113. package/src/tool-packs.js +346 -0
  114. package/src/v02.js +301 -105
  115. package/src/validation.js +24 -20
@@ -0,0 +1,317 @@
1
+ "use strict";
2
+
3
+ // MCP over Streamable HTTP (plan I-2): a node:http server with a small bridge
4
+ // to the web Request/Response that the SDK's createMcpHandler serves, instead
5
+ // of an @modelcontextprotocol/node dependency. The SDK entry validates
6
+ // nothing, so this module checks Host on every request and Origin on the MCP
7
+ // endpoint, caps request bodies at the stdio message limit, and resolves the
8
+ // principal each request runs for (anonymous read-only unless an
9
+ // authenticator is configured). Every request builds its McpServer over the
10
+ // one shared state, so the calls of all clients share the state's call queue.
11
+ // `legacy: "stateless"` serves 2025-era clients next to 2026-07-28 ones.
12
+
13
+ const http = require("node:http");
14
+ const {
15
+ createMcpHandler,
16
+ hostHeaderValidationResponse,
17
+ localhostAllowedHostnames,
18
+ localhostAllowedOrigins,
19
+ originValidationResponse,
20
+ } = require("@modelcontextprotocol/server");
21
+
22
+ const { advertisedScopes } = require("../tool-packs");
23
+ const { createHttpAuth } = require("./auth");
24
+ const { anonymousPrincipal } = require("./principal");
25
+ const { MAX_MCP_MESSAGE_BYTES, createStateAsync, registerMcpInterface } = require("./server");
26
+
27
+ const DEFAULT_MCP_PATH = "/mcp";
28
+ const DEFAULT_REFRESH_INTERVAL_MS = 2000;
29
+
30
+ // CORS for the origins --allowed-origin (and the localhost names) accept:
31
+ // the exact origin is echoed, never "*".
32
+ const CORS_ALLOW_METHODS = "GET, POST, DELETE, OPTIONS";
33
+ const CORS_ALLOW_HEADERS =
34
+ "Authorization, Content-Type, Mcp-Session-Id, MCP-Protocol-Version, Last-Event-ID";
35
+ const CORS_EXPOSE_HEADERS = "WWW-Authenticate, Mcp-Session-Id";
36
+
37
+ function corsHeaders(origin) {
38
+ return {
39
+ "access-control-allow-origin": origin,
40
+ vary: "Origin",
41
+ "access-control-expose-headers": CORS_EXPOSE_HEADERS,
42
+ };
43
+ }
44
+
45
+ function jsonRpcError(status, code, message) {
46
+ return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status });
47
+ }
48
+
49
+ // The request body, or null when it is larger than `limit` bytes; reading
50
+ // stops there and the caller answers 413 and closes the connection.
51
+ function readBody(req, limit) {
52
+ return new Promise((resolve, reject) => {
53
+ if (Number(req.headers["content-length"]) > limit) {
54
+ resolve(null);
55
+ return;
56
+ }
57
+ const chunks = [];
58
+ let total = 0;
59
+ let settled = false;
60
+ const settle = (value) => {
61
+ if (settled) return;
62
+ settled = true;
63
+ resolve(value);
64
+ };
65
+ req.on("data", (chunk) => {
66
+ if (settled) return;
67
+ total += chunk.length;
68
+ if (total > limit) {
69
+ req.pause();
70
+ settle(null);
71
+ return;
72
+ }
73
+ chunks.push(chunk);
74
+ });
75
+ req.on("end", () => settle(Buffer.concat(chunks)));
76
+ req.on("error", (error) => {
77
+ if (!settled) {
78
+ settled = true;
79
+ reject(error);
80
+ }
81
+ });
82
+ });
83
+ }
84
+
85
+ // node:http request → web Request. The URL is built on a fixed base from the
86
+ // request path only; the Host header travels as a header and is checked.
87
+ function toWebRequest(req, body, signal) {
88
+ const headers = new Headers();
89
+ for (let index = 0; index + 1 < req.rawHeaders.length; index += 2) {
90
+ headers.append(req.rawHeaders[index], req.rawHeaders[index + 1]);
91
+ }
92
+ const url = new URL("http://localhost/");
93
+ const target = String(req.url || "/");
94
+ const query = target.indexOf("?");
95
+ url.pathname = query < 0 ? target : target.slice(0, query);
96
+ url.search = query < 0 ? "" : target.slice(query);
97
+ return new Request(url, {
98
+ method: req.method,
99
+ headers,
100
+ signal,
101
+ ...(body?.length ? { body, duplex: "half" } : {}),
102
+ });
103
+ }
104
+
105
+ // web Response → node:http response, streaming the body (SSE included) with
106
+ // backpressure; a client that goes away cancels the stream.
107
+ async function sendWebResponse(res, response, extraHeaders) {
108
+ const headers = {};
109
+ response.headers.forEach((value, key) => {
110
+ headers[key] = value;
111
+ });
112
+ for (const [key, value] of Object.entries(extraHeaders || {})) {
113
+ headers[key] = key === "vary" && headers.vary ? `${headers.vary}, ${value}` : value;
114
+ }
115
+ res.writeHead(response.status, headers);
116
+ if (!response.body || res.req.method === "HEAD") {
117
+ res.end();
118
+ return;
119
+ }
120
+ const reader = response.body.getReader();
121
+ res.once("close", () => {
122
+ reader.cancel().catch(() => {});
123
+ });
124
+ try {
125
+ for (;;) {
126
+ const { done, value } = await reader.read();
127
+ if (done || res.destroyed) break;
128
+ if (!res.write(value)) {
129
+ await new Promise((resolve) => {
130
+ res.once("drain", resolve);
131
+ res.once("close", resolve);
132
+ });
133
+ }
134
+ }
135
+ } catch {
136
+ // The client went away or the stream failed; nothing more to send.
137
+ } finally {
138
+ res.end();
139
+ }
140
+ }
141
+
142
+ // Plan I-2c: the refresher the server state runs before a call or resource
143
+ // read that uses the index (never for initialize, ping or tools/list),
144
+ // inside the call queue and in the same job as that read: when at least
145
+ // `intervalMs` has passed since the last check, the shared index is
146
+ // refreshed from disk. A failed refresh leaves the index as it was.
147
+ function indexRefresher(state, intervalMs) {
148
+ let checkedAt = Date.now();
149
+ return () => {
150
+ const now = Date.now();
151
+ if (now - checkedAt < intervalMs) return;
152
+ checkedAt = now;
153
+ try {
154
+ state.refreshIndex();
155
+ } catch {
156
+ // Served from the index it had.
157
+ }
158
+ };
159
+ }
160
+
161
+ // The request handler for one shared state. `options`: mcpPath, allowedHosts
162
+ // and allowedOrigins (hostnames, added to the localhost names),
163
+ // `authenticate(request)` resolving to a principal or to a challenge
164
+ // Response, `routes(request)` for extra documents (a Response or undefined),
165
+ // and `refreshIntervalMs` (default 2,000; see indexRefresher).
166
+ function createMcpHttpHandler(state, options) {
167
+ const config = options || {};
168
+ // From now on many principals share this state (see GATES.runtimeRemote).
169
+ state.transport = "http";
170
+ state.refreshBeforeRead = indexRefresher(
171
+ state,
172
+ config.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS,
173
+ );
174
+ const mcpPath = config.mcpPath || DEFAULT_MCP_PATH;
175
+ // The endpoint answers with and without one trailing slash, so a
176
+ // --public-url written either way reaches it.
177
+ const mcpPaths = new Set([mcpPath, mcpPath === "/" ? "/" : `${mcpPath}/`]);
178
+ // GET /health, and beside the endpoint as well (/okf/mcp → /okf/health),
179
+ // where a client deriving it from the MCP URL looks for it.
180
+ const healthPaths = new Set(["/health", `${mcpPath.replace(/\/[^/]*$/, "")}/health`]);
181
+ const allowedHosts = localhostAllowedHostnames().concat(config.allowedHosts || []);
182
+ const allowedOrigins = localhostAllowedOrigins().concat(config.allowedOrigins || []);
183
+ const mcp = createMcpHandler(
184
+ (context) =>
185
+ registerMcpInterface(state, context.authInfo?.extra?.principal || anonymousPrincipal(), {
186
+ subjectToken: context.authInfo?.extra?.subjectToken,
187
+ }),
188
+ { legacy: "stateless" },
189
+ );
190
+
191
+ // The response for one request, with the headers to add to it:
192
+ // { response, headers?, close? }.
193
+ async function route(req, signal) {
194
+ const probe = toWebRequest(req, null, signal);
195
+ const rejected = hostHeaderValidationResponse(probe, allowedHosts);
196
+ if (rejected) return { response: rejected };
197
+ const pathname = new URL(probe.url).pathname;
198
+ if (healthPaths.has(pathname) && (req.method === "GET" || req.method === "HEAD")) {
199
+ return { response: Response.json({ status: "ok" }) };
200
+ }
201
+ const extra = config.routes ? await config.routes(probe) : undefined;
202
+ if (!extra && !mcpPaths.has(pathname)) {
203
+ return { response: Response.json({ error: "not_found" }, { status: 404 }) };
204
+ }
205
+ // The MCP endpoint and the documents beside it (the protected-resource
206
+ // metadata): a foreign origin gets 403 and no CORS headers; an accepted
207
+ // one gets them on every answer, refusals included, and a preflight is
208
+ // answered before authentication.
209
+ const foreign = originValidationResponse(probe, allowedOrigins);
210
+ if (foreign) return { response: foreign };
211
+ const origin = probe.headers.get("origin");
212
+ const headers = origin ? corsHeaders(origin) : undefined;
213
+ if (origin && req.method === "OPTIONS") {
214
+ const preflight = new Response(null, {
215
+ status: 204,
216
+ headers: {
217
+ "access-control-allow-methods": extra ? "GET, HEAD, OPTIONS" : CORS_ALLOW_METHODS,
218
+ "access-control-allow-headers": CORS_ALLOW_HEADERS,
219
+ },
220
+ });
221
+ return { response: preflight, headers };
222
+ }
223
+ if (extra) return { response: extra, headers };
224
+ const verified = config.authenticate
225
+ ? await config.authenticate(probe)
226
+ : { principal: anonymousPrincipal() };
227
+ if (verified instanceof Response) return { response: verified, headers };
228
+ const { principal, subjectToken } = verified;
229
+ const body = await readBody(req, MAX_MCP_MESSAGE_BYTES);
230
+ if (body === null) {
231
+ const tooLarge = jsonRpcError(413, -32600, "Request body too large.");
232
+ return { response: tooLarge, headers, close: true };
233
+ }
234
+ // createMcpHandler hands authInfo to the factory as-is: the principal,
235
+ // and the verified token only for tool-pack handlers (ctx.subjectToken).
236
+ const authInfo = {
237
+ token: "",
238
+ clientId: principal.subject,
239
+ scopes: [...principal.scopes],
240
+ extra: { principal, subjectToken },
241
+ };
242
+ return { response: await mcp.fetch(toWebRequest(req, body, signal), { authInfo }), headers };
243
+ }
244
+
245
+ async function handle(req, res) {
246
+ const aborter = new AbortController();
247
+ res.once("close", () => {
248
+ if (!res.writableFinished) aborter.abort();
249
+ });
250
+ let outcome;
251
+ try {
252
+ outcome = await route(req, aborter.signal);
253
+ } catch {
254
+ outcome = { response: jsonRpcError(500, -32603, "Internal server error.") };
255
+ }
256
+ const headers = Object.assign(
257
+ {},
258
+ outcome.headers,
259
+ outcome.close ? { connection: "close" } : {},
260
+ );
261
+ await sendWebResponse(res, outcome.response, headers);
262
+ }
263
+
264
+ return { handle, close: () => mcp.close() };
265
+ }
266
+
267
+ // Starts `okf mcp --http`: builds the server state like the stdio server does,
268
+ // sets up authentication (`http.auth`, see src/mcp/auth.js; `http.env` and
269
+ // `http.fetch` stand in for the process's in tests), listens on host:port and
270
+ // resolves once listening with { url, port, close }.
271
+ async function runMcpHttpServer(bundleArgs, options) {
272
+ const config = options || {};
273
+ const httpOptions = Object.assign({}, config.http);
274
+ // The state first: the tool packs it loads add to the advertised scopes.
275
+ const state = await createStateAsync(bundleArgs, config);
276
+ if (httpOptions.auth) {
277
+ const auth = createHttpAuth(httpOptions.auth, {
278
+ publicUrl: httpOptions.publicUrl,
279
+ env: httpOptions.env,
280
+ fetch: httpOptions.fetch,
281
+ scopes: advertisedScopes(state.toolPacks),
282
+ });
283
+ httpOptions.authenticate = auth.authenticate;
284
+ httpOptions.routes = auth.routes;
285
+ }
286
+ const handler = createMcpHttpHandler(state, httpOptions);
287
+ const server = http.createServer((req, res) => {
288
+ handler.handle(req, res).catch(() => res.destroy());
289
+ });
290
+ const host = httpOptions.host || "127.0.0.1";
291
+ await new Promise((resolve, reject) => {
292
+ server.once("error", reject);
293
+ server.listen(httpOptions.port ?? 0, host, () => {
294
+ server.off("error", reject);
295
+ resolve();
296
+ });
297
+ });
298
+ const { port } = server.address();
299
+ const shown = host.includes(":") ? `[${host}]` : host;
300
+ return {
301
+ state,
302
+ port,
303
+ url: `http://${shown}:${port}${httpOptions.mcpPath || DEFAULT_MCP_PATH}`,
304
+ async close() {
305
+ await handler.close();
306
+ server.closeAllConnections();
307
+ await new Promise((resolve) => server.close(resolve));
308
+ },
309
+ };
310
+ }
311
+
312
+ module.exports = {
313
+ DEFAULT_MCP_PATH,
314
+ DEFAULT_REFRESH_INTERVAL_MS,
315
+ createMcpHttpHandler,
316
+ runMcpHttpServer,
317
+ };
@@ -0,0 +1,59 @@
1
+ "use strict";
2
+
3
+ // The principal an MCP call runs for (plan I-2a):
4
+ // { subject, actor, scopes: Set, name?, email? }
5
+ // `okf.read` is required for any call and `okf.write` for the live write
6
+ // tools and producer runs; other scope strings (such as odoo.read) gate
7
+ // tool-pack tools (src/tool-packs.js). Over stdio the principal comes from the
8
+ // flags (actor = --actor, okf.write only with --write) and also holds the
9
+ // scopes the configured tool packs declare; over HTTP it comes from the
10
+ // authentication mode (src/mcp/auth.js), or is anonymous read-only.
11
+
12
+ const READ_SCOPE = "okf.read";
13
+ const WRITE_SCOPE = "okf.write";
14
+ const KNOWN_SCOPES = Object.freeze([READ_SCOPE, WRITE_SCOPE]);
15
+ const SCOPE_NAME = /^[a-z][a-z0-9_.:-]{0,63}$/;
16
+
17
+ function flagsPrincipal(state) {
18
+ return {
19
+ subject: "stdio",
20
+ actor: state?.actor || null,
21
+ scopes: new Set(
22
+ (state?.allowWrite ? [READ_SCOPE, WRITE_SCOPE] : [READ_SCOPE]).concat(
23
+ state?.toolPackScopes || [],
24
+ ),
25
+ ),
26
+ };
27
+ }
28
+
29
+ function anonymousPrincipal() {
30
+ return { subject: "anonymous", actor: null, scopes: new Set([READ_SCOPE]) };
31
+ }
32
+
33
+ function canWrite(principal) {
34
+ return Boolean(principal?.scopes?.has(WRITE_SCOPE));
35
+ }
36
+
37
+ // What a write made for this principal hands the authoring services: its
38
+ // actor, and as git author its name and email, each when it carries one.
39
+ function principalWriteContext(principal) {
40
+ const author = Object.assign(
41
+ principal?.name ? { name: principal.name } : {},
42
+ principal?.email ? { email: principal.email } : {},
43
+ );
44
+ return {
45
+ ...(principal?.actor ? { actor: principal.actor } : {}),
46
+ ...(Object.keys(author).length ? { author } : {}),
47
+ };
48
+ }
49
+
50
+ module.exports = {
51
+ KNOWN_SCOPES,
52
+ READ_SCOPE,
53
+ SCOPE_NAME,
54
+ WRITE_SCOPE,
55
+ anonymousPrincipal,
56
+ canWrite,
57
+ flagsPrincipal,
58
+ principalWriteContext,
59
+ };