feat: add get_post / sideshow show for single-post reads

Adds a read primitive for fetching a single post by id across all
three tiers — the missing counterpart to list_posts / sideshow list.

MCP: get_post(id) — returns the full post (surfaces with ids,
version, history). Available on both stdio and HTTP transports.
CLI: sideshow show <id> — prints the full post JSON.

Agents need this to recover surface ids for per-surface operations
(edit_surface, remove_surface, reorder_surfaces) after a context
compaction, without listing the entire session.

Author: benvinegar

bin/sideshow.js

@@ -127,6 +127,7 @@ usage:
                         --surface is a deprecated alias)
       --author <name>   defaults to agent name
   sideshow list [--session <id>|--all]    list posts
+  sideshow show <id>                      show a single post (surfaces, ids, version, history)
   sideshow sessions                       list sessions
   sideshow demo                           seed two example sessions to explore the viewer
   sideshow guide                          print the design contract for posts
@@ -1520,6 +1521,13 @@ const commands = {
     out(await api(`/api/sessions/${session}/surfaces`));
   },
 
+  async show() {
+    const { positionals } = parse({ allowPositionals: true });
+    const id = positionals[0];
+    if (!id) fail("usage: sideshow show <id>");
+    out(await api(`/api/posts/${id}`));
+  },
+
   async sessions() {
     parse();
     out(await api("/api/sessions"));

mcp/server.ts

@@ -99,6 +99,17 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  "get_post",
+  {
+    description: MCP_TOOL_DESCRIPTIONS.getPost,
+    inputSchema: STDIO_MCP_INPUT_SCHEMAS.getPost,
+  },
+  async ({ id }) => {
+    return text(JSON.parse(await api(`/api/posts/${id}`)));
+  },
+);
+
 server.registerTool(
   "publish_surface",
   {

server/mcpHttp.ts

@@ -195,6 +195,11 @@ export function registerMcp(app: Hono, deps: McpDeps) {
           2,
         );
       }
+      case "get_post": {
+        const post = await deps.store.getPost(String(args.id ?? ""));
+        if (!post) throw new Error("post not found");
+        return JSON.stringify(post, null, 2);
+      }
       case "upload_asset": {
         if (typeof args.data !== "string" || args.data.length === 0) {
           throw new Error("upload_asset needs base64 `data`");

server/mcpSpec.ts

@@ -163,6 +163,8 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "Revise a post in place (same card, new version). Prefer this over publishing a near-duplicate. Pass the full replacement surfaces array. If the result includes userFeedback, read it.",
   listPostsHttp: "List posts — pass a session id to scope, or omit for all sessions.",
   listPostsStdio: "List posts in this conversation's session.",
+  getPost:
+    "Fetch a single post by id — returns the full post object including surfaces (with their ids), version, and history. Use this to recover surface ids for per-surface operations (edit_surface, remove_surface, reorder_surfaces) after a context compaction, or to inspect a post's current state before editing.",
   publishSurfaceHttp:
     "Deprecated alias of publish_post — Publish a post to the user's sideshow workspace. A post is an ordered list of surfaces (html, markdown, mermaid, diff, image, trace, terminal, json, code). Returns the post id, view URL, and sessionId — pass sessionId as `session` on later calls. On your first publish, pass sessionTitle naming the task. If the result includes userFeedback, those are new comments from the user. Call get_design_guide first if you have not this session.",
   publishSurfaceStdio:
@@ -234,6 +236,17 @@ export const HTTP_MCP_TOOLS = [
       },
     },
   },
+  {
+    name: "get_post",
+    description: MCP_TOOL_DESCRIPTIONS.getPost,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: d.surfaceId },
+      },
+      required: ["id"],
+    },
+  },
   {
     name: "publish_surface",
     description: MCP_TOOL_DESCRIPTIONS.publishSurfaceHttp,
@@ -470,6 +483,9 @@ export const STDIO_MCP_INPUT_SCHEMAS = {
     surfaces: z.array(mcpPartSchema).optional().describe(d.replacementParts),
     title: z.string().optional().describe(d.replacementTitle),
   },
+  getPost: {
+    id: z.string().describe(d.surfaceId),
+  },
   publishSurface: {
     title: z.string().describe(d.title),
     parts: z.array(mcpPartSchema).describe(MCP_SURFACES_DESCRIPTION),

test/api.test.ts

@@ -2949,3 +2949,49 @@ test("mcp tools/list includes the new per-surface tools", async () => {
   assert.ok(names.includes("remove_surface"));
   assert.ok(names.includes("reorder_surfaces"));
 });
+
+test("mcp get_post fetches a single post with surface ids via HTTP MCP", async () => {
+  const app = makeApp();
+  const pub = (await (
+    await app.request(
+      "/mcp",
+      mcpCall(1, "tools/call", {
+        name: "publish_post",
+        arguments: {
+          title: "GetPost",
+          surfaces: [
+            { kind: "html", html: "<p>a</p>" },
+            { kind: "markdown", markdown: "# b" },
+          ],
+        },
+      }),
+    )
+  ).json()) as any;
+  const postId = JSON.parse(pub.result.content[0].text).id;
+
+  const res = (await (
+    await app.request(
+      "/mcp",
+      mcpCall(2, "tools/call", {
+        name: "get_post",
+        arguments: { id: postId },
+      }),
+    )
+  ).json()) as any;
+  assert.equal(res.result.isError, undefined);
+  const post = JSON.parse(res.result.content[0].text);
+  assert.equal(post.id, postId);
+  assert.equal(post.title, "GetPost");
+  assert.equal(post.surfaces.length, 2);
+  assert.equal(post.surfaces[0].kind, "html");
+  assert.equal(post.surfaces[1].kind, "markdown");
+  assert.ok(post.surfaces[0].id, "surface ids are present");
+  assert.ok(post.surfaces[1].id);
+});
+
+test("mcp tools/list includes get_post", async () => {
+  const app = makeApp();
+  const list = (await (await app.request("/mcp", mcpCall(1, "tools/list"))).json()) as any;
+  const names = list.result.tools.map((t: any) => t.name);
+  assert.ok(names.includes("get_post"));
+});

test/cli.test.ts

@@ -93,6 +93,7 @@ for (const cmd of [
   "watch",
   "comment",
   "list",
+  "show",
   "kits",
 ]) {
   test(`${cmd} --help prints usage and exits 0`, async () => {
@@ -948,6 +949,35 @@ test("sessions prints the workspace's sessions", async () => {
   }
 });
 
+test("show prints a single post with surface ids", async () => {
+  const server = await serveSession();
+  try {
+    const html = tmpFile("h.html", "<p>a</p>");
+    const md = tmpFile("m.md", "# b");
+    const pub = await cli(server, "publish", html, "--md", md, "--title", "ShowMe");
+    const id = JSON.parse(pub.stdout).id;
+
+    const { code, stdout } = await cli(server, "show", id);
+    assert.equal(code, 0);
+    const post = JSON.parse(stdout);
+    assert.equal(post.id, id);
+    assert.equal(post.title, "ShowMe");
+    assert.equal(post.surfaces.length, 2);
+    assert.equal(post.surfaces[0].kind, "html");
+    assert.equal(post.surfaces[1].kind, "markdown");
+    assert.ok(post.surfaces[0].id, "surface ids are present");
+    assert.ok(post.surfaces[1].id);
+  } finally {
+    await server.close();
+  }
+});
+
+test("show without an id fails with a usage error", async () => {
+  const { code, stderr } = await run("show");
+  assert.notEqual(code, 0);
+  assert.match(stderr, /usage: sideshow show/);
+});
+
 // --- assets (image / upload / asset-url) ----------------------------------
 
 test("image uploads bytes and publishes an image post", async () => {