@nexusbloom/mcp-server 2.1.2 → 2.2.0

package/index.js

@@ -19,6 +19,9 @@
  * stdout is the MCP transport. All diagnostics go to stderr.
  */
 
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 import { ApiClient } from "./src/client.js";
@@ -85,8 +88,25 @@ export async function main(env = process.env, deps = {}) {
 
 // Only run when executed directly, so importing this module in a test does not
 // hijack stdio.
-const invokedDirectly =
-  process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+//
+// Both sides have to be normalised, and both mistakes here are silent:
+//   - `npx @nexusbloom/mcp-server` launches the `.bin/nexusbloom-mcp` symlink,
+//     so `process.argv[1]` is the symlink path while the ESM loader resolves
+//     `import.meta.url` to the real one. Comparing them raw reports "not
+//     invoked directly", the server never starts, and the process exits 0 with
+//     no output — a host just reports "no tools".
+//   - `import.meta.url` is percent-encoded, so a path containing a space or
+//     `#` never string-matches the raw `process.argv[1]`.
+// `pathToFileURL(realpathSync(argv[1]))` puts both sides in the same form.
+const invokedDirectly = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    return false;
+  }
+})();
 
 if (invokedDirectly) {
   main().catch((err) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.1.2",
-  "description": "MCP server for NexusBloom \u2014 agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
+  "version": "2.2.0",
+  "description": "MCP server for NexusBloom — agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -28,7 +28,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.8.0",
-    "@nexusbloom/core": "^1.0.0"
+    "@nexusbloom/core": "^1.2.0"
   },
   "scripts": {
     "test": "node --test --import ./test/setup.mjs test/*.test.js",

package/src/manifests.js

@@ -7,8 +7,42 @@
  * not. Everything downstream should be able to assume one shape.
  */
 
+import * as coreContract from "@nexusbloom/core";
 import { NexusBloomError, ErrorCode } from "./errors.js";
 
+/**
+ * The surface contract lives in `@nexusbloom/core` as of 1.2.0, but this package
+ * is consumed as `npx -y @nexusbloom/mcp-server`, which resolves its dependency
+ * fresh at install time. A static named import of a symbol the resolved core
+ * does not have is a *link* error, so the whole server would fail to start and
+ * an agent would get no tools at all — the worst failure this package can have,
+ * and one that depends on a publish order nobody controls.
+ *
+ * A namespace import cannot fail that way: a missing export is `undefined`
+ * rather than a crash. So the contract degrades to "nothing declared, nothing
+ * known" — the conservative reading — instead of taking the server down. Once
+ * core 1.2.0 is on the registry this resolves to the real implementation and the
+ * guard simply never fires.
+ */
+const readContract = typeof coreContract.readContract === "function" ? coreContract.readContract : null;
+
+const collectUnknownKeys =
+  typeof coreContract.collectUnknownKeys === "function" ? coreContract.collectUnknownKeys : () => [];
+
+/** The shape `readContractFields` returns when no core contract is available. */
+function emptyContractFields() {
+  return {
+    coreContract: null,
+    extensionContract: null,
+    side_effects: ["none"],
+    trust: "unverified",
+    surfaces: {},
+    unknownSideEffects: [],
+    contractIssues: [],
+    unknownManifestKeys: [],
+  };
+}
+
 /** Empty but valid — a schema saying "takes nothing" is not the same as null. */
 export function emptyInputSchema() {
   return { type: "object", properties: {}, required: [] };
@@ -111,6 +145,49 @@ export function normaliseTool(raw) {
     // object — but an agent needs to know which one it is, because the first
     // means call `schema` before trying and the second means just call it.
     hasSchema: isSchemaPresent(raw.input_schema),
+
+    // ── Surface contract ────────────────────────────────────────────────────
+    // Everything below is additive and read-only. Nothing above changed shape,
+    // so a consumer that ignores these fields behaves exactly as before.
+    //
+    // The important property is that `surfaces` is *carried*, not filtered.
+    // This function used to be a closed whitelist: any key it did not name was
+    // dropped on the floor, which made per-surface customisation impossible to
+    // ship — an author's `mcp.agentHints` or `website.view` would vanish here
+    // with no error, and the only symptom would be a tool that looks correct in
+    // its own manifest and does nothing on the surface that asked for it.
+    // Preserving the block and reporting what we could not validate makes that
+    // failure mode impossible to hide.
+    ...readContractFields(raw),
+  };
+}
+
+/**
+ * Project the surface contract off a raw manifest row.
+ *
+ * Split out from `normaliseTool` so the projection can be tested on its own and
+ * reused by any surface that normalises a manifest the same way.
+ *
+ * @param {object} raw
+ * @returns {{coreContract: number|null, extensionContract: number|null,
+ *   side_effects: string[], trust: string, surfaces: object,
+ *   unknownSideEffects: string[], contractIssues: object[],
+ *   unknownManifestKeys: string[]}}
+ */
+export function readContractFields(raw) {
+  if (!readContract) return emptyContractFields();
+  const contract = readContract(raw);
+  return {
+    coreContract: contract.coreContract,
+    extensionContract: contract.extensionContract,
+    side_effects: contract.sideEffects.declared,
+    trust: contract.trust,
+    surfaces: contract.surfaces,
+    // Split out from `side_effects` so a consumer gating on capability does not
+    // have to re-derive which entries were recognised.
+    unknownSideEffects: contract.sideEffects.unknown,
+    contractIssues: contract.issues,
+    unknownManifestKeys: collectUnknownKeys(raw),
   };
 }