@okfit/mcp 0.3.6 → 0.4.0

package/README.md

@@ -41,7 +41,7 @@ or `.config/okfit.toml`.
 | `get_concept` | One concept by id: its whole decoded frontmatter, the file's raw markdown text, its bundle-relative path, and every outgoing link. |
 | `concept_neighbors` | A concept's graph neighbours — everything it links to and everything that links to it — each with its node kind and, for a concept target, its full summary. |
 | `stale_report` | Every concept whose `stale_after` instant has passed, each with its summary and how many whole days past it, as of now or an explicit instant. |
-| `validate_bundle` | The same conformance and lint report `okfit validate --format json` produces, unchanged. |
+| `validate_bundle` | The same conformance and lint report `okfit validate --format json` produces, unchanged. Its `engine_version` and `okf_version` match the CLI's over one bundle; `okfit_version` is this package's own version and `producer` is `@okfit/mcp`. |
 
 ## Resources
 

package/index.d.ts

@@ -1,6 +1,7 @@
 import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
 import { AppDirs, Xdg } from "@effected/xdg";
 import { LoadedConcept } from "@okfit/core";
+import { Distribution } from "@okfit/engine";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { Toolkit } from "effect/unstable/ai";
 //#region src/errors.d.ts
@@ -379,6 +380,18 @@ export type ValidateBundleParams = typeof ValidateBundleParams.Type;
  * @public
  */
 type PlatformServices = FileSystem.FileSystem | Path.Path | AppDirs | Xdg | Stdio.Stdio | ChildProcessSpawner.ChildProcessSpawner;
+/**
+ * Options `ServerLayer` accepts, beyond `projectRoot`. `distribution`
+ * (okfit #137) names the meta-package that launched this server (currently
+ * only `@okfit/plugin`'s `okfit-mcp` bin shim), threaded down into
+ * `validate_bundle`'s rendered `JsonEnvelope`; `undefined` for a direct
+ * install of `@okfit/mcp`.
+ *
+ * @public
+ */
+interface ServerOptions {
+  readonly distribution?: Distribution;
+}
 /**
  * The whole server as one layer: the toolkit, one static resource per
  * concept (`okf://concept/<id>`, built once at boot — see
@@ -396,7 +409,7 @@ type PlatformServices = FileSystem.FileSystem | Path.Path | AppDirs | Xdg | Stdi
  *
  * @public
  */
-export declare const ServerLayer: (projectRoot: string) => Layer.Layer<never, never, PlatformServices>;
+export declare const ServerLayer: (projectRoot: string, options?: ServerOptions) => Layer.Layer<never, never, PlatformServices>;
 //#endregion
 //#region src/toolkit.d.ts
 /**
@@ -552,7 +565,12 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
     readonly success: import("effect/Schema").Struct<{
       readonly schema: import("effect/Schema").Literal<1>;
       readonly okfit_version: import("effect/Schema").String;
+      readonly engine_version: import("effect/Schema").String;
       readonly producer: import("effect/Schema").String;
+      readonly distribution: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+        readonly name: import("effect/Schema").String;
+        readonly version: import("effect/Schema").String;
+      }>>;
       readonly okf_version: import("effect/Schema").String;
       readonly root: import("effect/Schema").String;
       readonly profile: import("effect/Schema").NullOr<import("effect/Schema").String>;
@@ -581,10 +599,13 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
 /**
  * The handler layer. `projectRoot` is closed over from the bin (N-21);
  * the bundle itself reloads on every call inside each handler (N-9).
+ * `distribution` (okfit #137) is whatever `ServerLayer` was given -- only
+ * `validate_bundle` renders a `JsonEnvelope`, so it is the only handler
+ * that needs it.
  *
  * @public
  */
-export declare const ToolsLayer: (projectRoot: string) => import("effect/Layer").Layer<import("effect/unstable/ai/Tool").HandlersFor<{
+export declare const ToolsLayer: (projectRoot: string, distribution?: Distribution) => import("effect/Layer").Layer<import("effect/unstable/ai/Tool").HandlersFor<{
   readonly concept_neighbors: import("effect/unstable/ai/Tool").Tool<"concept_neighbors", {
     readonly parameters: import("effect/Schema").Struct<{
       readonly id: import("effect/Schema").String;
@@ -730,7 +751,12 @@ export declare const ToolsLayer: (projectRoot: string) => import("effect/Layer")
     readonly success: import("effect/Schema").Struct<{
       readonly schema: import("effect/Schema").Literal<1>;
       readonly okfit_version: import("effect/Schema").String;
+      readonly engine_version: import("effect/Schema").String;
       readonly producer: import("effect/Schema").String;
+      readonly distribution: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+        readonly name: import("effect/Schema").String;
+        readonly version: import("effect/Schema").String;
+      }>>;
       readonly okf_version: import("effect/Schema").String;
       readonly root: import("effect/Schema").String;
       readonly profile: import("effect/Schema").NullOr<import("effect/Schema").String>;
@@ -766,5 +792,5 @@ export declare const ToolsLayer: (projectRoot: string) => import("effect/Layer")
  */
 export declare const MCP_VERSION: string;
 //#endregion
-export type { PlatformServices };
+export type { PlatformServices, ServerOptions };
 //# sourceMappingURL=index.d.ts.map

package/main.d.ts

@@ -1,9 +1,16 @@
+import { Distribution } from "@okfit/engine";
 //#region src/main.d.ts
 /**
- * The assembled okfit MCP server program.
+ * Options `@okfit/plugin`'s `okfit-mcp` bin shim (and only it, today) passes
+ * to {@link main}. `distribution` names the meta-package the server was
+ * launched through; omitted for a direct install of `@okfit/mcp` (okfit
+ * #137).
  *
- * @packageDocumentation
+ * @public
  */
+export interface MainOptions {
+  readonly distribution?: Distribution;
+}
 /**
  * Run the okfit MCP server over stdio. Owns the process.
  *
@@ -11,10 +18,12 @@
  * the `uncaughtException` and `unhandledRejection` handlers are registered
  * before `NodeRuntime`, the logger and `ServerLayer` are ever evaluated, so
  * a throw during module evaluation is still reported on stderr rather than
- * crashing silently. Adding a static import here would defeat that.
+ * crashing silently. Adding a static import here would defeat that --
+ * `Distribution` above is a type-only import, so it carries no runtime
+ * import at all.
  *
  * @public
  */
-export declare const main: () => Promise<void>;
+export declare const main: (options?: MainOptions) => Promise<void>;
 //#endregion
 //# sourceMappingURL=main.d.ts.map

package/main.js

@@ -1,9 +1,4 @@
 //#region src/main.ts
-/**
-* The assembled okfit MCP server program.
-*
-* @packageDocumentation
-*/
 const FATAL_FALLBACK = "okfit-mcp: a fatal error occurred and could not be described.";
 const describe = (error) => {
 	try {
@@ -24,11 +19,13 @@ const fatal = (label, error) => {
 * the `uncaughtException` and `unhandledRejection` handlers are registered
 * before `NodeRuntime`, the logger and `ServerLayer` are ever evaluated, so
 * a throw during module evaluation is still reported on stderr rather than
-* crashing silently. Adding a static import here would defeat that.
+* crashing silently. Adding a static import here would defeat that --
+* `Distribution` above is a type-only import, so it carries no runtime
+* import at all.
 *
 * @public
 */
-const main = async () => {
+const main = async (options = {}) => {
 	process.on("uncaughtException", (error) => fatal("uncaught exception", error));
 	process.on("unhandledRejection", (reason) => fatal("unhandled rejection", reason));
 	const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
@@ -37,7 +34,7 @@ const main = async () => {
 	const { resolveMcpProjectRoot } = await import("./internal/projectRoot.js");
 	const { ServerLayer } = await import("./server.js");
 	const projectRoot = resolveMcpProjectRoot(process.env);
-	const program = Layer.launch(ServerLayer(projectRoot).pipe(Layer.provide(OkfitPlatform), Layer.provide(Logger.layer([Logger.consolePretty()])), Layer.provide(Layer.succeed(Logger.LogToStderr, true))));
+	const program = Layer.launch(ServerLayer(projectRoot, options).pipe(Layer.provide(OkfitPlatform), Layer.provide(Logger.layer([Logger.consolePretty()])), Layer.provide(Layer.succeed(Logger.LogToStderr, true))));
 	NodeRuntime.runMain(program, { teardown: (exit, onExit) => Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) ? onExit(0) : Runtime.defaultTeardown(exit, onExit) });
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/mcp",
-	"version": "0.3.6",
+	"version": "0.4.0",
 	"private": false,
 	"description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
 	"keywords": [
@@ -47,9 +47,9 @@
 		"@effect/platform-node": "4.0.0-rc.115",
 		"@effected/git": "^0.15.1",
 		"@effected/xdg": "^0.5.2",
-		"@okfit/core": "0.5.0",
-		"@okfit/engine": "0.5.0",
-		"@okfit/profiles": "0.7.0",
+		"@okfit/core": "0.7.0",
+		"@okfit/engine": "0.7.0",
+		"@okfit/profiles": "0.7.2",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {

package/server.js

@@ -25,7 +25,7 @@ import { GitHistory } from "@okfit/profiles";
 *
 * @public
 */
-const ServerLayer = (projectRoot) => Layer.mergeAll(McpServer.toolkit(OkfitToolkit).pipe(Layer.provideMerge(ToolsLayer(projectRoot))), ConceptResources(projectRoot), IndexResource(projectRoot)).pipe(Layer.provide(Layer.mergeAll(Git.layer, GitHistory.layer)), Layer.provide(McpServer.layerStdio({
+const ServerLayer = (projectRoot, options = {}) => Layer.mergeAll(McpServer.toolkit(OkfitToolkit).pipe(Layer.provideMerge(ToolsLayer(projectRoot, options.distribution))), ConceptResources(projectRoot), IndexResource(projectRoot)).pipe(Layer.provide(Layer.mergeAll(Git.layer, GitHistory.layer)), Layer.provide(McpServer.layerStdio({
 	name: "okfit",
 	version: MCP_VERSION,
 	protocols: [McpProtocol.v2025_11_25, McpProtocol.v2025_06_18]

package/toolkit.js

@@ -18,16 +18,19 @@ const OkfitToolkit = Toolkit.make(describeVocabulary, listConcepts, getConcept,
 /**
 * The handler layer. `projectRoot` is closed over from the bin (N-21);
 * the bundle itself reloads on every call inside each handler (N-9).
+* `distribution` (okfit #137) is whatever `ServerLayer` was given -- only
+* `validate_bundle` renders a `JsonEnvelope`, so it is the only handler
+* that needs it.
 *
 * @public
 */
-const ToolsLayer = (projectRoot) => OkfitToolkit.toLayer({
+const ToolsLayer = (projectRoot, distribution) => OkfitToolkit.toLayer({
 	describe_vocabulary: () => handleDescribeVocabulary(projectRoot),
 	list_concepts: (params) => handleListConcepts(projectRoot, params),
 	get_concept: (params) => handleGetConcept(projectRoot, params),
 	concept_neighbors: (params) => handleConceptNeighbors(projectRoot, params),
 	stale_report: (params) => handleStaleReport(projectRoot, params),
-	validate_bundle: (params) => handleValidateBundle(projectRoot, params)
+	validate_bundle: (params) => handleValidateBundle(projectRoot, params, distribution)
 });
 
 //#endregion

package/tools/validateBundle.js

@@ -61,11 +61,13 @@ const validateBundle = Tool.make("validate_bundle", {
 * (J-2): the field names the package that produced the report, and
 * `producer` says which package that is so a reader comparing this report
 * with `okfit validate --format json` does not read the two versions as
-* drift (okfit #75).
+* drift (okfit #75). `distribution` is whatever `ServerLayer` was given
+* (okfit #137) -- `null` unless the launching bin came through
+* `@okfit/plugin`.
 *
 * @public
 */
-const handleValidateBundle = (projectRoot, params) => Effect.gen(function* () {
+const handleValidateBundle = (projectRoot, params, distribution) => Effect.gen(function* () {
 	const resolved = yield* resolveConfigOnly(projectRoot);
 	const now = yield* resolveNow(params.now);
 	const result = yield* run({
@@ -94,7 +96,8 @@ const handleValidateBundle = (projectRoot, params) => Effect.gen(function* () {
 		}),
 		exitCode: code,
 		concepts: result.bundle.concepts.size,
-		diagnostics
+		diagnostics,
+		...distribution === void 0 ? {} : { distribution }
 	});
 });
 

package/version.js

@@ -5,7 +5,7 @@
 *
 * @public
 */
-const MCP_VERSION = "0.3.6";
+const MCP_VERSION = "0.4.0";
 
 //#endregion
 export { MCP_VERSION };