@okfit/mcp 0.1.0 → 0.3.0

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/engine";
+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 };

package/tools/getConcept.js

@@ -0,0 +1,93 @@
+import { ConceptNotFound, InvalidArgument, McpToolError, composeRemediatedMessage, truncateEchoed } from "../errors.js";
+import { loadToolContext } from "../internal/toolContext.js";
+import { GetConceptSuccess } from "../schema/tools.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { ConceptId, Derive, Graph } from "@okfit/core";
+import { Tool } from "effect/unstable/ai";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/tools/getConcept.ts
+const DESCRIPTION = "Returns one concept by id: its whole decoded frontmatter, the file's raw markdown text, its bundle-relative path, and every outgoing link with where the link was written and whether the target is another concept, an existing file, or missing. Accepts a tolerant id, with or without a leading slash or a trailing .md.";
+/**
+* `dependencies` mirrors `list_concepts`' and `describe_vocabulary`'s
+* (Task B1's Deviation 1, carried through Task C1): `loadToolContext` needs
+* the same platform services, and without a `dependencies` declaration
+* `Tool.HandlerServices` infers `never`, failing the handler record against
+* `HandlersFrom` when it is passed to `OkfitToolkit.toLayer`.
+*
+* @public
+*/
+const getConcept = Tool.make("get_concept", {
+	description: DESCRIPTION,
+	parameters: Schema.Struct({ id: Schema.String }),
+	success: GetConceptSuccess,
+	failure: McpToolError,
+	dependencies: [
+		FileSystem.FileSystem,
+		Path.Path,
+		AppDirs,
+		Xdg
+	]
+}).annotate(Tool.Title, "Get one OKF concept").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 handleGetConcept = (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;
+	const concept = ctx.bundle.concepts.get(id);
+	if (concept === void 0) {
+		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 links = graph.edges.filter((edge) => edge.from === id).map((edge) => ({
+		to: edge.to,
+		kind: Option.match(graph.node(edge.to), {
+			onNone: () => "missing",
+			onSome: (node) => node.kind
+		}),
+		source: edge.data.source,
+		...edge.data.field === void 0 ? {} : { field: edge.data.field }
+	}));
+	return {
+		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,
+		frontmatter: concept.frontmatter.raw,
+		raw: concept.document.source,
+		links
+	};
+});
+
+//#endregion
+export { getConcept, handleGetConcept };

package/tools/listConcepts.js

@@ -0,0 +1,81 @@
+import { McpToolError, UnknownVocabulary, composeRemediatedMessage, truncateEchoed } from "../errors.js";
+import { loadToolContext } from "../internal/toolContext.js";
+import { toConceptSummary } from "../schema/ConceptSummary.js";
+import { ListConceptsParams, ListConceptsSuccess } from "../schema/tools.js";
+import { Effect, FileSystem, Path } from "effect";
+import { Derive } from "@okfit/core";
+import { Tool } from "effect/unstable/ai";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/tools/listConcepts.ts
+const DESCRIPTION = "Lists concept summaries from the okf bundle, optionally filtered by an exact type, by tags that must all be present (AND, not OR), and by status. Pages with limit (default 200, max 1000) and offset, and reports the total matching count. Use it to discover what exists before reading one concept with get_concept; an unknown type or tag name fails with the list of valid names.";
+/**
+* `dependencies` mirrors `describe_vocabulary`'s (Deviation 1 in Task B1's
+* report): `loadToolContext` needs the same platform services
+* (`resolveConfigOnly` -> `resolveProjectConfig`/`provideConfig`, plus
+* `Bundle.load`), and without a `dependencies` declaration
+* `Tool.HandlerServices` infers `never`, failing the handler record against
+* `HandlersFrom` when it is passed to `OkfitToolkit.toLayer`.
+*
+* @public
+*/
+const listConcepts = Tool.make("list_concepts", {
+	description: DESCRIPTION,
+	parameters: ListConceptsParams,
+	success: ListConceptsSuccess,
+	failure: McpToolError,
+	dependencies: [
+		FileSystem.FileSystem,
+		Path.Path,
+		AppDirs,
+		Xdg
+	]
+}).annotate(Tool.Title, "List OKF concepts").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/**
+* Deviation from the brief's literal snippet: `message` is composed through
+* {@link composeRemediatedMessage} (per the controller's ruling binding every
+* C task, progress.md), and the raw message embeds the full `valid` list
+* rather than leaving it only on the schema's `valid` field — a declared
+* typed failure under `failureMode: "error"` never reaches the wire with
+* `structuredContent` (B1's finding), so `valid` would otherwise be
+* unreachable to a real caller reading only `content[0].text`.
+*/
+const unknown = (kind, requested, valid) => {
+	const remediation = {
+		hint: "Use one of the listed type names, or call describe_vocabulary.",
+		suggestedTool: "describe_vocabulary"
+	};
+	const rawMessage = `"${truncateEchoed(requested)}" is not a ${kind} declared by this project's okfit config. Valid ${kind}s: ${valid.join(", ")}.`;
+	return new UnknownVocabulary({
+		kind,
+		requested,
+		valid,
+		message: composeRemediatedMessage(rawMessage, remediation),
+		remediation
+	});
+};
+/** @public */
+const handleListConcepts = (projectRoot, params) => Effect.gen(function* () {
+	const ctx = yield* loadToolContext(projectRoot);
+	const declaredTypes = Object.keys(ctx.config.types ?? {}).toSorted();
+	const declaredTags = Object.keys(ctx.config.tags ?? {}).toSorted();
+	if (params.type !== void 0 && !declaredTypes.includes(params.type)) return yield* Effect.fail(unknown("type", params.type, declaredTypes));
+	const requestedTags = params.tags ?? [];
+	for (const tag of requestedTags) if (!declaredTags.includes(tag)) return yield* Effect.fail(unknown("tag", tag, declaredTags));
+	const filtered = [...ctx.bundle.concepts.values()].filter((concept) => {
+		if (params.type !== void 0 && concept.frontmatter.type !== params.type) return false;
+		const tags = concept.frontmatter.tags ?? [];
+		if (!requestedTags.every((tag) => tags.includes(tag))) return false;
+		if (params.status !== void 0 && Derive.status(concept.frontmatter) !== params.status) return false;
+		return true;
+	}).toSorted((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+	const limit = params.limit ?? 200;
+	const offset = params.offset ?? 0;
+	return {
+		items: filtered.slice(offset, offset + limit).map(toConceptSummary),
+		total: filtered.length
+	};
+});
+
+//#endregion
+export { handleListConcepts, listConcepts };

package/tools/staleReport.js

@@ -0,0 +1,53 @@
+import { McpToolError } from "../errors.js";
+import { loadToolContext } from "../internal/toolContext.js";
+import { toConceptSummary } from "../schema/ConceptSummary.js";
+import { StaleReportParams, StaleReportSuccess } from "../schema/tools.js";
+import { resolveNow } from "../internal/resolveNow.js";
+import { DateTime, Effect, FileSystem, Path } from "effect";
+import { Derive } from "@okfit/core";
+import { Tool } from "effect/unstable/ai";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/tools/staleReport.ts
+const DESCRIPTION = "Lists every concept whose stale_after instant has passed, each with its summary, the date, and how many whole days past it. Uses the current time by default; pass now as an ISO-8601 instant with an explicit offset to report staleness as of a different moment.";
+/**
+* `dependencies` mirrors the other tools' (Task B1's Deviation 1):
+* `loadToolContext` needs the same platform services, and without a
+* `dependencies` declaration `Tool.HandlerServices` infers `never`, failing
+* the handler record against `HandlersFrom` when passed to
+* `OkfitToolkit.toLayer`.
+*
+* @public
+*/
+const staleReport = Tool.make("stale_report", {
+	description: DESCRIPTION,
+	parameters: StaleReportParams,
+	success: StaleReportSuccess,
+	failure: McpToolError,
+	dependencies: [
+		FileSystem.FileSystem,
+		Path.Path,
+		AppDirs,
+		Xdg
+	]
+}).annotate(Tool.Title, "Stale concepts").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/** @public */
+const handleStaleReport = (projectRoot, params) => Effect.gen(function* () {
+	const ctx = yield* loadToolContext(projectRoot);
+	const now = yield* resolveNow(params.now);
+	const items = Derive.staleReport(ctx.bundle, now).flatMap((entry) => {
+		const concept = ctx.bundle.concepts.get(entry.id);
+		return concept === void 0 ? [] : [{
+			summary: toConceptSummary(concept),
+			stale_after: DateTime.formatIso(entry.staleAfter),
+			days_past: entry.daysPast
+		}];
+	});
+	return {
+		as_of: DateTime.formatIso(now),
+		items
+	};
+});
+
+//#endregion
+export { handleStaleReport, staleReport };

package/tools/validateBundle.js

@@ -0,0 +1,94 @@
+import { BundleNotFound, McpToolError, composeRemediatedMessage } from "../errors.js";
+import { resolveConfigOnly } from "../internal/toolContext.js";
+import { ValidateBundleParams } from "../schema/tools.js";
+import { resolveNow } from "../internal/resolveNow.js";
+import { MCP_VERSION } from "../version.js";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { OKF_SPEC_VERSION } from "@okfit/core";
+import { Tool } from "effect/unstable/ai";
+import { JsonEnvelope, collect, forDiagnostics, json, run } from "@okfit/engine";
+import { Git } from "@effected/git";
+import { GitHistory } from "@okfit/profiles";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/tools/validateBundle.ts
+const DESCRIPTION = "Runs the same conformance and lint checks as `okfit validate --format json` and returns that report unchanged: every diagnostic's file, code, severity, message and range, plus the summary counts and the exit code the CLI would use. Call it after writing or editing any concept file, before moving on to the next one.";
+/**
+* `dependencies` mirrors the other tools' (Task B1's Deviation 1):
+* `resolveConfigOnly` and `run()` need the same platform services, and
+* without a `dependencies` declaration `Tool.HandlerServices` infers
+* `never`, failing the handler record against `HandlersFrom` when passed to
+* `OkfitToolkit.toLayer`.
+*
+* `Git` and `GitHistory` are new in this list: B3 widened `run()`'s own
+* requirement channel to `FileSystem.FileSystem | Path.Path | Git |
+* GitHistory` so it can run `Provenance.lint`'s `generated-at-drift`
+* check (S-8, S-16). Both are provided by `server.ts`'s `ServerLayer`,
+* which needs only `ChildProcessSpawner` to build them — already
+* supplied by `@okfit/engine`'s `OkfitPlatform` (S-16).
+*
+* @public
+*/
+const validateBundle = Tool.make("validate_bundle", {
+	description: DESCRIPTION,
+	parameters: ValidateBundleParams,
+	success: JsonEnvelope,
+	failure: McpToolError,
+	dependencies: [
+		FileSystem.FileSystem,
+		Path.Path,
+		AppDirs,
+		Xdg,
+		Git,
+		GitHistory
+	]
+}).annotate(Tool.Title, "Validate the bundle").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/**
+* This tool does not call `loadToolContext`: `run()` calls `Bundle.load`
+* itself (`packages/engine/src/validate/run.ts:52-56`), so routing through
+* `loadToolContext` would load the bundle twice. It uses `resolveConfigOnly`
+* and keeps `bundleRoot`, `config` **and** `profile` — `run()` needs the
+* profile. `success` is `JsonEnvelope`, imported from `@okfit/engine` and used
+* verbatim (N-35's own carve-out: data reuse, not envelope reuse);
+* `JsonErrorEnvelope` is never returned — that is the CLI's stdout
+* convention for an exit-3 infrastructure failure, and here that failure is
+* a typed `McpToolError` instead, so `forDiagnostics`' `0 | 1 | 2` result is
+* always reachable. `okfitVersion` is `MCP_VERSION`, not `CLI_VERSION`
+* (J-2): the field names the package that produced the report.
+*
+* @public
+*/
+const handleValidateBundle = (projectRoot, params) => Effect.gen(function* () {
+	const resolved = yield* resolveConfigOnly(projectRoot);
+	const now = yield* resolveNow(params.now);
+	const result = yield* run({
+		root: resolved.bundleRoot,
+		config: resolved.config,
+		profile: resolved.profile,
+		now
+	}).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
+		});
+	}));
+	const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
+	const code = forDiagnostics(diagnostics);
+	return json({
+		okfitVersion: MCP_VERSION,
+		okfVersion: resolved.config.okf_version ?? OKF_SPEC_VERSION,
+		root: resolved.bundleRoot,
+		profile: Option.match(resolved.profile, {
+			onNone: () => null,
+			onSome: (profile) => profile.name
+		}),
+		exitCode: code,
+		concepts: result.bundle.concepts.size,
+		diagnostics
+	});
+});
+
+//#endregion
+export { handleValidateBundle, validateBundle };

package/version.js

@@ -0,0 +1,11 @@
+//#region src/version.ts
+/**
+* The version this server reports in `initialize`. Injected by
+* `@savvy-web/bundler` at build time (K-32); `"0.0.0"` in unbuilt source.
+*
+* @public
+*/
+const MCP_VERSION = "0.3.0";
+
+//#endregion
+export { MCP_VERSION };