@okfit/mcp 0.1.0 → 0.2.0

package/README.md

@@ -2,11 +2,72 @@
 
 Model Context Protocol server for [okfit](https://github.com/spencerbeggs/okfit). Gives agents structured access to an Open Knowledge Format bundle: concepts, types, tags, the link graph, and staleness.
 
-> **Part of the okfit kit.** Most users want **[@okfit/plugin](https://www.npmjs.com/package/@okfit/plugin)**, which pulls this package in automatically.
+> **Part of the okfit kit.** Most users want **[@okfit/plugin](https://www.npmjs.com/package/@okfit/plugin)**, which pulls this package in automatically and launches this server through the Claude Code plugin's `mcpServers.mcp` entry.
 
-## Status
+## What it is
 
-Skeleton. The `okfit-mcp` bin starts, reports that the server is not implemented, and exits 1.
+`@okfit/mcp` speaks MCP over stdio for one OKF bundle. It is read-only: no
+tool or resource ever writes to the bundle, the config, or anywhere else.
+`validate_bundle` spawns read-only `git log`/`git show` calls for one lint
+(`generated-at-drift`); a read is not a write, and the promise stands. Six
+tools cover orientation, discovery, and validation; the bundle index plus
+one resource per concept expose the bundle's own markdown to a client's
+@-mention UI.
+
+## Launching it
+
+Most users never invoke this directly — the Claude Code plugin's
+`bin/start-mcp.sh` loader resolves the project's own
+`node_modules/.bin/okfit-mcp` and falls back to `npx --yes @okfit/mcp` when
+it is not installed. To run it directly, the package's own bin is
+`okfit-mcp`.
+
+The server resolves its project root in this order:
+`OKFIT_PROJECT_DIR` → `CLAUDE_PROJECT_DIR` → the process's current working
+directory. No command-line flags are read. `OKFIT_PROJECT_DIR` selects
+where the CLI's own config discovery *starts*, not the project root
+outright — and under the CLI's per-directory resolver order an
+ancestor's `.okfit.toml` never beats a nearer directory's `okfit.toml`
+or `.config/okfit.toml`.
+
+## Tools
+
+| Tool | Returns |
+| --- | --- |
+| `describe_vocabulary` | The resolved project and bundle roots, active profile, agent actor, and the config's declared type and tag vocabulary. Call first, before filtering or writing anything. |
+| `list_concepts` | Concept summaries, optionally filtered by an exact type, by tags that must all be present, and by status; pages with `limit`/`offset` and reports the total match count. |
+| `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. |
+
+## Resources
+
+- `okf://index` — the bundle's root `index.md`, re-read from disk on every
+  call.
+- `okf://concept/<id>` — one **static** resource per concept loaded when
+  the server starts, one per concept in the bundle at that moment. Editing
+  an already-listed concept's file is picked up live on every read; a
+  concept added or removed after boot is not reflected in `resources/list`
+  until the server restarts. There is no URI template and no completion —
+  every concept resource is registered by its own literal URI. The listing
+  is one entry per concept and uncursored, sized for bundles of the scale
+  okfit targets today.
+
+## Errors
+
+A failing tool call reaches the client as `isError: true`, with the
+remediation text folded directly into the message — there is no separate
+structured error field on the wire. The five `McpToolError` members:
+
+- `ConfigError` — config discovery, parsing, or validation failed.
+- `BundleNotFound` — the configured bundle root does not exist or could
+  not be read.
+- `ConceptNotFound` — no concept in the bundle has the requested id.
+- `UnknownVocabulary` — a requested type or tag name is not declared in
+  the resolved config.
+- `InvalidArgument` — a tool argument was structurally acceptable but
+  semantically invalid.
 
 ## License
 

package/bin/okfit-mcp.js

@@ -1,14 +1,37 @@
 #!/usr/bin/env node
-import { NOT_IMPLEMENTED_EXIT_CODE, NOT_IMPLEMENTED_MESSAGE } from "../index.js";
-
 //#region src/bin.ts
 /**
-* MCP server entry point for okfit. Phase-1 stub.
+* MCP server entry point for okfit.
 *
 * @packageDocumentation
 */
-process.stderr.write(`${NOT_IMPLEMENTED_MESSAGE}\n`);
-process.exit(1);
+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);
+};
+process.on("uncaughtException", (error) => fatal("uncaught exception", error));
+process.on("unhandledRejection", (reason) => fatal("unhandled rejection", reason));
+await (async () => {
+	const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
+	const NodeServices = await import("@effect/platform-node/NodeServices");
+	const { AppDirs, Xdg } = await import("@effected/xdg");
+	const { Cause, Exit, Layer, Logger, Runtime } = await import("effect");
+	const { resolveMcpProjectRoot } = await import("../internal/projectRoot.js");
+	const { ServerLayer } = await import("../server.js");
+	const PlatformLayer = Layer.mergeAll(Xdg.layer, AppDirs.layer({ namespace: "okfit" }).pipe(Layer.provide(Xdg.layer))).pipe(Layer.provideMerge(NodeServices.layer));
+	const projectRoot = resolveMcpProjectRoot(process.env);
+	const program = Layer.launch(ServerLayer(projectRoot).pipe(Layer.provide(PlatformLayer), 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 {  };

package/errors.js

@@ -0,0 +1,105 @@
+import { Schema } from "effect";
+
+//#region src/errors.ts
+/** What a caller should do next about a failed tool call. @public */
+const Remediation = Schema.Struct({
+	hint: Schema.String,
+	suggestedTool: Schema.optionalKey(Schema.String)
+});
+/**
+* Compose a self-contained wire message from a raw cause message and its
+* remediation: the human message, then the hint, then `Try <suggestedTool>.`
+* when one is present. Every `McpToolError` member's `message` field is
+* built through this at construction — under `failureMode: "error"` (the
+* only mode this contract's tools use), `McpServer`'s own `registerToolkit`
+* collapses a caught typed failure to
+* `{ isError: true, content: [{ type: "text", text: error.message }] }`
+* and never surfaces `structuredContent` for it
+* (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1502-1506,1576-1584`,
+* confirmed empirically in Task B1's own build). `remediation` itself is
+* left on the schema unchanged, both for anything that inspects the typed
+* error directly (a defect handler, a future in-process caller) and
+* because it is what this function reads to build `message`.
+*
+* @public
+*/
+const composeRemediatedMessage = (message, remediation) => remediation.suggestedTool === void 0 ? `${message} ${remediation.hint}` : `${message} ${remediation.hint} Try ${remediation.suggestedTool}.`;
+const ECHO_LIMIT = 200;
+/**
+* Truncate a caller-supplied value before it is echoed back inside an
+* error's `message` — the only field a `failureMode: "error"` failure
+* actually delivers to the wire (see {@link composeRemediatedMessage}'s
+* doc comment). Without this, a pathological argument (a multi-megabyte
+* `id`, say) is echoed once in the response's `content[0].text` and once
+* more in the corresponding log line, wasting an agent's context on what
+* is usually a pure typo (final whole-branch review, Minor finding 5).
+*
+* @public
+*/
+const truncateEchoed = (value, limit = ECHO_LIMIT) => value.length > limit ? `${value.slice(0, limit)}…` : value;
+/**
+* Config discovery, parsing, or validation failed. `message` is composed
+* through {@link composeRemediatedMessage} at construction, so it is what
+* reaches the wire as `tools/call`'s `content[0].text` (see that
+* function's doc comment for why). @public
+*/
+var ConfigError = class extends Schema.TaggedError()("ConfigError", {
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* The configured bundle root does not exist or could not be read.
+* `message` is composed through {@link composeRemediatedMessage} at
+* construction, so it is what reaches the wire as `tools/call`'s
+* `content[0].text`. @public
+*/
+var BundleNotFound = class extends Schema.TaggedError()("BundleNotFound", {
+	root: Schema.String,
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* No concept in the bundle has the requested id. `message` is composed
+* through {@link composeRemediatedMessage} at construction, so it is what
+* reaches the wire as `tools/call`'s `content[0].text`. @public
+*/
+var ConceptNotFound = class extends Schema.TaggedError()("ConceptNotFound", {
+	id: Schema.String,
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* A requested type or tag name is not declared in the resolved config.
+* `message` is composed through {@link composeRemediatedMessage} at
+* construction, so it is what reaches the wire as `tools/call`'s
+* `content[0].text`. @public
+*/
+var UnknownVocabulary = class extends Schema.TaggedError()("UnknownVocabulary", {
+	kind: Schema.Literals(["type", "tag"]),
+	requested: Schema.String,
+	valid: Schema.Array(Schema.String),
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* A tool argument was structurally acceptable but semantically invalid.
+* `message` is composed through {@link composeRemediatedMessage} at
+* construction, so it is what reaches the wire as `tools/call`'s
+* `content[0].text`. @public
+*/
+var InvalidArgument = class extends Schema.TaggedError()("InvalidArgument", {
+	argument: Schema.String,
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/** The one failure schema every tool declares (N-14). @public */
+const McpToolError = Schema.Union([
+	ConfigError,
+	BundleNotFound,
+	ConceptNotFound,
+	UnknownVocabulary,
+	InvalidArgument
+]);
+
+//#endregion
+export { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary, composeRemediatedMessage, truncateEchoed };