zerno-mcp 0.1.2 → 0.1.5

package/README.md

@@ -1,13 +1,37 @@
 # zerno-mcp
 
-Local stdio MCP server for ZERNO code-agent integrations.
+MCP server for ZERNO code-agent integrations.
 
-## Usage
+ZERNO gives AI coding agents project-scoped product context: backlog tasks,
+stage, execution policy, product memory, checkpoints, and run telemetry.
+
+## Hosted server
+
+Use the hosted Streamable HTTP endpoint when your client supports remote MCP:
+
+```text
+https://zerno.one/mcp
+```
+
+Authentication uses OAuth with PKCE. The public discovery documents are:
+
+```text
+https://zerno.one/.well-known/mcp
+https://zerno.one/.well-known/oauth-protected-resource/mcp
+https://zerno.one/.well-known/oauth-authorization-server
+```
+
+The OAuth scope is `mcp`. Tokens are project-scoped and grant only ZERNO MCP
+permissions: read project context/tasks/memory, write task status, plans,
+reports, checkpoints, memory notes, intake tasks, and agent run telemetry.
+They do not grant repository, filesystem, shell, or source-code access.
+
+## Local stdio server
 
 Recommended setup:
 
 ```bash
-npx -y zerno-mcp@0.1.2 setup
+npx -y zerno-mcp@0.1.5 setup
 ```
 
 The setup command opens ZERNO in the browser, lets the user choose a project,
@@ -16,7 +40,7 @@ creates the project-scoped MCP token, and writes local agent configs.
 Agent runtime:
 
 ```bash
-npx -y zerno-mcp@0.1.2
+npx -y zerno-mcp@0.1.5
 ```
 
 Required environment:
@@ -26,3 +50,118 @@ ZERNO_API_URL=https://zerno.one
 ZERNO_API_TOKEN=<project-token>
 ZERNO_PROJECT_ID=<project-id>
 ```
+
+For local stdio, `ZERNO_PROJECT_ID` may also come from a non-secret repository
+binding file:
+
+```json
+{
+  "project_id": "<project-id>",
+  "workspace_id": "<workspace-id>",
+  "origin": "git@github.com:org/repo.git"
+}
+```
+
+Place it at `.zerno/project.json`. Environment variables still win, so CI and
+manual project-scoped setups remain deterministic.
+
+## Client examples
+
+Codex remote MCP:
+
+```bash
+codex mcp add zerno --url https://zerno.one/mcp
+codex mcp login zerno --scopes mcp
+```
+
+Claude Code remote MCP:
+
+```bash
+claude mcp add --transport http zerno https://zerno.one/mcp
+```
+
+Then run `/mcp` inside Claude Code to complete OAuth and confirm that ZERNO
+shows connected with tools available.
+
+Claude Desktop local stdio:
+
+```json
+{
+  "mcpServers": {
+    "zerno": {
+      "command": "npx",
+      "args": ["-y", "zerno-mcp@0.1.5"],
+      "env": {
+        "ZERNO_API_URL": "https://zerno.one",
+        "ZERNO_API_TOKEN": "<project-token>",
+        "ZERNO_PROJECT_ID": "<project-id>"
+      }
+    }
+  }
+}
+```
+
+Cursor local stdio uses the same `mcpServers.zerno` block in `.mcp.json`.
+
+OpenCode local stdio:
+
+```json
+{
+  "mcp": {
+    "zerno": {
+      "type": "local",
+      "command": ["npx", "-y", "zerno-mcp@0.1.5"],
+      "enabled": true,
+      "environment": {
+        "ZERNO_API_URL": "https://zerno.one",
+        "ZERNO_API_TOKEN": "<project-token>",
+        "ZERNO_PROJECT_ID": "<project-id>"
+      }
+    }
+  }
+}
+```
+
+## Main tools
+
+- `zerno_get_project_context`
+- `zerno_list_tasks`
+- `zerno_get_task`
+- `zerno_resume_task`
+- `zerno_checkpoint`
+- `zerno_update_task_status`
+- `zerno_memory_snapshot`
+- `zerno_run_start`
+
+## Compatibility notes
+
+- Remote transport: Streamable HTTP at `/mcp`.
+- Local transport: stdio via the official MCP TypeScript SDK.
+- Server instructions are returned during initialization so Claude Code Tool
+  Search can decide when ZERNO tools are relevant.
+- Tool text output is capped to keep Claude Code and Codex context usage
+  predictable. Full structured data remains available in `structuredContent`
+  on the hosted HTTP transport.
+- The local stdio runtime does not write logs to stdout.
+
+## Verification
+
+```bash
+npm run build
+npm pack --dry-run
+```
+
+For the hosted endpoint:
+
+```bash
+curl -i https://zerno.one/.well-known/mcp
+curl -i https://zerno.one/.well-known/oauth-protected-resource/mcp
+curl -i -X POST https://zerno.one/mcp \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+```
+
+## Registry metadata
+
+The MCP Registry server name is `io.github.zernozerno/zerno-mcp`.
+Package verification is declared with `mcpName` in `package.json`.

package/dist/index.js

@@ -22,7 +22,12 @@ if (process.argv[2] === "setup") {
     process.exit(0);
 }
 const client = await import("./zerno-client.js");
-const server = new Server({ name: "zerno-mcp", version: "0.1.2" }, { capabilities: { tools: {} } });
+const SERVER_INSTRUCTIONS = "ZERNO provides project-scoped product context for coding agents: backlog tasks, stage, execution policy, product memory, checkpoints, and run telemetry. Use these tools when the user asks to work from ZERNO tasks, inspect backlog/product context, resume prior agent work, record checkpoints, or report task progress. ZERNO never grants repository, filesystem, shell, or source-code access.";
+const MAX_TEXT_CHARS = 12000;
+const server = new Server({ name: "zerno-mcp", version: "0.1.5" }, {
+    capabilities: { tools: {} },
+    instructions: SERVER_INSTRUCTIONS,
+});
 function asRecord(value) {
     if (value && typeof value === "object") {
         return value;
@@ -42,6 +47,12 @@ function asTaskList(value) {
     const items = rec.tasks ?? rec.items ?? rec.results;
     return Array.isArray(items) ? items : [];
 }
+function capText(value) {
+    if (value.length <= MAX_TEXT_CHARS)
+        return value;
+    const suffix = `\n\n[truncated: ${value.length - MAX_TEXT_CHARS} chars omitted]`;
+    return `${value.slice(0, Math.max(0, MAX_TEXT_CHARS - suffix.length))}${suffix}`;
+}
 function renderForTool(name, args, result) {
     switch (name) {
         case "zerno_get_task":
@@ -812,7 +823,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 throw new Error(`Unknown tool: ${name}`);
         }
         const rendered = renderForTool(name, (args ?? {}), result);
-        const fallbackJson = JSON.stringify(result, null, 2);
+        const fallbackJson = capText(JSON.stringify(result, null, 2));
         const content = [];
         if (rendered?.html) {
             content.push({
@@ -828,10 +839,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             });
         }
         if (rendered?.markdown) {
-            content.push({ type: "text", text: rendered.markdown });
+            content.push({ type: "text", text: capText(rendered.markdown) });
         }
         content.push({ type: "text", text: fallbackJson });
-        return { content };
+        return { content, _meta: { "anthropic/maxResultSizeChars": MAX_TEXT_CHARS } };
     }
     catch (err) {
         return {

package/dist/setup.js

@@ -5,7 +5,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 const DEFAULT_API_URL = "https://zerno.one";
-const PACKAGE_SPEC = "zerno-mcp@0.1.2";
+const PACKAGE_SPEC = "zerno-mcp@0.1.5";
 const MANAGED_START = "# ZERNO MCP:START";
 const MANAGED_END = "# ZERNO MCP:END";
 function argValue(args, name) {
@@ -130,10 +130,26 @@ async function oauthConnect(apiUrl) {
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: form.toString(),
     });
+    if (!token.access_token) {
+        throw new Error("OAuth token response missing access_token");
+    }
+    if (!token.project_id) {
+        throw new Error("OAuth token response missing project_id — backend likely on an old build. Re-run setup against the updated server.");
+    }
     return { token: token.access_token, projectId: token.project_id };
 }
 function runtimeEnv(apiUrl, rawToken, projectId) {
-    return { ZERNO_API_URL: apiUrl, ZERNO_API_TOKEN: rawToken, ZERNO_PROJECT_ID: projectId };
+    const env = {
+        ZERNO_API_URL: apiUrl,
+        ZERNO_API_TOKEN: rawToken,
+        ZERNO_PROJECT_ID: projectId,
+    };
+    for (const [key, value] of Object.entries(env)) {
+        if (!value || typeof value !== "string") {
+            throw new Error(`Refusing to write config: env value for ${key} is empty`);
+        }
+    }
+    return env;
 }
 function writeJson(filePath, value) {
     mkdirSync(dirname(filePath), { recursive: true });
@@ -155,6 +171,9 @@ function readJson(filePath) {
     return JSON.parse(stripJsonComments(readFileSync(filePath, "utf8")));
 }
 function quoteToml(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Cannot serialise empty value to TOML string`);
+    }
     return JSON.stringify(value);
 }
 function codexConfigPath() {
@@ -221,17 +240,22 @@ function writeClaudeCode(env) {
 export async function runSetup(args) {
     if (args.includes("--help") || args.includes("-h")) {
         console.log([
-            "Usage: npx -y zerno-mcp@0.1.2 setup [--api-url https://zerno.one]",
+            "Usage: npx -y zerno-mcp@0.1.5 setup [--api-url https://zerno.one]",
             "",
             "Opens the hosted ZERNO OAuth consent screen, lets the user choose a project,",
-            "and writes local Codex, Claude Desktop, and OpenCode MCP configs.",
+            "and writes local Codex, Claude Desktop, Claude Code, and OpenCode MCP configs.",
         ].join("\n"));
         return;
     }
     const apiUrl = argValue(args, "--api-url") || DEFAULT_API_URL;
     const auth = await oauthConnect(apiUrl);
     const env = runtimeEnv(apiUrl, auth.token, auth.projectId);
-    const written = [["Codex", writeCodex(env)], ["Claude Desktop", writeClaude(env)], ["OpenCode", writeOpenCode(env)]];
+    const written = [
+        ["Codex", writeCodex(env)],
+        ["Claude Desktop", writeClaude(env)],
+        ["Claude Code", writeClaudeCode(env)],
+        ["OpenCode", writeOpenCode(env)],
+    ];
     console.log("\nZERNO MCP is configured.");
     for (const [client, filePath] of written)
         console.log(`- ${client}: ${filePath}`);

package/dist/zerno-client.js

@@ -21,22 +21,38 @@ function readKey(jsonLike, key) {
     const rx = new RegExp(`"${key}"\\s*:\\s*"([^"]+)"`);
     return jsonLike.match(rx)?.[1] ?? "";
 }
-function readLocalFallbackConfig() {
-    const opencodePath = findUp("opencode.jsonc");
-    const zernoConfigPath = findUp(".zerno/config.json");
-    const opencodeText = opencodePath ? readFileSync(opencodePath, "utf8") : "";
-    const zernoConfigText = zernoConfigPath ? readFileSync(zernoConfigPath, "utf8") : "";
-    let zernoConfigProjectId = "";
+function readJsonFile(path) {
+    if (!path)
+        return {};
     try {
-        zernoConfigProjectId = zernoConfigText ? JSON.parse(zernoConfigText).projectId ?? "" : "";
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
     }
     catch {
-        zernoConfigProjectId = "";
+        return {};
+    }
+}
+function readStringField(obj, ...keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
     }
+    return "";
+}
+function readLocalFallbackConfig() {
+    const opencodePath = findUp("opencode.jsonc");
+    const zernoConfigPath = findUp(".zerno/config.json");
+    const zernoProjectPath = findUp(".zerno/project.json");
+    const opencodeText = opencodePath ? readFileSync(opencodePath, "utf8") : "";
+    const zernoConfig = readJsonFile(zernoConfigPath);
+    const zernoProject = readJsonFile(zernoProjectPath);
     return {
         apiUrl: readKey(opencodeText, "ZERNO_API_URL"),
         apiToken: readKey(opencodeText, "ZERNO_API_TOKEN"),
-        projectId: readKey(opencodeText, "ZERNO_PROJECT_ID") || zernoConfigProjectId,
+        projectId: readKey(opencodeText, "ZERNO_PROJECT_ID") ||
+            readStringField(zernoProject, "project_id", "projectId") ||
+            readStringField(zernoConfig, "project_id", "projectId"),
         connectionId: readKey(opencodeText, "ZERNO_CONNECTION_ID"),
     };
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "zerno-mcp",
-  "version": "0.1.2",
+  "version": "0.1.5",
+  "mcpName": "io.github.zernozerno/zerno-mcp",
   "description": "MCP server connecting OpenCode to ZERNO cloud product brain",
   "type": "module",
   "main": "dist/index.js",
@@ -9,8 +10,18 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "server.json"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zernozerno/betboard-console.git",
+    "directory": "packages/zerno-mcp"
+  },
+  "homepage": "https://zerno.one",
+  "bugs": {
+    "url": "https://github.com/zernozerno/betboard-console/issues"
+  },
   "publishConfig": {
     "access": "public"
   },

package/server.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.zernozerno/zerno-mcp",
+  "title": "ZERNO",
+  "description": "Project backlog, memory, and execution context for AI coding agents.",
+  "version": "0.1.5",
+  "websiteUrl": "https://zerno.one",
+  "repository": {
+    "url": "https://github.com/zernozerno/betboard-console",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://zerno.one/mcp"
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "zerno-mcp",
+      "version": "0.1.5",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}