@okfit/mcp 0.4.2 → 0.5.0

package/errors.js

@@ -15,8 +15,12 @@ const Remediation = Schema.Struct({
 * 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
+* (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1774-1778,1842-1846`
+* at effect@4.0.0-rc.116: `toolErrorResult` and `declaredFailureResult`'s
+* `error instanceof Error` branch; confirmed empirically in Task B1's own
+* build). Since rc.116 that declared branch is rendered WITHOUT a log line
+* — only an internal failure goes through `Effect.logError` — so the
+* message text is the whole of what a client ever sees. `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`.

package/index.d.ts

@@ -21,8 +21,12 @@ export type Remediation = typeof Remediation.Type;
  * 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
+ * (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1774-1778,1842-1846`
+ * at effect@4.0.0-rc.116: `toolErrorResult` and `declaredFailureResult`'s
+ * `error instanceof Error` branch; confirmed empirically in Task B1's own
+ * build). Since rc.116 that declared branch is rendered WITHOUT a log line
+ * — only an internal failure goes through `Effect.logError` — so the
+ * message text is the whole of what a client ever sees. `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`.
@@ -392,20 +396,39 @@ type PlatformServices = FileSystem.FileSystem | Path.Path | AppDirs | Xdg | Stdi
 interface ServerOptions {
   readonly distribution?: Distribution;
 }
+/**
+ * Agent-facing orientation, surfaced verbatim as `instructions` in both the
+ * `initialize` result (2025-11-25 / 2025-06-18) and the `server/discover`
+ * result (2026-07-28). `description` on the server identity stays the
+ * one-line human summary; this is the paragraph an agent reads before its
+ * first call. Exported so tests can assert identity rather than a
+ * substring.
+ *
+ * @public
+ */
+export declare const SERVER_INSTRUCTIONS: string;
 /**
  * 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.
+ * `protocols` ships three adapters, newest first. `McpProtocol.v2026_07_28`
+ * is the stateless adapter (SEP-2575): no `initialize`, no session, every
+ * request self-identifies through `params._meta`, and the client discovers
+ * the server with `server/discover`. The two stateful adapters stay
+ * because `initialize` matches stateful adapters only — a client that
+ * opens with `initialize` (Claude Code by default, Copilot, Cursor, the
+ * Inspector) would otherwise get `METHOD_NOT_FOUND`. Array order is
+ * load-bearing: a request with no session and no `_meta` protocol version
+ * falls to `protocols[0]`, and `server/discover` advertises every listed
+ * adapter in `supportedVersions`. The runtime allows at most one stateless
+ * adapter; a second fails the layer with `Cause.IllegalArgumentError`.
+ * 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.
+ * unhandled: `protocols` is a static literal, so it is an implementer-time
+ * defect, not a runtime condition.
  *
  * @public
  */

package/index.js

@@ -5,6 +5,6 @@ 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";
+import { SERVER_INSTRUCTIONS, ServerLayer } from "./server.js";
 
-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 };
+export { BundleNotFound, ConceptNeighborsSuccess, ConceptNotFound, ConceptResources, ConceptSummary, ConfigError, DescribeVocabularySuccess, GetConceptSuccess, IndexResource, InvalidArgument, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, UnknownVocabulary, ValidateBundleParams, composeRemediatedMessage, toConceptSummary, truncateEchoed };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/mcp",
-	"version": "0.4.2",
+	"version": "0.5.0",
 	"private": false,
 	"description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
 	"keywords": [
@@ -44,13 +44,13 @@
 		"okfit-mcp": "bin/okfit-mcp.js"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.115",
-		"@effected/git": "^0.15.2",
-		"@effected/xdg": "^0.5.3",
-		"@okfit/core": "0.7.1",
-		"@okfit/engine": "0.7.2",
-		"@okfit/profiles": "0.7.3",
-		"effect": "4.0.0-rc.115"
+		"@effect/platform-node": "4.0.0-rc.116",
+		"@effected/git": "^0.16.0",
+		"@effected/xdg": "^0.6.0",
+		"@okfit/core": "0.7.2",
+		"@okfit/engine": "0.7.3",
+		"@okfit/profiles": "0.7.4",
+		"effect": "4.0.0-rc.116"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/server.js

@@ -9,27 +9,61 @@ import { GitHistory } from "@okfit/profiles";
 
 //#region src/server.ts
 /**
+* Agent-facing orientation, surfaced verbatim as `instructions` in both the
+* `initialize` result (2025-11-25 / 2025-06-18) and the `server/discover`
+* result (2026-07-28). `description` on the server identity stays the
+* one-line human summary; this is the paragraph an agent reads before its
+* first call. Exported so tests can assert identity rather than a
+* substring.
+*
+* @public
+*/
+const SERVER_INSTRUCTIONS = [
+	"okfit-mcp serves one Open Knowledge Format (OKF) bundle: the okf/ directory of the project it was launched in.",
+	"Every tool is read-only and answers from the bundle as it is on disk at call time.",
+	"Start with describe_vocabulary to learn the concept types and tags this project's config declares, then",
+	"list_concepts to find ids; get_concept, concept_neighbors, stale_report and validate_bundle take those ids.",
+	"Concept ids are bundle-relative paths without the .md extension (for example decisions/cli-exit-codes).",
+	"Every successful tools/call result carries the typed payload in structuredContent and a JSON rendering in",
+	"content[0].text. A failed call is isError: true with the human message and a remediation hint in",
+	"content[0].text and no structuredContent; read that text before retrying.",
+	"Resources: okf://index is the bundle's root index.md, and okf://concept/<id> is one static resource per concept."
+].join(" ");
+/**
 * 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.
+* `protocols` ships three adapters, newest first. `McpProtocol.v2026_07_28`
+* is the stateless adapter (SEP-2575): no `initialize`, no session, every
+* request self-identifies through `params._meta`, and the client discovers
+* the server with `server/discover`. The two stateful adapters stay
+* because `initialize` matches stateful adapters only — a client that
+* opens with `initialize` (Claude Code by default, Copilot, Cursor, the
+* Inspector) would otherwise get `METHOD_NOT_FOUND`. Array order is
+* load-bearing: a request with no session and no `_meta` protocol version
+* falls to `protocols[0]`, and `server/discover` advertises every listed
+* adapter in `supportedVersions`. The runtime allows at most one stateless
+* adapter; a second fails the layer with `Cause.IllegalArgumentError`.
+* 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.
+* unhandled: `protocols` is a static literal, so it is an implementer-time
+* defect, not a runtime condition.
 *
 * @public
 */
 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]
+	instructions: SERVER_INSTRUCTIONS,
+	protocols: [
+		McpProtocol.v2026_07_28,
+		McpProtocol.v2025_11_25,
+		McpProtocol.v2025_06_18
+	]
 })), Layer.orDie);
 
 //#endregion
-export { ServerLayer };
+export { SERVER_INSTRUCTIONS, ServerLayer };

package/version.js

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