@okfit/mcp 0.1.0 → 0.3.0

package/index.js

@@ -1,21 +1,10 @@
-//#region src/index.ts
-/**
-* Model Context Protocol server for okfit.
-*
-* @packageDocumentation
-*/
-/**
-* Message the stub bin writes to stderr until the server exists.
-*
-* @public
-*/
-const NOT_IMPLEMENTED_MESSAGE = "okfit-mcp: the MCP server is not implemented yet. Track progress at https://github.com/spencerbeggs/okfit.";
-/**
-* Exit code the stub bin uses.
-*
-* @public
-*/
-const NOT_IMPLEMENTED_EXIT_CODE = 1;
+import { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary, composeRemediatedMessage, truncateEchoed } from "./errors.js";
+import { ConceptResources } from "./resources/conceptResource.js";
+import { IndexResource } from "./resources/indexResource.js";
+import { ConceptSummary, toConceptSummary } from "./schema/ConceptSummary.js";
+import { ConceptNeighborsSuccess, DescribeVocabularySuccess, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams } from "./schema/tools.js";
+import { MCP_VERSION } from "./version.js";
+import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
+import { ServerLayer } from "./server.js";
 
-//#endregion
-export { NOT_IMPLEMENTED_EXIT_CODE, NOT_IMPLEMENTED_MESSAGE };
+export { BundleNotFound, ConceptNeighborsSuccess, ConceptNotFound, ConceptResources, ConceptSummary, ConfigError, DescribeVocabularySuccess, GetConceptSuccess, IndexResource, InvalidArgument, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, UnknownVocabulary, ValidateBundleParams, composeRemediatedMessage, toConceptSummary, truncateEchoed };

package/internal/projectRoot.js

@@ -0,0 +1,14 @@
+//#region src/internal/projectRoot.ts
+/**
+* N-21's precedence, exactly: `OKFIT_PROJECT_DIR`, else
+* `CLAUDE_PROJECT_DIR`, else the process's working directory. Pure over
+* its `env` argument so tests never touch `process.env`. No argv flags:
+* `start-mcp.sh` forwards `"$@"` with nothing in it, and the manifest's
+* `cwd` field is unused.
+*
+* @internal
+*/
+const resolveMcpProjectRoot = (env) => env["OKFIT_PROJECT_DIR"] ?? env["CLAUDE_PROJECT_DIR"] ?? process.cwd();
+
+//#endregion
+export { resolveMcpProjectRoot };

package/internal/resolveNow.js

@@ -0,0 +1,26 @@
+import { InvalidArgument, composeRemediatedMessage } from "../errors.js";
+import { DateTime, Effect, Schema } from "effect";
+import { Timestamp } from "@okfit/core";
+
+//#region src/internal/resolveNow.ts
+/**
+* An optional ISO-8601 `now` argument, else the Effect clock. Decoding
+* happens here rather than in the parameter schema so a malformed value
+* becomes this contract's `InvalidArgument` — with a remediation hint —
+* instead of Effect's generic protocol-level `InvalidParams` (J-5).
+* `OKFIT_NOW` is deliberately NOT read: it is the CLI's own test hook
+* (F-17), never the server's.
+*
+* @internal
+*/
+const resolveNow = (input) => input === void 0 ? DateTime.now : Schema.decodeUnknownEffect(Timestamp)(input).pipe(Effect.mapError((issue) => {
+	const remediation = { hint: "now must be an ISO-8601 instant with an explicit offset, for example 2026-09-06T00:00:00Z." };
+	return new InvalidArgument({
+		argument: "now",
+		message: composeRemediatedMessage(String(issue), remediation),
+		remediation
+	});
+}));
+
+//#endregion
+export { resolveNow };

package/internal/toolContext.js

@@ -0,0 +1,77 @@
+import { BundleNotFound, ConfigError, composeRemediatedMessage } from "../errors.js";
+import { Effect, Option } from "effect";
+import { Bundle } from "@okfit/core";
+import { provideConfig, resolveProjectConfig } from "@okfit/engine";
+
+//#region src/internal/toolContext.ts
+/**
+* The error's `message` when it has one as a string, else `String(error)`.
+* A four-line local copy of `CLI/render/json.ts`'s own helper, which is
+* module-private there and cannot be imported.
+*/
+const messageOf = (error) => {
+	if (typeof error === "object" && error !== null && "message" in error) {
+		const message = error.message;
+		if (typeof message === "string") return message;
+	}
+	return String(error);
+};
+const CONFIG_HINT = "Check the project's .okfit.toml, okfit.toml, or .config/okfit.toml for a syntax or schema error; remove it to fall back to defaults.";
+/**
+* Config resolution alone, with every failure collapsed to `ConfigError`.
+* `describe_vocabulary` and `validate_bundle` use this; every other tool
+* goes through {@link loadToolContext}.
+*
+* The requirement union (`FileSystem.FileSystem | Path.Path | AppDirs | Xdg`)
+* is inlined here rather than named, so API Extractor never needs a local
+* type alias exported from the package's entry point (K-32-adjacent; a
+* private `ToolServices` alias failed `ae-forgotten-export` at the entry
+* point in this task's own build).
+*
+* @internal
+*/
+const resolveConfigOnly = (projectRoot) => resolveProjectConfig({
+	pathArg: Option.none(),
+	explicitConfigPath: Option.none(),
+	cwd: projectRoot
+}).pipe(provideConfig({
+	explicitConfigPath: Option.none(),
+	discoveryCwd: projectRoot
+}), Effect.mapError((cause) => {
+	const remediation = {
+		hint: CONFIG_HINT,
+		suggestedTool: "describe_vocabulary"
+	};
+	return new ConfigError({
+		message: composeRemediatedMessage(messageOf(cause), remediation),
+		remediation
+	});
+}));
+/**
+* Resolve config and load the bundle, fresh, for one tool call (N-9). No
+* cache and no `reload` tool: correct under mid-session edits, trivially
+* testable, and the bundles in scope are small.
+*
+* @internal
+*/
+const loadToolContext = (projectRoot) => Effect.gen(function* () {
+	const resolved = yield* resolveConfigOnly(projectRoot);
+	const bundle = yield* Bundle.load({ root: resolved.bundleRoot }).pipe(Effect.mapError((cause) => {
+		const remediation = { hint: `The bundle root "${resolved.bundleRoot}" does not exist or could not be read; check the config's [bundle].path, or run \`okfit init\`.` };
+		return new BundleNotFound({
+			root: resolved.bundleRoot,
+			message: composeRemediatedMessage(cause.message, remediation),
+			remediation
+		});
+	}));
+	return {
+		projectRoot,
+		bundleRoot: resolved.bundleRoot,
+		config: resolved.config,
+		profile: resolved.profile,
+		bundle
+	};
+});
+
+//#endregion
+export { loadToolContext, messageOf, resolveConfigOnly };

package/main.d.ts

@@ -0,0 +1,20 @@
+//#region src/main.d.ts
+/**
+ * The assembled okfit MCP server program.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Run the okfit MCP server over stdio. Owns the process.
+ *
+ * This module deliberately carries NO static imports of the server graph:
+ * 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.
+ *
+ * @public
+ */
+export declare const main: () => Promise<void>;
+//#endregion
+//# sourceMappingURL=main.d.ts.map

package/main.js

@@ -0,0 +1,45 @@
+//#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 {
+		if (error instanceof Error) return error.stack ?? error.message;
+		return String(error);
+	} catch {
+		return FATAL_FALLBACK;
+	}
+};
+const fatal = (label, error) => {
+	process.stderr.write(`okfit-mcp: ${label}: ${describe(error)}\n`);
+	process.exit(1);
+};
+/**
+* Run the okfit MCP server over stdio. Owns the process.
+*
+* This module deliberately carries NO static imports of the server graph:
+* 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.
+*
+* @public
+*/
+const main = async () => {
+	process.on("uncaughtException", (error) => fatal("uncaught exception", error));
+	process.on("unhandledRejection", (reason) => fatal("unhandled rejection", reason));
+	const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
+	const { OkfitPlatform } = await import("@okfit/engine");
+	const { Cause, Exit, Layer, Logger, Runtime } = await import("effect");
+	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))));
+	NodeRuntime.runMain(program, { teardown: (exit, onExit) => Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) ? onExit(0) : Runtime.defaultTeardown(exit, onExit) });
+};
+
+//#endregion
+export { main };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/mcp",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"private": false,
 	"description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
 	"keywords": [
@@ -33,14 +33,24 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./main": {
+			"types": "./main.d.ts",
+			"import": "./main.js",
+			"default": "./main.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"bin": {
 		"okfit-mcp": "bin/okfit-mcp.js"
 	},
 	"dependencies": {
-		"@okfit/core": "0.1.0",
-		"effect": "4.0.0-rc.109"
+		"@effect/platform-node": "4.0.0-rc.112",
+		"@effected/git": "^0.12.0",
+		"@effected/xdg": "^0.4.1",
+		"@okfit/core": "0.2.0",
+		"@okfit/engine": "0.1.0",
+		"@okfit/profiles": "0.2.0",
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/resources/conceptResource.js

@@ -0,0 +1,63 @@
+import { loadToolContext } from "../internal/toolContext.js";
+import { Effect, FileSystem, Layer, Path } from "effect";
+import { Derive } from "@okfit/core";
+import { McpSchema, McpServer } from "effect/unstable/ai";
+
+//#region src/resources/conceptResource.ts
+/**
+* `okf://concept/<id>` — one static resource per concept in the bundle,
+* built once at server start.
+*
+* Amends N-19 and contract §6.1 (Ruling, task C4): a `McpServer.resource`
+* URI **template** routes a `McpSchema.param` through a single path
+* segment only — `FindMyWay`'s parametric matcher stops a param at the
+* next `/` (`.repos/effect/packages/effect/src/unstable/http/FindMyWay/internal/router.ts:355-360`),
+* and every non-root OKF concept id nests under a type directory (D-12),
+* e.g. `metrics/revenue`. A templated `okf://concept/{id}` therefore never
+* routes a real bundle id. Static per-concept resources sidestep the
+* router entirely: each concept gets its own literal `uri`, so there is
+* no segment-spanning to fail.
+*
+* The list is fixed at server start (`loadToolContext` runs once, inside
+* `Layer.unwrap`, not per read): a concept added after boot is not listed
+* until the server restarts, though editing an already-listed concept's
+* file is picked up live, since `content` re-reads the file from disk on
+* every read (same complete text `get_concept`'s `raw` field returns).
+*
+* If the bundle fails to load at boot (bad config, missing bundle root),
+* one line is logged and this layer contributes no resources — the
+* six tools stay usable; only `okf://index` remains, since it is
+* registered independently and re-resolves the bundle on every read.
+*
+* `content` builds the full `ReadResourceResult` itself, `mimeType`
+* included, rather than returning a bare string: verified against source
+* (`resolveResourceContent`, `unstable/ai/McpServer.ts:2324-2343`), a bare
+* string is wrapped as `{ contents: [{ uri, text }] }` with no `mimeType`
+* at all — the declared `mimeType` option only documents the resource in
+* `resources/list`, it is never merged into a `resources/read` response.
+*
+* @public
+*/
+const ConceptResources = (projectRoot) => Layer.unwrap(Effect.gen(function* () {
+	const ctx = yield* loadToolContext(projectRoot);
+	const path = yield* Path.Path;
+	const fs = yield* FileSystem.FileSystem;
+	return [...ctx.bundle.concepts.entries()].map(([id, concept]) => {
+		const uri = `okf://concept/${id}`;
+		const absolutePath = path.join(ctx.bundleRoot, concept.path);
+		return McpServer.resource({
+			uri,
+			name: id,
+			description: Derive.title(concept),
+			mimeType: "text/markdown",
+			content: fs.readFileString(absolutePath).pipe(Effect.map((text) => ({ contents: [{
+				uri,
+				mimeType: "text/markdown",
+				text
+			}] })), Effect.mapError(() => new McpSchema.InternalError({ message: `no readable concept file at ${absolutePath}` })))
+		});
+	}).reduce((acc, layer) => acc.pipe(Layer.merge(layer)), Layer.empty);
+}).pipe(Effect.tapError((error) => Effect.logError(`okfit-mcp: could not load the bundle to register concept resources: ${error.message}`)), Effect.orElseSucceed(() => Layer.empty)));
+
+//#endregion
+export { ConceptResources };

package/resources/indexResource.js

@@ -0,0 +1,49 @@
+import { loadToolContext } from "../internal/toolContext.js";
+import { Effect, FileSystem, Path } from "effect";
+import { McpSchema, McpServer } from "effect/unstable/ai";
+
+//#region src/resources/indexResource.ts
+/**
+* `okf://index` — the bundle's root `index.md`, read from disk.
+*
+* This reads the file from disk, deliberately (J-7): `IndexDocument`
+* carries only `{ path, dir, okfVersion?, sections }` — no raw-source
+* field at all — so `bundle.indexes.get("")` cannot supply the raw
+* markdown N-19 asks for. Reading the file also means a root `index.md`
+* that failed to parse is still served, which is the more useful
+* behaviour for an agent trying to fix it.
+*
+* A missing `index.md` fails the read rather than returning placeholder
+* text (J-8): a resource that silently returns prose instead of the file
+* it names is indistinguishable, to a model, from a bundle whose index
+* really says that; §6.1 already fails an unknown id through the same
+* channel.
+*
+* `content` builds the full `ReadResourceResult` itself, `mimeType`
+* included, rather than returning a bare string: verified against source
+* (`resolveResourceContent`, `unstable/ai/McpServer.ts:2324-2343`), a bare
+* string is wrapped as `{ contents: [{ uri, text }] }` with no `mimeType`
+* at all — the declared `mimeType` option only documents the resource in
+* `resources/list`, it is never merged into a `resources/read` response.
+*
+* @public
+*/
+const IndexResource = (projectRoot) => McpServer.resource({
+	uri: "okf://index",
+	name: "OKF bundle index",
+	description: "The bundle's root index.md — the entry point for orienting on this OKF bundle.",
+	mimeType: "text/markdown",
+	content: Effect.gen(function* () {
+		const ctx = yield* loadToolContext(projectRoot);
+		const fs = yield* FileSystem.FileSystem;
+		const indexPath = (yield* Path.Path).join(ctx.bundleRoot, "index.md");
+		return { contents: [{
+			uri: "okf://index",
+			mimeType: "text/markdown",
+			text: yield* fs.readFileString(indexPath).pipe(Effect.mapError(() => new McpSchema.InternalError({ message: `no readable index.md at ${indexPath}` })))
+		}] };
+	})
+});
+
+//#endregion
+export { IndexResource };

package/schema/ConceptSummary.js

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+import { Derive, Status } from "@okfit/core";
+
+//#region src/schema/ConceptSummary.ts
+/** The seven-field shape every list-like tool result carries (N-16). @public */
+const ConceptSummary = Schema.Struct({
+	id: Schema.String,
+	type: Schema.String,
+	title: Schema.String,
+	description: Schema.NullOr(Schema.String),
+	status: Status,
+	tags: Schema.Array(Schema.String),
+	path: Schema.String
+});
+/** Project one loaded concept into its summary. @public */
+const toConceptSummary = (concept) => ({
+	id: concept.id,
+	type: concept.frontmatter.type,
+	title: Derive.title(concept),
+	description: concept.frontmatter.description ?? null,
+	status: Derive.status(concept.frontmatter),
+	tags: [...concept.frontmatter.tags ?? []],
+	path: concept.path
+});
+
+//#endregion
+export { ConceptSummary, toConceptSummary };

package/schema/tools.js

@@ -0,0 +1,78 @@
+import { ConceptSummary } from "./ConceptSummary.js";
+import { Schema } from "effect";
+import { GraphNodeKind, Status } from "@okfit/core";
+import { ContextTag, ContextType } from "@okfit/engine";
+
+//#region src/schema/tools.ts
+/** `describe_vocabulary`'s result (§5.2). @public */
+const DescribeVocabularySuccess = Schema.Struct({
+	project_root: Schema.String,
+	bundle_root: Schema.String,
+	config_path: Schema.NullOr(Schema.String),
+	profile: Schema.NullOr(Schema.String),
+	profile_requested: Schema.NullOr(Schema.String),
+	agent: Schema.NullOr(Schema.String),
+	types: Schema.Array(ContextType),
+	tags: Schema.Array(ContextTag)
+});
+/** `list_concepts`' arguments (§5.3). @public */
+const ListConceptsParams = Schema.Struct({
+	type: Schema.optionalKey(Schema.String),
+	tags: Schema.optionalKey(Schema.Array(Schema.String)),
+	status: Schema.optionalKey(Status),
+	limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 1e3
+	}))),
+	offset: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+});
+/** `list_concepts`' result: the page, plus the match count before paging. @public */
+const ListConceptsSuccess = Schema.Struct({
+	items: Schema.Array(ConceptSummary),
+	total: Schema.Int
+});
+/** `get_concept`'s result (§5.4). @public */
+const GetConceptSuccess = Schema.Struct({
+	id: Schema.String,
+	type: Schema.String,
+	title: Schema.String,
+	description: Schema.NullOr(Schema.String),
+	status: Status,
+	tags: Schema.Array(Schema.String),
+	path: Schema.String,
+	frontmatter: Schema.Record(Schema.String, Schema.Unknown),
+	raw: Schema.String,
+	links: Schema.Array(Schema.Struct({
+		to: Schema.String,
+		kind: GraphNodeKind,
+		source: Schema.Literals(["body", "frontmatter"]),
+		field: Schema.optionalKey(Schema.String)
+	}))
+});
+/** One graph neighbour: flat, with a nullable summary (J-4). @public */
+const Neighbor = Schema.Struct({
+	id: Schema.String,
+	kind: GraphNodeKind,
+	summary: Schema.NullOr(ConceptSummary)
+});
+/** `concept_neighbors`' result (§5.5). @public */
+const ConceptNeighborsSuccess = Schema.Struct({
+	outgoing: Schema.Array(Neighbor),
+	incoming: Schema.Array(Neighbor)
+});
+/** `stale_report`'s arguments: an optional ISO instant, decoded in the handler (J-5). @public */
+const StaleReportParams = Schema.Struct({ now: Schema.optionalKey(Schema.String) });
+/** `stale_report`'s result (§5.6). @public */
+const StaleReportSuccess = Schema.Struct({
+	as_of: Schema.String,
+	items: Schema.Array(Schema.Struct({
+		summary: ConceptSummary,
+		stale_after: Schema.String,
+		days_past: Schema.Int
+	}))
+});
+/** `validate_bundle`'s arguments: the same shape and decode path as stale_report. @public */
+const ValidateBundleParams = Schema.Struct({ now: Schema.optionalKey(Schema.String) });
+
+//#endregion
+export { ConceptNeighborsSuccess, DescribeVocabularySuccess, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams };

package/server.js

@@ -0,0 +1,35 @@
+import { ConceptResources } from "./resources/conceptResource.js";
+import { IndexResource } from "./resources/indexResource.js";
+import { MCP_VERSION } from "./version.js";
+import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
+import { Layer } from "effect";
+import { McpProtocol, McpServer } from "effect/unstable/ai";
+import { Git } from "@effected/git";
+import { GitHistory } from "@okfit/profiles";
+
+//#region src/server.ts
+/**
+* The whole server as one layer: the toolkit, one static resource per
+* concept (`okf://concept/<id>`, built once at boot — see
+* {@link ConceptResources}), and `okf://index` (re-read from disk on every
+* call), over `McpServer.layerStdio`.
+*
+* `protocols` ships BOTH adapters, newest first (N-2). Array order is
+* load-bearing: the protocol registry falls back to `protocols[0]` for an
+* unrecognised client version, so a 2026-07-28 client is answered with
+* 2025-11-25. Never reduce this to one entry.
+*
+* `Cause.IllegalArgumentError` in `layerStdio`'s signature is left
+* unhandled: `protocols` is a static two-element literal, so it is an
+* implementer-time defect, not a runtime condition.
+*
+* @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({
+	name: "okfit",
+	version: MCP_VERSION,
+	protocols: [McpProtocol.v2025_11_25, McpProtocol.v2025_06_18]
+})), Layer.orDie);
+
+//#endregion
+export { ServerLayer };

package/toolkit.js

@@ -0,0 +1,34 @@
+import { conceptNeighbors, handleConceptNeighbors } from "./tools/conceptNeighbors.js";
+import { describeVocabulary, handleDescribeVocabulary } from "./tools/describeVocabulary.js";
+import { getConcept, handleGetConcept } from "./tools/getConcept.js";
+import { handleListConcepts, listConcepts } from "./tools/listConcepts.js";
+import { handleStaleReport, staleReport } from "./tools/staleReport.js";
+import { handleValidateBundle, validateBundle } from "./tools/validateBundle.js";
+import { Toolkit } from "effect/unstable/ai";
+
+//#region src/toolkit.ts
+/**
+* The six read-only tools (N-10). Tasks C1, C2 and C3 each add two; the
+* order here is the tool set's own order and is what
+* `agents/okf-docs.md`'s `tools:` allowlist mirrors.
+*
+* @public
+*/
+const OkfitToolkit = Toolkit.make(describeVocabulary, listConcepts, getConcept, conceptNeighbors, staleReport, validateBundle);
+/**
+* The handler layer. `projectRoot` is closed over from the bin (N-21);
+* the bundle itself reloads on every call inside each handler (N-9).
+*
+* @public
+*/
+const ToolsLayer = (projectRoot) => 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)
+});
+
+//#endregion
+export { OkfitToolkit, ToolsLayer };

package/tools/conceptNeighbors.js

@@ -0,0 +1,87 @@
+import { ConceptNotFound, InvalidArgument, McpToolError, composeRemediatedMessage, truncateEchoed } from "../errors.js";
+import { loadToolContext } from "../internal/toolContext.js";
+import { toConceptSummary } from "../schema/ConceptSummary.js";
+import { ConceptNeighborsSuccess } from "../schema/tools.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { ConceptId, Graph } from "@okfit/core";
+import { Tool } from "effect/unstable/ai";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/tools/conceptNeighbors.ts
+const DESCRIPTION = "Returns the graph neighbours of one concept: everything it links to (outgoing) and everything that links to it (incoming), each with the node kind and, for a concept target, its full summary. Use it after get_concept to walk the bundle's link graph one hop at a time without loading every concept.";
+/**
+* `dependencies` mirrors the other tools' (Task B1's Deviation 1): without it
+* `Tool.HandlerServices` infers `never`, failing the handler record against
+* `HandlersFrom` when passed to `OkfitToolkit.toLayer`.
+*
+* @public
+*/
+const conceptNeighbors = Tool.make("concept_neighbors", {
+	description: DESCRIPTION,
+	parameters: Schema.Struct({ id: Schema.String }),
+	success: ConceptNeighborsSuccess,
+	failure: McpToolError,
+	dependencies: [
+		FileSystem.FileSystem,
+		Path.Path,
+		AppDirs,
+		Xdg
+	]
+}).annotate(Tool.Title, "Concept graph neighbors").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/**
+* Deviation from the brief's literal snippet, matching the ruling binding
+* every C task (progress.md): `message` is composed through
+* {@link composeRemediatedMessage} at construction, since a declared typed
+* failure under `failureMode: "error"` never reaches the wire with
+* `structuredContent` — only `error.message` does.
+*
+* @public
+*/
+const handleConceptNeighbors = (projectRoot, params) => Effect.gen(function* () {
+	const ctx = yield* loadToolContext(projectRoot);
+	const normalized = ConceptId.normalize(params.id);
+	if (Option.isNone(normalized)) {
+		const remediation = {
+			hint: "Pass a bundle-relative concept id such as decisions/cli-exit-codes.",
+			suggestedTool: "list_concepts"
+		};
+		return yield* Effect.fail(new InvalidArgument({
+			argument: "id",
+			message: composeRemediatedMessage("id must not be empty", remediation),
+			remediation
+		}));
+	}
+	const id = normalized.value;
+	if (!ctx.bundle.concepts.has(id)) {
+		const remediation = {
+			hint: "Call list_concepts to see the ids this bundle contains.",
+			suggestedTool: "list_concepts"
+		};
+		return yield* Effect.fail(new ConceptNotFound({
+			id: params.id,
+			message: composeRemediatedMessage(`no concept "${truncateEchoed(params.id)}" in this bundle`, remediation),
+			remediation
+		}));
+	}
+	const graph = Graph.fromBundle(ctx.bundle);
+	const project = (node) => {
+		if (node.kind !== "concept") return {
+			id: node.id,
+			kind: node.kind,
+			summary: null
+		};
+		const concept = ctx.bundle.concepts.get(node.id);
+		return {
+			id: node.id,
+			kind: node.kind,
+			summary: concept === void 0 ? null : toConceptSummary(concept)
+		};
+	};
+	return {
+		outgoing: graph.successors(id).map(project),
+		incoming: graph.predecessors(id).map(project)
+	};
+});
+
+//#endregion
+export { conceptNeighbors, handleConceptNeighbors };