@okfit/mcp 0.1.0 → 0.2.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/cli";
+
+//#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/package.js

@@ -0,0 +1,5 @@
+//#region package.json
+var version = "0.2.0";
+
+//#endregion
+export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/mcp",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"private": false,
 	"description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
 	"keywords": [
@@ -39,8 +39,13 @@
 		"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/cli": "0.2.0",
+		"@okfit/core": "0.2.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/cli";
+
+//#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 };

package/tools/describeVocabulary.js

@@ -0,0 +1,73 @@
+import { McpToolError } from "../errors.js";
+import { resolveConfigOnly } from "../internal/toolContext.js";
+import { DescribeVocabularySuccess } from "../schema/tools.js";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Tool } from "effect/unstable/ai";
+import { contextEnvelope } from "@okfit/cli";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/tools/describeVocabulary.ts
+const DESCRIPTION = "Returns this project's resolved okfit configuration: the project root, bundle root, active profile, configured agent actor, and the full set of concept types and tags the config declares, each with its description. Call this first, before filtering or writing any concept, to learn which type and tag names actually exist in this project.";
+/**
+* `dependencies` names the platform services `handleDescribeVocabulary`
+* needs (`resolveConfigOnly` -> `resolveProjectConfig`/`provideConfig`);
+* without it `Tool.HandlerServices` infers `never` and the handler record
+* passed to `Toolkit.toLayer` fails to typecheck against `HandlersFrom`
+* (verified against `.repos/effect/packages/effect/src/unstable/ai/Tool.ts`
+* `dependencies`/`HandlerServices`; not spelled out in the brief's snippet).
+*
+* `parameters` is `Tool.EmptyParams`, not the brief's `Schema.Struct({})`:
+* a zero-key `Schema.Struct` fails `McpServer.layerStdio`'s build with a
+* `SchemaError` (`MissingKey` at path `type`) when the toolkit registers
+* its JSON Schema, reproduced in isolation against a minimal tool and
+* confirmed fixed by switching to `Tool.EmptyParams` — the same schema
+* Effect's own MCP conformance fixtures use for parameterless tools
+* (`.repos/effect/packages/effect/test/unstable/ai/McpServer/McpConformance/McpConformanceFixtures.ts:29`).
+*
+* @public
+*/
+const describeVocabulary = Tool.make("describe_vocabulary", {
+	description: DESCRIPTION,
+	parameters: Tool.EmptyParams,
+	success: DescribeVocabularySuccess,
+	failure: McpToolError,
+	dependencies: [
+		FileSystem.FileSystem,
+		Path.Path,
+		AppDirs,
+		Xdg
+	]
+}).annotate(Tool.Title, "Describe okfit vocabulary").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/** @public */
+const handleDescribeVocabulary = (projectRoot) => Effect.gen(function* () {
+	const resolved = yield* resolveConfigOnly(projectRoot);
+	const envelope = contextEnvelope({
+		projectRoot: resolved.projectRoot,
+		bundleRoot: resolved.bundleRoot,
+		configPath: Option.match(resolved.discovered, {
+			onNone: () => null,
+			onSome: (d) => d.path
+		}),
+		profile: Option.match(resolved.profile, {
+			onNone: () => null,
+			onSome: (p) => p.name
+		}),
+		profileRequested: resolved.profileName,
+		indexPath: "",
+		indexExists: false,
+		config: resolved.config
+	});
+	return {
+		project_root: envelope.project_root,
+		bundle_root: envelope.bundle_root,
+		config_path: envelope.config_path,
+		profile: envelope.profile,
+		profile_requested: envelope.profile_requested,
+		agent: envelope.actors.agent,
+		types: envelope.types,
+		tags: envelope.tags
+	};
+});
+
+//#endregion
+export { describeVocabulary, handleDescribeVocabulary };