@plannotator/artifact-server-claude-channel 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 backnotprop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# Claude Code live feedback
+
+Connect a Claude Code session to Artifact Server through
+[Claude Code Channels](https://code.claude.com/docs/en/channels-reference).
+Reviewers can send open comment threads to the session. Claude receives the
+threads, completes the work, replies, and resolves them in Artifact Server.
+
+## Current support
+
+Claude Code Channels are a research preview. Custom channels require a
+development flag. Team and Enterprise administrators must also enable the
+`channelsEnabled` organization policy.
+
+The Artifact Server channel is currently available from a source checkout.
+The npm package is not published yet.
+
+## Before you start
+
+Before you start, make sure that:
+
+- Artifact Server is running.
+- The Artifact Server source is available locally.
+- Node.js 24.12.0 or later is installed.
+- pnpm 10.34.3 is installed.
+- Claude Code supports Channels.
+
+From the Artifact Server source directory, install the dependencies:
+
+```bash
+pnpm install
+```
+
+## Connect to Artifact Server
+
+### Local installation
+
+If `artifactserver start` runs the server, the channel reads the connection
+from these files:
+
+- `~/.artifact-server/local-service.json`
+- `~/.artifact-server/local-api-token`
+
+No additional connection settings are necessary.
+
+If `pnpm dev` runs the server from source, set the origin and token in the
+shell that starts Claude Code:
+
+```bash
+export ARTIFACT_SERVER_ORIGIN="http://127.0.0.1:8787"
+export ARTIFACT_SERVER_AGENT_TOKEN="$(<.artifact-server/local-api-token)"
+```
+
+Run these commands from the Artifact Server source directory. Do not print or
+commit the token.
+
+### Team installation
+
+Ask an Artifact Server administrator to issue an API key with these
+permissions:
+
+- **Connect agents**
+- **Manage comments**
+
+Set the server origin and API key in the shell that starts Claude Code:
+
+```bash
+export ARTIFACT_SERVER_ORIGIN="https://artifacts.example.com"
+export ARTIFACT_SERVER_AGENT_TOKEN="replace-with-the-api-key"
+```
+
+Do not add the API key to `.mcp.json` or source control.
+
+You can also set `ARTIFACT_SERVER_AGENT_NAME` to change the session name that
+appears in Artifact Server. The default name is the current directory name.
+
+## Add the channel to Claude Code
+
+Add this entry to `.mcp.json` in the project where you use Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "artifact-server": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/artifact-server/integrations/claude-channel/bin/claude-channel.js"
+      ]
+    }
+  }
+}
+```
+
+Replace the example path with the absolute path to your Artifact Server
+checkout.
+
+## Start Claude Code
+
+Start Claude Code from the project that contains `.mcp.json`:
+
+```bash
+claude --dangerously-load-development-channels server:artifact-server
+```
+
+Claude Code shows a warning for the development channel. Select **I am using
+this for local development**. If Claude Code also asks whether to use the MCP
+server, select **Use this MCP server**.
+
+## Send comments to Claude
+
+1. Open an artifact in Artifact Server.
+2. Add one or more comments.
+3. Select the Claude session in the agent picker.
+4. Send the open comments to the session.
+
+Claude receives the comments as follow-up work. The channel gives Claude the
+`artifact_comments` tool to read, reply to, and resolve each thread.
+
+## Troubleshooting
+
+If the channel does not start, run `/mcp` in Claude Code. Make sure that the
+server entry uses the correct absolute path.
+
+If Claude Code reports that an organization policy blocked the channel, ask
+an administrator to enable `channelsEnabled`.
+
+If the channel starts but no agent appears in Artifact Server, make sure that
+Artifact Server is running. Then make sure that the connection settings are
+available in the shell that started Claude Code.
+
+If `MCP_PROTOCOL_NEGOTIATION=auto` is set, Claude Code can reject the MCP
+version of the channel. Unset the variable. Then restart Claude Code.
+
+Claude Code writes channel errors to
+`~/.claude/debug/<session-id>.txt`.

package/bin/claude-channel.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {tsImport} from "tsx/esm/api";
+
+await tsImport("../index.ts", import.meta.url);

package/index.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * Artifact Server bridge as a Claude Code channel.
+ *
+ * Claude Code spawns this process over stdio when the channel is registered
+ * and opted in. It runs the same claim loop as the Pi bridge (the long poll
+ * is the heartbeat, so presence is real), and each claimed bundle is pushed
+ * into the session as a `notifications/claude/channel` event. Claude replies
+ * to and resolves each thread through the `artifact_comments` tool this
+ * server exposes.
+ *
+ * Evidence tier: `channel` — the bridge reports `delivered` once the
+ * notification is written to the transport, which proves admission to the
+ * session, not model processing (spec section 4.3).
+ */
+
+import {homedir, hostname} from "node:os";
+import process from "node:process";
+
+import {Server} from "@modelcontextprotocol/sdk/server/index.js";
+import {StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {z} from "zod";
+
+import {
+  ActivityBeacon,
+  type BridgeHandle,
+  chooseDisplayName,
+  type CommentOperations,
+  createCommentOperations,
+  type EnvironmentConfiguration,
+  resolveBridgeCredentials,
+  startBridge,
+  ThreadLocationCache,
+} from "@plannotator/agent-bridge";
+
+const channelName = "artifact-server";
+const channelVersion = "0.1.1";
+
+function environmentConfiguration(): EnvironmentConfiguration {
+  return {
+    agentDisplayName: process.env["ARTIFACT_SERVER_AGENT_NAME"],
+    agentToken: process.env["ARTIFACT_SERVER_AGENT_TOKEN"],
+    origin: process.env["ARTIFACT_SERVER_ORIGIN"],
+  };
+}
+
+const artifactCommentsInputSchema = {
+  properties: {
+    body: {
+      description: "Reply text (reply operation only).",
+      type: "string",
+    },
+    operation: {
+      description:
+        "get_bundle reads threads with their replies; reply posts one " +
+        "reply; resolve closes one thread.",
+      enum: ["get_bundle", "reply", "resolve"],
+      type: "string",
+    },
+    threadId: {
+      description: "Target thread id (reply and resolve operations).",
+      type: "string",
+    },
+    threadIds: {
+      description: "Thread ids to read (get_bundle operation).",
+      items: {type: "string"},
+      type: "array",
+    },
+  },
+  required: ["operation"],
+  type: "object",
+} as const;
+
+const artifactCommentsArgumentsSchema = z.object({
+  body: z.string().optional(),
+  operation: z.enum(["get_bundle", "reply", "resolve"]),
+  threadId: z.string().optional(),
+  threadIds: z.array(z.string()).optional(),
+});
+
+type ArtifactCommentsArguments = z.infer<typeof artifactCommentsArgumentsSchema>;
+
+function textContent(text: string) {
+  return {content: [{text, type: "text" as const}]};
+}
+
+async function runArtifactComments(
+  operations: CommentOperations | null,
+  parameters: ArtifactCommentsArguments,
+) {
+  if (operations === null) {
+    throw new Error("Artifact Server is not configured; the bridge is dormant.");
+  }
+  if (parameters.operation === "get_bundle") {
+    const threadIds = parameters.threadIds ?? [];
+    if (threadIds.length === 0) throw new Error("get_bundle requires threadIds.");
+    const details = [];
+    for (const threadId of threadIds) {
+      // eslint-disable-next-line no-await-in-loop
+      details.push(await operations.getThread(threadId));
+    }
+    return textContent(JSON.stringify(details, null, 2));
+  }
+  const threadId = parameters.threadId ?? "";
+  if (threadId === "") throw new Error(`${parameters.operation} requires threadId.`);
+  if (parameters.operation === "reply") {
+    const body = parameters.body ?? "";
+    if (body.trim() === "") throw new Error("reply requires a non-empty body.");
+    await operations.reply(threadId, body);
+    return textContent(`Replied to ${threadId}.`);
+  }
+  await operations.resolve(threadId);
+  return textContent(`Resolved ${threadId}.`);
+}
+
+async function main(): Promise<void> {
+  const mcp = new Server(
+    {name: channelName, version: channelVersion},
+    {
+      capabilities: {
+        experimental: {"claude/channel": {}},
+        tools: {},
+      },
+      instructions:
+        "Artifact Server review bundles arrive as " +
+        '<channel source="artifact-server"> events listing comment threads ' +
+        "with their ids. Do the work each thread asks for, then use the " +
+        "artifact_comments tool: reply on each thread with what you did, " +
+        "then resolve it. get_bundle rereads threads when you need the " +
+        "full context.",
+    },
+  );
+
+  const locations = new ThreadLocationCache();
+  const beacon = new ActivityBeacon();
+  const environment = environmentConfiguration();
+  const credentials = await resolveBridgeCredentials(environment, homedir());
+  const comments = credentials === null
+    ? null
+    : createCommentOperations(credentials, fetch, locations, beacon);
+
+  mcp.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: [{
+      description:
+        "Read, reply to, and resolve Artifact Server comment threads that " +
+        "were sent to this session. Use get_bundle to read threads, reply " +
+        "to record what you did on a thread, and resolve to close it when " +
+        "done.",
+      inputSchema: artifactCommentsInputSchema,
+      name: "artifact_comments",
+    }],
+  }));
+  mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "artifact_comments") {
+      throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    return runArtifactComments(
+      comments,
+      artifactCommentsArgumentsSchema.parse(request.params.arguments ?? {}),
+    );
+  });
+
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+
+  let bridge: BridgeHandle | null = null;
+  bridge = startBridge({
+    agentSessionId: null,
+    beacon,
+    capabilities: {beacon: true, evidence: "channel"},
+    credentials,
+    displayName: chooseDisplayName(environment, process.cwd()),
+    fetchImplementation: fetch,
+    host: {
+      // No compaction signal exists on this side of the stdio boundary;
+      // Claude Code itself queues channel events while the session is busy.
+      isCompacting: () => false,
+      notify: (message) => {
+        // A channel has no user-facing notice surface; stderr reaches the
+        // channel log without entering the protocol stream on stdout.
+        process.stderr.write(`${message}\n`);
+      },
+      sendUserMessage: async (text) => {
+        // Resolution proves transport admission, not model processing, which
+        // is this tier's evidence bound. A rejection fails this dispatch while
+        // leaving the channel available for later work.
+        try {
+          await mcp.notification({
+            method: "notifications/claude/channel",
+            params: {
+              content: text,
+              meta: {channel_kind: "artifact_server_dispatch"},
+            },
+          });
+        } catch (error) {
+          process.stderr.write("Channel notification failed.\n");
+          throw error;
+        }
+      },
+    },
+    hostname: hostname(),
+    kind: "claude",
+    locations,
+    log: (message) => {
+      process.stderr.write(`${message}\n`);
+    },
+    workingDirectory: process.cwd(),
+  });
+
+  const stop = (): void => {
+    const active = bridge;
+    bridge = null;
+    if (active !== null) {
+      void active.stop({disconnect: true}).finally(() => {
+        process.exit(0);
+      });
+    }
+  };
+  // The SDK transport exposes a single onclose property, not an event target.
+  // eslint-disable-next-line unicorn/prefer-add-event-listener
+  transport.onclose = stop;
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+}
+
+void (async () => {
+  try {
+    await main();
+  } catch (error) {
+    process.stderr.write(`Channel failed to start: ${String(error)}\n`);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@plannotator/artifact-server-claude-channel",
+  "version": "0.1.1",
+  "description": "Claude Code channel bridge for Artifact Server: pushes annotation bundles into an opted-in Claude Code session and closes them through the comment API.",
+  "type": "module",
+  "keywords": [
+    "claude-channel",
+    "artifact-server"
+  ],
+  "bin": {
+    "artifact-server-claude-channel": "./bin/claude-channel.js"
+  },
+  "files": [
+    "bin",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@plannotator/agent-bridge": "^0.1.1",
+    "tsx": "4.23.12",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "integrations/claude-channel",
+    "type": "git",
+    "url": "git+https://github.com/plannotator/artifact-server.git"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}