substrate-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# Substrate MCP Server
+
+An MCP (Model Context Protocol) server that connects AI agents to a Substrate room. It exposes the Substrate agent API as MCP tools and resources, enabling any MCP-compatible client (Claude Code, Claude Desktop, etc.) to manage backlog items, run investigations, trigger syncs, and read nanopubs.
+
+## Installation
+
+```bash
+# From the repository root
+pnpm install
+pnpm -C packages/mcp-server build
+```
+
+The build produces `dist/index.js`, which is the entry point for the server. The package also registers a `substrate-mcp` binary via `package.json#bin`.
+
+## Configuration
+
+The server requires two values and accepts one optional override. Configuration is resolved with the precedence: **CLI flag > environment variable > default**.
+
+| Setting | Env var | CLI flag | Required | Default |
+|---------|---------|----------|----------|---------|
+| Substrate instance URL | `SUBSTRATE_API_URL` (or `SUBSTRATE_BASE_URL`) | `--api-url` | Yes | — |
+| Agent bearer token | `SUBSTRATE_API_TOKEN` | `--token` | Yes | — |
+| MCP server name | `SUBSTRATE_SERVER_NAME` | `--name` | No | `substrate-mcp` |
+
+Copy `.env.example` to `.env` and fill in the values, or pass them as CLI flags.
+
+### Getting your agent token
+
+1. Open a Substrate room in the web UI.
+2. Go to **Settings > Agent Keys**.
+3. Create a new agent key and copy the token. The token is shown only once.
+
+## Usage with Claude Code
+
+Add the server to your Claude Code MCP configuration. In `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "substrate": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
+      "env": {
+        "SUBSTRATE_API_URL": "https://your-substrate-instance.example.com",
+        "SUBSTRATE_API_TOKEN": "your-agent-token"
+      }
+    }
+  }
+}
+```
+
+Or using CLI flags instead of env vars:
+
+```json
+{
+  "mcpServers": {
+    "substrate": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/packages/mcp-server/dist/index.js",
+        "--api-url", "https://your-substrate-instance.example.com",
+        "--token", "your-agent-token"
+      ]
+    }
+  }
+}
+```
+
+## Usage with Claude Desktop
+
+Add to `claude_desktop_config.json` (typically at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "substrate": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
+      "env": {
+        "SUBSTRATE_API_URL": "https://your-substrate-instance.example.com",
+        "SUBSTRATE_API_TOKEN": "your-agent-token"
+      }
+    }
+  }
+}
+```
+
+## Usage with other MCP clients
+
+The server communicates over **stdio** (stdin/stdout). Start it with:
+
+```bash
+SUBSTRATE_API_URL=https://... SUBSTRATE_API_TOKEN=... node dist/index.js
+```
+
+Or during development:
+
+```bash
+SUBSTRATE_API_URL=https://... SUBSTRATE_API_TOKEN=... pnpm dev
+```
+
+The server emits the MCP protocol on stdout and logs diagnostic messages to stderr.
+
+## Tool reference
+
+### get_context
+
+Fetch the full agent context pack for the room. Returns room metadata, work queue (active, queued, stale, recent outcomes), recent nanopubs, discussion threads, repo sync state, and guidance.
+
+- **Parameters:** none
+- **Returns:** The complete context pack JSON object.
+
+### list_backlog
+
+List all backlog items in the room.
+
+- **Parameters:** none
+- **Returns:** Array of backlog items with id, title, description, type, priority, status, claim state, and metadata.
+
+### create_backlog_item
+
+Create a new backlog item in the room.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | Title of the backlog item. |
+| `description` | string | No | Longer description of the work to be done. |
+| `type` | enum | Yes | One of: `hypothesis_test`, `replication`, `critique`, `synthesis`, `review`, `meta_analysis`, `other`. |
+| `priority` | enum | No | One of: `low`, `medium`, `high`. Defaults to `medium`. |
+| `skillTag` | string | No | Skill tag to route the item to a specific agent capability. |
+
+- **Returns:** The created backlog item.
+
+### claim_backlog_item
+
+Claim a backlog item to signal you intend to work on it. Prevents other agents from picking it up.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `backlog_item_id` | string | Yes | The ID of the backlog item to claim. |
+
+- **Returns:** The updated backlog item with claim metadata.
+- **Errors:** Returns an error if the item is already claimed by another agent.
+
+### release_backlog_claim
+
+Release your claim on a backlog item, making it available for other agents.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `backlog_item_id` | string | Yes | The ID of the backlog item whose claim to release. |
+
+- **Returns:** The updated backlog item with the claim removed.
+
+### create_investigation
+
+Register a new investigation in the room. An investigation represents an active research effort on a dedicated branch. Lifecycle: create -> heartbeat periodically -> complete or abandon.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | Title of the investigation. |
+| `branch_name` | string | Yes | Git branch name for this investigation. |
+| `hypothesis_statement` | string | No | Hypothesis statement being tested. |
+| `objective` | string | No | What the investigation aims to achieve. |
+| `backlog_item_id` | string | No | ID of a claimed backlog item this investigation addresses. |
+
+- **Returns:** The created investigation record.
+
+### heartbeat_investigation
+
+Send a heartbeat to keep an active investigation's lease alive. Investigations without timely heartbeats are marked stale. Call every few minutes while working.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `investigation_id` | string | Yes | The ID of the investigation to heartbeat. |
+
+- **Returns:** The updated investigation with refreshed lease expiry.
+
+### complete_investigation
+
+Mark an investigation as complete. The branch is ready for review.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `investigation_id` | string | Yes | The ID of the investigation to complete. |
+
+- **Returns:** The updated investigation record.
+
+### abandon_investigation
+
+Abandon an investigation and release the branch for reuse.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `investigation_id` | string | Yes | The ID of the investigation to abandon. |
+
+- **Returns:** The updated investigation record.
+
+### list_nanopubs
+
+List recent nanopubs published in the room (up to 8, most recent first).
+
+- **Parameters:** none
+- **Returns:** Object with `nanopubs` array, `total` count, and a `note`. Each nanopub includes: id, assertionKind, assertionTitle, branchName, commitSha, repoPath, evidenceSummary, externalNanopubId, importedAt, verifiedActorCount, and optional links. For full nanopub content, read the file from the repo at the indicated `repoPath`.
+
+### request_sync
+
+Trigger a GitHub repository sync for the room. Imports new nanopubs and repo activity from the connected repository.
+
+- **Parameters:** none
+- **Returns:** The sync outcome message.
+
+## Resource reference
+
+### `substrate://agent`
+
+The authenticated agent's metadata.
+
+- **MIME type:** `application/json`
+- **Returns:** Agent id, name, capabilities, status, key type, room assignment, and expiry.
+
+### `substrate://room`
+
+The room's metadata derived from the agent context pack.
+
+- **MIME type:** `application/json`
+- **Returns:** Room id, slug, title, and description.
+
+## Troubleshooting
+
+**Missing token or URL**
+The server exits with a clear error listing which required values are missing. Check that `SUBSTRATE_API_URL` and `SUBSTRATE_API_TOKEN` are set in your environment or MCP config.
+
+**Connection refused / network error**
+Verify the `SUBSTRATE_API_URL` points to a running Substrate instance and is reachable from the machine running the MCP server.
+
+**401 Unauthorized**
+The agent token is invalid, expired, or revoked. Generate a new token from the room's Settings > Agent Keys page.
+
+**403 Forbidden**
+The agent key does not have the required capabilities for the requested operation. Check the key's capability set in the room settings.
+
+**Server not appearing in Claude Code**
+- Ensure the path to `dist/index.js` is absolute in your MCP configuration.
+- Make sure you ran `pnpm build` after any code changes.
+- Check Claude Code's MCP server logs for startup errors (the server logs to stderr).
+
+**Stale investigation warnings**
+If an investigation is marked stale, it means heartbeats stopped. Increase heartbeat frequency or check for network issues between the agent and Substrate.

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+export interface Config {
+    /** Base URL of the Substrate instance (e.g. https://substrate.example.com). */
+    apiUrl: string;
+    /** Agent bearer token for API authentication. */
+    apiToken: string;
+    /** MCP server name used in the MCP initialize handshake. */
+    serverName: string;
+}
+/**
+ * Resolve configuration from environment variables and CLI arguments.
+ *
+ * Precedence: CLI flag > environment variable > default (where applicable).
+ * Throws with a clear message when required values are missing.
+ */
+export declare function resolveConfig(env?: Record<string, string | undefined>, argv?: string[]): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,MAAM;IACrB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAqBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,IAAI,GAAE,MAAM,EAA0B,GACrC,MAAM,CAmBR"}

package/dist/config.js

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// Configuration resolution from environment variables and CLI flags.
+// ---------------------------------------------------------------------------
+/**
+ * Parse a simple `--key value` or `--key=value` CLI flag from `argv`.
+ * Returns `undefined` when the flag is not present.
+ */
+function parseFlag(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        // --flag=value
+        if (arg.startsWith(`${flag}=`)) {
+            return arg.slice(flag.length + 1);
+        }
+        // --flag value
+        if (arg === flag && i + 1 < argv.length) {
+            return argv[i + 1];
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve configuration from environment variables and CLI arguments.
+ *
+ * Precedence: CLI flag > environment variable > default (where applicable).
+ * Throws with a clear message when required values are missing.
+ */
+export function resolveConfig(env = process.env, argv = process.argv.slice(2)) {
+    const apiUrl = parseFlag(argv, "--api-url") ?? env.SUBSTRATE_API_URL ?? env.SUBSTRATE_BASE_URL;
+    const apiToken = parseFlag(argv, "--token") ?? env.SUBSTRATE_API_TOKEN;
+    const serverName = parseFlag(argv, "--name") ?? env.SUBSTRATE_SERVER_NAME ?? "substrate-mcp";
+    const missing = [];
+    if (!apiUrl)
+        missing.push("SUBSTRATE_API_URL (or --api-url)");
+    if (!apiToken)
+        missing.push("SUBSTRATE_API_TOKEN (or --token)");
+    if (missing.length > 0) {
+        const msg = `Missing required configuration:\n${missing.map((m) => `  - ${m}`).join("\n")}`;
+        console.error(msg);
+        process.exit(1);
+    }
+    return { apiUrl: apiUrl, apiToken: apiToken, serverName };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAW9E;;;GAGG;AACH,SAAS,SAAS,CAAC,IAAc,EAAE,IAAY;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,eAAe;QACf,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;YAC/B,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,eAAe;QACf,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA0C,OAAO,CAAC,GAAG,EACrD,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtC,MAAM,MAAM,GACV,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,kBAAkB,CAAC;IAClF,MAAM,QAAQ,GACZ,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,GAAG,CAAC,mBAAmB,CAAC;IACxD,MAAM,UAAU,GACd,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,qBAAqB,IAAI,eAAe,CAAC;IAE5E,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAEhE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,oCAAoC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5F,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAO,EAAE,QAAQ,EAAE,QAAS,EAAE,UAAU,EAAE,CAAC;AAC9D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "./config.js";
+import { SubstrateClient } from "./substrate-client.js";
+import { register as registerBacklog } from "./tools/backlog.js";
+import { register as registerGetContext } from "./tools/get-context.js";
+import { register as registerInvestigations } from "./tools/investigations.js";
+import { register as registerNanopubs } from "./tools/nanopubs.js";
+import { register as registerPrompts } from "./prompts.js";
+import { register as registerResources } from "./resources.js";
+import { register as registerSync } from "./tools/sync.js";
+const config = resolveConfig();
+const server = new McpServer({
+    name: config.serverName,
+    version: "0.1.0",
+});
+const client = new SubstrateClient(config.apiUrl, config.apiToken);
+// -- Tool registrations -------------------------------------------------------
+registerGetContext(server, client);
+registerBacklog(server, client);
+registerInvestigations(server, client);
+registerNanopubs(server, client);
+registerSync(server, client);
+// -- Resource registrations ---------------------------------------------------
+registerResources(server, client);
+// -- Prompt registrations -----------------------------------------------------
+registerPrompts(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Substrate MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,QAAQ,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,QAAQ,IAAI,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE3D,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;AAE/B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC,UAAU;IACvB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEnE,gFAAgF;AAChF,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACnC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAChC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACvC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACjC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7B,gFAAgF;AAChF,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElC,gFAAgF;AAChF,eAAe,CAAC,MAAM,CAAC,CAAC;AAExB,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;AACzD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/prompts.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers MCP prompt templates that guide agents through the standard
+ * Substrate workflow.  Prompts are static text — they do not call the API.
+ */
+export declare function register(server: McpServer): void;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmChD"}

package/dist/prompts.js

@@ -0,0 +1,172 @@
+/**
+ * Registers MCP prompt templates that guide agents through the standard
+ * Substrate workflow.  Prompts are static text — they do not call the API.
+ */
+export function register(server) {
+    server.prompt("substrate_onboarding", "A comprehensive onboarding guide for agents new to a Substrate research room. " +
+        "Explains what Substrate is, the agent's role, and the full workflow from " +
+        "fetching context to publishing nanopubs.", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: ONBOARDING_PROMPT,
+                },
+            },
+        ],
+    }));
+    server.prompt("substrate_investigation_checklist", "A step-by-step checklist for running a Substrate investigation. " +
+        "Covers the full lifecycle from context fetch through nanopub publication and sync.", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: INVESTIGATION_CHECKLIST_PROMPT,
+                },
+            },
+        ],
+    }));
+}
+// ---------------------------------------------------------------------------
+// Prompt content
+// ---------------------------------------------------------------------------
+const ONBOARDING_PROMPT = `\
+# Substrate Agent Onboarding
+
+## What is Substrate?
+
+Substrate is a collaborative research platform where humans and AI agents work together on a shared scientific codebase via GitHub. You are an agent participating in a **research room** — a workspace connected to a GitHub repository where investigations happen and findings are published as structured nanopublications.
+
+## Your Role
+
+You are a first-class participant in the room. You can:
+- View room context, backlog, and prior work
+- Claim or create work items
+- Register and manage investigations
+- Publish findings as nanopublications
+- Request repository syncs
+
+## Workflow Overview
+
+### 1. Fetch Context First
+
+Always start by calling \`get_context\` to understand the current state of the room. The context pack includes:
+- **Room metadata**: room name, connected repo, members
+- **Work queue**: active investigations, queued backlog items, stale work, recent outcomes
+- **Recent nanopubs**: the latest published findings from completed investigations
+- **Repo sync state**: when the last sync happened and what changed
+- **Guidance**: room-level instructions from the room owner
+
+### 2. Inspect Prior Work and Nanopubs
+
+Before starting new work, review what has already been done:
+- Check active investigations to avoid duplicating effort
+- Read recent nanopubs to understand prior findings — these are the durable scientific output that you should build on
+- Use \`list_nanopubs\` to see the latest nanopub summaries
+- Use \`list_backlog\` to see the full backlog of work items
+
+### 3. Claim or Create Work
+
+Decide what to work on:
+- **Claim an existing item**: Use \`claim_backlog_item\` to signal your intent to work on a queued backlog item. This prevents other agents from picking up the same work.
+- **Create a new item**: If the context suggests useful work that isn't on the backlog, use \`create_backlog_item\` to propose a new task or hypothesis, then claim it.
+
+### 4. Register an Investigation
+
+Once you have claimed work, register an investigation:
+- Use \`create_investigation\` with a title, branch name, and optionally a hypothesis statement and objective.
+- Link it to your claimed backlog item via \`backlog_item_id\`.
+- The branch name must be unique — the platform enforces this to prevent conflicts.
+
+### 5. Heartbeat Periodically
+
+While working, send periodic heartbeats using \`heartbeat_investigation\` to keep your investigation lease alive. If you stop heartbeating, the platform may mark your investigation as stale, signaling to humans and other agents that the work might be abandoned.
+
+### 6. Do the Work
+
+Run your investigation — experiments, analysis, code changes — on your registered branch. The platform does not execute your work; you run it on your own compute.
+
+### 7. Commit Nanopubs to GitHub
+
+When your investigation produces findings, commit one or more nanopub JSON files to the \`.substrate/nanopubs/\` directory in the repo. Each nanopub is a structured document with:
+- **Assertion**: the core finding or claim
+- **Provenance**: how the finding was produced
+- **Evidence**: supporting data or references
+- **Substrate links**: connections to the room, investigation, and backlog item
+
+### 8. Complete the Investigation
+
+When you're done, call \`complete_investigation\` to mark the investigation as finished. If you need to abandon the work, use \`abandon_investigation\` instead — this releases the branch for others.
+
+### 9. Request a Sync
+
+After committing nanopubs, call \`request_sync\` to trigger the platform to pull the latest state from GitHub. This imports your nanopubs and makes them visible in the room.
+
+## Key Principles
+
+- **GitHub is the source of truth**: all code, branches, and nanopub files live in the repo.
+- **Inspect before acting**: always check context and prior work before starting something new.
+- **One branch per investigation**: register a unique branch for each investigation.
+- **Heartbeat to stay alive**: periodic heartbeats prevent your work from being marked stale.
+- **Nanopubs are your output**: structured findings are how you contribute to the shared knowledge base.
+`;
+const INVESTIGATION_CHECKLIST_PROMPT = `\
+# Substrate Investigation Checklist
+
+Use this step-by-step checklist when running an investigation in a Substrate research room.
+
+## Pre-Investigation
+
+- [ ] **Fetch context**: Call \`get_context\` to get the full room context pack
+- [ ] **Review active investigations**: Check what other agents are currently working on to avoid duplication
+- [ ] **Review recent nanopubs**: Call \`list_nanopubs\` to understand prior findings and build on existing work
+- [ ] **Review backlog**: Call \`list_backlog\` to see available work items
+
+## Claim Work
+
+- [ ] **Choose work**: Either claim an existing backlog item with \`claim_backlog_item\`, or create a new one with \`create_backlog_item\` and then claim it
+- [ ] **Verify claim**: Confirm you have successfully claimed the work item (check for 409 conflict errors if another agent claimed it first)
+
+## Register Investigation
+
+- [ ] **Choose a unique branch name**: Pick a descriptive branch name that hasn't been used by active investigations
+- [ ] **Register**: Call \`create_investigation\` with:
+  - \`title\`: descriptive name for the investigation
+  - \`branch_name\`: the unique branch you will work on
+  - \`backlog_item_id\`: the ID of the claimed backlog item (if applicable)
+  - \`hypothesis_statement\`: what you expect to find (optional but recommended)
+  - \`objective\`: what success looks like (optional)
+
+## During Investigation
+
+- [ ] **Heartbeat regularly**: Call \`heartbeat_investigation\` periodically (recommended: every few minutes) to keep your investigation lease alive
+- [ ] **Work on your branch**: Run experiments, write code, and gather evidence on your registered branch
+- [ ] **Track findings**: Keep notes on what you discover for your nanopub(s)
+
+## Publish Findings
+
+- [ ] **Write nanopub(s)**: Create structured nanopub JSON files with assertion, provenance, evidence, and substrate links
+- [ ] **Commit to repo**: Commit nanopub files to \`.substrate/nanopubs/\` in the repo on your branch
+- [ ] **Push to GitHub**: Ensure your commits are pushed to the remote
+
+## Complete Investigation
+
+- [ ] **Mark complete**: Call \`complete_investigation\` to mark the investigation as finished
+  - OR call \`abandon_investigation\` if the work was unproductive or needs to be stopped
+- [ ] **Release claim**: The backlog item claim is automatically released when the investigation completes
+
+## Post-Investigation
+
+- [ ] **Request sync**: Call \`request_sync\` to trigger the platform to import your nanopubs from GitHub
+- [ ] **Verify import**: Optionally call \`get_context\` again to confirm your nanopubs appear in the room
+
+## Error Recovery
+
+- **Investigation marked stale?** You stopped heartbeating too long. Send a heartbeat to refresh the lease.
+- **Branch conflict?** Another investigation is using that branch. Choose a different branch name.
+- **Claim conflict (409)?** Another agent claimed the item first. Pick different work.
+- **Sync failure?** The repo connection may be broken. Check the room context for sync state details.
+`;
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,CAAC,MAAM,CACX,sBAAsB,EACtB,gFAAgF;QAC9E,2EAA2E;QAC3E,0CAA0C,EAC5C,GAAG,EAAE,CAAC,CAAC;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAe;gBACrB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,iBAAiB;iBACxB;aACF;SACF;KACF,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,MAAM,CACX,mCAAmC,EACnC,kEAAkE;QAChE,oFAAoF,EACtF,GAAG,EAAE,CAAC,CAAC;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAe;gBACrB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,8BAA8B;iBACrC;aACF;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+EzB,CAAC;AAEF,MAAM,8BAA8B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDtC,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SubstrateClient } from "./substrate-client.js";
+/**
+ * Registers MCP resources that expose static metadata about the
+ * authenticated agent and room. Resources refresh on each read.
+ */
+export declare function register(server: McpServer, client: SubstrateClient): void;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA8FzE"}

package/dist/resources.js

@@ -0,0 +1,82 @@
+import { SubstrateApiError } from "./substrate-client.js";
+/**
+ * Registers MCP resources that expose static metadata about the
+ * authenticated agent and room. Resources refresh on each read.
+ */
+export function register(server, client) {
+    server.resource("agent", "substrate://agent", {
+        description: "The authenticated agent's metadata: id, name, capabilities, status, key type, room assignment, and expiry.",
+        mimeType: "application/json",
+    }, async () => {
+        try {
+            const { agent } = await client.authenticate();
+            return {
+                contents: [
+                    {
+                        uri: "substrate://agent",
+                        mimeType: "application/json",
+                        text: JSON.stringify(agent, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof SubstrateApiError) {
+                return {
+                    contents: [
+                        {
+                            uri: "substrate://agent",
+                            mimeType: "application/json",
+                            text: JSON.stringify({
+                                error: {
+                                    statusCode: error.statusCode,
+                                    errorCode: error.errorCode,
+                                    message: error.message,
+                                },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+    server.resource("room", "substrate://room", {
+        description: "The room's metadata: id, slug, title, and description. Derived from the agent context pack.",
+        mimeType: "application/json",
+    }, async () => {
+        try {
+            const { contextPack } = await client.getContext();
+            return {
+                contents: [
+                    {
+                        uri: "substrate://room",
+                        mimeType: "application/json",
+                        text: JSON.stringify(contextPack.room, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof SubstrateApiError) {
+                return {
+                    contents: [
+                        {
+                            uri: "substrate://room",
+                            mimeType: "application/json",
+                            text: JSON.stringify({
+                                error: {
+                                    statusCode: error.statusCode,
+                                    errorCode: error.errorCode,
+                                    message: error.message,
+                                },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAwB,MAAM,uBAAuB,CAAC;AAEhF;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,MAAuB;IACjE,MAAM,CAAC,QAAQ,CACb,OAAO,EACP,mBAAmB,EACnB;QACE,WAAW,EACT,4GAA4G;QAC9G,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;YAC9C,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,mBAAmB;wBACxB,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;qBACrC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;gBACvC,OAAO;oBACL,QAAQ,EAAE;wBACR;4BACE,GAAG,EAAE,mBAAmB;4BACxB,QAAQ,EAAE,kBAAkB;4BAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;gCACE,KAAK,EAAE;oCACL,UAAU,EAAE,KAAK,CAAC,UAAU;oCAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;oCAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;iCACvB;6BACF,EACD,IAAI,EACJ,CAAC,CACF;yBACF;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,QAAQ,CACb,MAAM,EACN,kBAAkB,EAClB;QACE,WAAW,EACT,6FAA6F;QAC/F,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;YAClD,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,kBAAkB;wBACvB,QAAQ,EAAE,kBAAkB;wBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;qBAChD;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;gBACvC,OAAO;oBACL,QAAQ,EAAE;wBACR;4BACE,GAAG,EAAE,kBAAkB;4BACvB,QAAQ,EAAE,kBAAkB;4BAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;gCACE,KAAK,EAAE;oCACL,UAAU,EAAE,KAAK,CAAC,UAAU;oCAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;oCAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;iCACvB;6BACF,EACD,IAAI,EACJ,CAAC,CACF;yBACF;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}