@useclickly/mcp-server 1.0.0 → 1.0.1

package/dist/index.js.map

@@ -1 +1,7 @@
-{"version":3,"sources":["../src/server.ts"],"names":[],"mappings":";;AAoBA,eAAsB,YAAA,CAAa,QAAA,GAA0B,EAAC,EAA0B;AACtF,EAAA,MAAM,IAAI,MAAM,gEAAgE,CAAA;AAClF","file":"index.js","sourcesContent":["import type { Annotation } from \"@useclickly/core\";\n\nexport interface ServerOptions {\n  /** HTTP port for the browser bridge. Default: 4747. */\n  port?: number;\n  /** On-disk path for session persistence. Default: ~/.clickly/sessions.json. */\n  storePath?: string;\n}\n\nexport interface ServerHandle {\n  port: number;\n  close(): Promise<void>;\n  getAnnotations(sessionId: string): Annotation[];\n}\n\n/**\n * Phase 2 stub. Real MCP wiring + HTTP/SSE bridge + tool definitions\n * arrive after Phase 8 (output format) so we have a stable schema to\n * advertise to MCP clients.\n */\nexport async function createServer(_options: ServerOptions = {}): Promise<ServerHandle> {\n  throw new Error(\"@useclickly/mcp-server: not yet implemented (Phase 2 scaffold)\");\n}\n"]}
+{
+  "version": 3,
+  "sources": ["../src/server.ts", "../src/store.ts", "../src/http-bridge.ts"],
+  "sourcesContent": ["/**\n * @useclickly/mcp-server \u2014 real implementation.\n *\n * Exposes a Model Context Protocol stdio server backed by an in-process\n * HTTP bridge. AI coding agents connect via stdio; the browser component\n * connects via HTTP on localhost:4747.\n *\n * MCP tools\n * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n *  clickly_list_sessions      List all annotation sessions\n *  clickly_list_annotations   List annotations for a session\n *  clickly_get_annotation     Fetch a single annotation by ID\n *  clickly_acknowledge        Mark annotation as acknowledged\n *  clickly_resolve            Mark annotation as resolved\n *  clickly_dismiss            Mark annotation as dismissed\n *  clickly_reply              Append a thread message to an annotation\n */\n\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\nimport { AnnotationStore } from \"./store.js\";\nimport { createHttpBridge } from \"./http-bridge.js\";\n\nexport { AnnotationStore } from \"./store.js\";\n\n/* \u2500\u2500\u2500 Public types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nexport interface ServerOptions {\n  /** HTTP port for the browser bridge. Default: 4747. */\n  port?: number;\n  /** On-disk path for session persistence. Default: ~/.clickly/sessions.json. */\n  storePath?: string;\n  /** Custom store instance (useful for testing). */\n  store?: AnnotationStore;\n}\n\nexport interface ServerHandle {\n  port: number;\n  close(): Promise<void>;\n}\n\n/* \u2500\u2500\u2500 Shared input schemas \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nconst SessionIdSchema = {\n  sessionId: z.string().describe(\"Session ID returned by the browser bridge\"),\n};\n\nconst AnnotationIdSchema = {\n  ...SessionIdSchema,\n  annotationId: z.string().describe(\"Annotation ID\"),\n};\n\n/* \u2500\u2500\u2500 Helper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nfunction errResult(message: string) {\n  return {\n    isError: true as const,\n    content: [{ type: \"text\" as const, text: message }],\n  };\n}\n\nfunction okResult(data: unknown) {\n  return {\n    content: [\n      {\n        type: \"text\" as const,\n        text: typeof data === \"string\" ? data : JSON.stringify(data, null, 2),\n      },\n    ],\n  };\n}\n\n/* \u2500\u2500\u2500 createServer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nexport async function createServer(options: ServerOptions = {}): Promise<ServerHandle> {\n  const port = options.port ?? 4747;\n  const store =\n    options.store ?? new AnnotationStore({ storePath: options.storePath });\n\n  /* \u2500\u2500 HTTP bridge (browser \u2192 server) \u2500\u2500\u2500 */\n  const bridge = createHttpBridge(store, port);\n\n  /* \u2500\u2500 MCP server (stdio, agent \u2192 server) \u2500\u2500\u2500 */\n  const mcp = new McpServer(\n    { name: \"clickly\", version: \"1.0.0\" },\n    {\n      capabilities: { tools: {} },\n      instructions:\n        \"Clickly exposes UI annotations captured in a running React development app. \" +\n        \"Use these tools to read feedback, acknowledge issues, resolve them, or reply \" +\n        \"to start a conversation thread with the developer.\",\n    },\n  );\n\n  /* \u2500\u2500 clickly_list_sessions \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_list_sessions\",\n    {\n      description:\n        \"List all Clickly annotation sessions. Each session corresponds to a page/URL \" +\n        \"where the developer opened the Clickly toolbar. Returns session IDs, URLs, \" +\n        \"creation timestamps, and annotation counts.\",\n      inputSchema: {},\n    },\n    async () => {\n      const sessions = store.listSessions();\n      const rows = sessions.map((s) => ({\n        sessionId: s.id,\n        url: s.url,\n        createdAt: new Date(s.createdAt).toISOString(),\n        annotationCount: store.listAnnotations(s.id).length,\n      }));\n      return okResult(rows);\n    },\n  );\n\n  /* \u2500\u2500 clickly_list_annotations \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_list_annotations\",\n    {\n      description:\n        \"List all annotations in a session. Includes element path, position, React \" +\n        \"component tree, source file/line, feedback comment, and lifecycle status.\",\n      inputSchema: SessionIdSchema,\n    },\n    async ({ sessionId }) => {\n      const session = store.getSession(sessionId);\n      if (!session) return errResult(`Session not found: ${sessionId}`);\n      return okResult(store.listAnnotations(sessionId));\n    },\n  );\n\n  /* \u2500\u2500 clickly_get_annotation \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_get_annotation\",\n    {\n      description:\n        \"Fetch a single annotation by ID. Returns the full AFS 1.1 record including \" +\n        \"element metadata, bounding box, React component chain, source location, \" +\n        \"and any thread messages.\",\n      inputSchema: AnnotationIdSchema,\n    },\n    async ({ sessionId, annotationId }) => {\n      const annotation = store.getAnnotation(sessionId, annotationId);\n      if (!annotation) {\n        return errResult(\n          `Annotation not found: ${annotationId} in session ${sessionId}`,\n        );\n      }\n      return okResult(annotation);\n    },\n  );\n\n  /* \u2500\u2500 clickly_acknowledge \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_acknowledge\",\n    {\n      description:\n        \"Mark an annotation as 'acknowledged' \u2014 you have seen it and are working on it. \" +\n        \"The developer's UI will show an acknowledged badge on the annotation pin.\",\n      inputSchema: AnnotationIdSchema,\n    },\n    async ({ sessionId, annotationId }) => {\n      try {\n        const updated = store.updateAnnotation(sessionId, annotationId, {\n          status: \"acknowledged\",\n        });\n        return okResult(\n          `Acknowledged annotation ${updated.id} in session ${sessionId}.`,\n        );\n      } catch (err) {\n        return errResult(err instanceof Error ? err.message : String(err));\n      }\n    },\n  );\n\n  /* \u2500\u2500 clickly_resolve \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_resolve\",\n    {\n      description:\n        \"Mark an annotation as 'resolved' \u2014 the issue has been fixed. Optionally include \" +\n        \"a resolution note. The pin will show as resolved in the developer's browser.\",\n      inputSchema: {\n        ...AnnotationIdSchema,\n        note: z\n          .string()\n          .optional()\n          .describe(\"Optional resolution note to append to the thread\"),\n      },\n    },\n    async ({ sessionId, annotationId, note }) => {\n      try {\n        const existing = store.getAnnotation(sessionId, annotationId);\n        if (!existing) return errResult(`Annotation not found: ${annotationId}`);\n\n        const thread = existing.thread ? [...existing.thread] : [];\n        if (note) {\n          thread.push({\n            id: crypto.randomUUID(),\n            role: \"agent\",\n            content: note,\n            timestamp: Date.now(),\n          });\n        }\n\n        const updated = store.updateAnnotation(sessionId, annotationId, {\n          status: \"resolved\",\n          resolvedAt: new Date().toISOString(),\n          resolvedBy: \"agent\",\n          ...(note ? { thread } : {}),\n        });\n        return okResult(\n          `Resolved annotation ${updated.id}.${note ? ` Note: \"${note}\"` : \"\"}`,\n        );\n      } catch (err) {\n        return errResult(err instanceof Error ? err.message : String(err));\n      }\n    },\n  );\n\n  /* \u2500\u2500 clickly_dismiss \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_dismiss\",\n    {\n      description:\n        \"Mark an annotation as 'dismissed' \u2014 it is not actionable or is a duplicate. \" +\n        \"Dismissed annotations are hidden from the default list view.\",\n      inputSchema: AnnotationIdSchema,\n    },\n    async ({ sessionId, annotationId }) => {\n      try {\n        const updated = store.updateAnnotation(sessionId, annotationId, {\n          status: \"dismissed\",\n        });\n        return okResult(`Dismissed annotation ${updated.id}.`);\n      } catch (err) {\n        return errResult(err instanceof Error ? err.message : String(err));\n      }\n    },\n  );\n\n  /* \u2500\u2500 clickly_reply \u2500\u2500\u2500 */\n  mcp.registerTool(\n    \"clickly_reply\",\n    {\n      description:\n        \"Append a thread message to an annotation. Use this to ask a clarifying question, \" +\n        \"describe what you changed, or communicate back to the developer who left feedback.\",\n      inputSchema: {\n        ...AnnotationIdSchema,\n        message: z.string().describe(\"Your reply message\"),\n      },\n    },\n    async ({ sessionId, annotationId, message }) => {\n      try {\n        const existing = store.getAnnotation(sessionId, annotationId);\n        if (!existing) return errResult(`Annotation not found: ${annotationId}`);\n\n        const thread = [\n          ...(existing.thread ?? []),\n          {\n            id: crypto.randomUUID(),\n            role: \"agent\" as const,\n            content: message,\n            timestamp: Date.now(),\n          },\n        ];\n\n        store.updateAnnotation(sessionId, annotationId, { thread });\n        return okResult(`Reply added to annotation ${annotationId}.`);\n      } catch (err) {\n        return errResult(err instanceof Error ? err.message : String(err));\n      }\n    },\n  );\n\n  /* \u2500\u2500 Connect stdio transport \u2500\u2500\u2500 */\n  const transport = new StdioServerTransport();\n  await mcp.connect(transport);\n\n  return {\n    port,\n    close: async () => {\n      await mcp.close();\n      await bridge.close();\n    },\n  };\n}\n", "/**\n * Annotation + Session store.\n *\n * Holds everything in-memory for fast reads.\n * Persists to a JSON file on every mutating operation so the MCP client\n * can survive a server restart without losing annotations.\n */\n\nimport fs from \"node:fs\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport type { Annotation } from \"@useclickly/core\";\n\n/* \u2500\u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nexport interface Session {\n  id: string;\n  url: string;\n  createdAt: number;\n  /** Monotonically increasing counter \u2014 incremented on every annotation mutation. */\n  seq: number;\n}\n\nexport interface AnnotationRecord extends Annotation {\n  sessionId: string;\n}\n\nexport interface StoreOptions {\n  /**\n   * Where to persist sessions + annotations.\n   * Defaults to `~/.clickly/sessions.json`.\n   */\n  storePath?: string;\n}\n\n/* \u2500\u2500\u2500 Persisted shape \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\ninterface PersistedData {\n  sessions: Session[];\n  annotations: AnnotationRecord[];\n}\n\n/* \u2500\u2500\u2500 Store \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nexport class AnnotationStore {\n  private sessions = new Map<string, Session>();\n  /** sessionId \u2192 (annotationId \u2192 AnnotationRecord) */\n  private annotations = new Map<string, Map<string, AnnotationRecord>>();\n  /** Listeners waiting for new annotations in a session (SSE bridge) */\n  private listeners = new Map<string, Set<(a: AnnotationRecord, seq: number) => void>>();\n\n  readonly storePath: string;\n\n  constructor(options: StoreOptions = {}) {\n    this.storePath =\n      options.storePath ?? path.join(os.homedir(), \".clickly\", \"sessions.json\");\n    this._load();\n  }\n\n  /* \u2500\u2500 Sessions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n  createSession(url: string): Session {\n    const id = crypto.randomUUID();\n    const session: Session = { id, url, createdAt: Date.now(), seq: 0 };\n    this.sessions.set(id, session);\n    this.annotations.set(id, new Map());\n    this._persist();\n    return session;\n  }\n\n  getSession(sessionId: string): Session | undefined {\n    return this.sessions.get(sessionId);\n  }\n\n  listSessions(): Session[] {\n    return [...this.sessions.values()].sort((a, b) => b.createdAt - a.createdAt);\n  }\n\n  /* \u2500\u2500 Annotations \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n  addAnnotation(sessionId: string, annotation: Annotation): AnnotationRecord {\n    const session = this.sessions.get(sessionId);\n    if (!session) throw new Error(`Session not found: ${sessionId}`);\n\n    const bucket = this.annotations.get(sessionId)!;\n    const record: AnnotationRecord = { ...annotation, sessionId };\n    bucket.set(annotation.id, record);\n\n    session.seq += 1;\n    const seq = session.seq;\n\n    this._persist();\n    this._emit(sessionId, record, seq);\n    return record;\n  }\n\n  getAnnotation(sessionId: string, annotationId: string): AnnotationRecord | undefined {\n    return this.annotations.get(sessionId)?.get(annotationId);\n  }\n\n  listAnnotations(sessionId: string): AnnotationRecord[] {\n    const bucket = this.annotations.get(sessionId);\n    if (!bucket) return [];\n    return [...bucket.values()].sort((a, b) => a.timestamp - b.timestamp);\n  }\n\n  updateAnnotation(\n    sessionId: string,\n    annotationId: string,\n    patch: Partial<Annotation>,\n  ): AnnotationRecord {\n    const session = this.sessions.get(sessionId);\n    if (!session) throw new Error(`Session not found: ${sessionId}`);\n\n    const bucket = this.annotations.get(sessionId);\n    const existing = bucket?.get(annotationId);\n    if (!existing) throw new Error(`Annotation not found: ${annotationId}`);\n\n    const updated: AnnotationRecord = { ...existing, ...patch, sessionId };\n    bucket!.set(annotationId, updated);\n\n    session.seq += 1;\n    const seq = session.seq;\n\n    this._persist();\n    this._emit(sessionId, updated, seq);\n    return updated;\n  }\n\n  /* \u2500\u2500 SSE subscriptions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n  subscribe(\n    sessionId: string,\n    cb: (annotation: AnnotationRecord, seq: number) => void,\n  ): () => void {\n    if (!this.listeners.has(sessionId)) {\n      this.listeners.set(sessionId, new Set());\n    }\n    this.listeners.get(sessionId)!.add(cb);\n    return () => this.listeners.get(sessionId)?.delete(cb);\n  }\n\n  private _emit(sessionId: string, annotation: AnnotationRecord, seq: number): void {\n    this.listeners.get(sessionId)?.forEach((cb) => cb(annotation, seq));\n  }\n\n  /* \u2500\u2500 Persistence \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n  private _persist(): void {\n    try {\n      const dir = path.dirname(this.storePath);\n      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n\n      const data: PersistedData = {\n        sessions: [...this.sessions.values()],\n        annotations: [...this.annotations.values()].flatMap((m) => [...m.values()]),\n      };\n      fs.writeFileSync(this.storePath, JSON.stringify(data, null, 2), \"utf-8\");\n    } catch {\n      // Persistence failures are non-fatal \u2014 data is still in-memory.\n    }\n  }\n\n  private _load(): void {\n    try {\n      if (!fs.existsSync(this.storePath)) return;\n      const raw = fs.readFileSync(this.storePath, \"utf-8\");\n      const data: PersistedData = JSON.parse(raw);\n\n      for (const session of data.sessions ?? []) {\n        this.sessions.set(session.id, session);\n        this.annotations.set(session.id, new Map());\n      }\n      for (const annotation of data.annotations ?? []) {\n        this.annotations.get(annotation.sessionId)?.set(annotation.id, annotation);\n      }\n    } catch {\n      // Corrupted or missing file \u2014 start fresh.\n    }\n  }\n}\n", "/**\n * HTTP bridge \u2014 lets the in-browser <Clickly /> component talk to this server.\n *\n * Endpoints\n * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n *  POST /sessions\n *    Body: { url: string }\n *    Returns: { sessionId: string }\n *\n *  POST /sessions/:sessionId/annotations\n *    Body: Annotation (AFS 1.1)\n *    Returns: { ok: true, id: string }\n *\n *  GET  /sessions/:sessionId/annotations\n *    Returns: Annotation[]\n *\n *  GET  /sessions/:sessionId/events\n *    Server-Sent Events stream \u2014 emits `annotation` events on every add/update.\n *    Each event: `data: { annotation, seq }\\n\\n`\n *\n *  GET  /sessions\n *    Returns: Session[]\n *\n *  GET  /health\n *    Returns: { ok: true, version: string }\n */\n\nimport http from \"node:http\";\nimport type { AnnotationStore } from \"./store.js\";\n\nconst VERSION = \"1.0.0\";\n\n/* \u2500\u2500\u2500 CORS helper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nfunction cors(res: http.ServerResponse): void {\n  res.setHeader(\"Access-Control-Allow-Origin\", \"*\");\n  res.setHeader(\"Access-Control-Allow-Methods\", \"GET, POST, OPTIONS\");\n  res.setHeader(\"Access-Control-Allow-Headers\", \"Content-Type\");\n}\n\n/* \u2500\u2500\u2500 Response helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nfunction json(res: http.ServerResponse, status: number, body: unknown): void {\n  cors(res);\n  const payload = JSON.stringify(body);\n  res.writeHead(status, {\n    \"Content-Type\": \"application/json\",\n    \"Content-Length\": Buffer.byteLength(payload),\n  });\n  res.end(payload);\n}\n\nfunction notFound(res: http.ServerResponse): void {\n  json(res, 404, { error: \"not_found\" });\n}\n\nfunction badRequest(res: http.ServerResponse, message: string): void {\n  json(res, 400, { error: \"bad_request\", message });\n}\n\n/* \u2500\u2500\u2500 Body reader \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nfunction readBody(req: http.IncomingMessage): Promise<unknown> {\n  return new Promise((resolve, reject) => {\n    let raw = \"\";\n    req.on(\"data\", (chunk) => (raw += chunk));\n    req.on(\"end\", () => {\n      try {\n        resolve(raw ? JSON.parse(raw) : {});\n      } catch {\n        reject(new Error(\"Invalid JSON body\"));\n      }\n    });\n    req.on(\"error\", reject);\n  });\n}\n\n/* \u2500\u2500\u2500 Router \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nfunction route(\n  req: http.IncomingMessage,\n): { method: string; segments: string[] } | null {\n  const url = new URL(req.url ?? \"/\", \"http://localhost\");\n  const segments = url.pathname.replace(/^\\//, \"\").split(\"/\").filter(Boolean);\n  return { method: req.method?.toUpperCase() ?? \"GET\", segments };\n}\n\n/* \u2500\u2500\u2500 Bridge factory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nexport interface BridgeHandle {\n  port: number;\n  close(): Promise<void>;\n}\n\nexport function createHttpBridge(store: AnnotationStore, port: number): BridgeHandle {\n  const server = http.createServer(async (req, res) => {\n    // Preflight\n    if (req.method === \"OPTIONS\") {\n      cors(res);\n      res.writeHead(204);\n      res.end();\n      return;\n    }\n\n    const r = route(req);\n    if (!r) return notFound(res);\n    const { method, segments } = r;\n\n    try {\n      // GET /health\n      if (method === \"GET\" && segments[0] === \"health\") {\n        return json(res, 200, { ok: true, version: VERSION });\n      }\n\n      // GET /sessions\n      if (method === \"GET\" && segments.length === 1 && segments[0] === \"sessions\") {\n        return json(res, 200, store.listSessions());\n      }\n\n      // POST /sessions\n      if (method === \"POST\" && segments.length === 1 && segments[0] === \"sessions\") {\n        const body = (await readBody(req)) as { url?: string };\n        if (!body.url) return badRequest(res, \"url is required\");\n        const session = store.createSession(body.url);\n        return json(res, 201, { sessionId: session.id });\n      }\n\n      // Routes under /sessions/:sessionId/...\n      if (segments[0] === \"sessions\" && segments[1]) {\n        const sessionId = segments[1];\n        const session = store.getSession(sessionId);\n        if (!session) return json(res, 404, { error: \"session_not_found\" });\n\n        const sub = segments[2];\n\n        // GET /sessions/:id/annotations\n        if (method === \"GET\" && sub === \"annotations\" && segments.length === 3) {\n          return json(res, 200, store.listAnnotations(sessionId));\n        }\n\n        // POST /sessions/:id/annotations\n        if (method === \"POST\" && sub === \"annotations\" && segments.length === 3) {\n          const body = await readBody(req);\n          if (!body || typeof body !== \"object\") return badRequest(res, \"body required\");\n          const annotation = body as Record<string, unknown>;\n          if (!annotation.id || !annotation.comment || !annotation.elementPath) {\n            return badRequest(res, \"id, comment, elementPath are required\");\n          }\n          // eslint-disable-next-line @typescript-eslint/no-explicit-any\n          const record = store.addAnnotation(sessionId, annotation as any);\n          return json(res, 201, { ok: true, id: record.id });\n        }\n\n        // GET /sessions/:id/events  \u2014 SSE\n        if (method === \"GET\" && sub === \"events\" && segments.length === 3) {\n          cors(res);\n          res.writeHead(200, {\n            \"Content-Type\": \"text/event-stream\",\n            \"Cache-Control\": \"no-cache\",\n            Connection: \"keep-alive\",\n            \"X-Accel-Buffering\": \"no\", // disable nginx buffering\n          });\n\n          // Send current sequence as a \"connected\" event\n          res.write(`event: connected\\ndata: ${JSON.stringify({ seq: session.seq })}\\n\\n`);\n\n          // Subscribe to future annotations\n          const unsubscribe = store.subscribe(sessionId, (annotation, seq) => {\n            const payload = JSON.stringify({ annotation, seq });\n            res.write(`event: annotation\\ndata: ${payload}\\n\\n`);\n          });\n\n          // Heartbeat every 15s to keep connection alive through proxies\n          const heartbeat = setInterval(() => {\n            res.write(`: heartbeat\\n\\n`);\n          }, 15_000);\n\n          req.on(\"close\", () => {\n            clearInterval(heartbeat);\n            unsubscribe();\n          });\n          return; // SSE \u2014 don't close\n        }\n      }\n\n      notFound(res);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : \"internal_error\";\n      json(res, 500, { error: \"internal_error\", message });\n    }\n  });\n\n  server.listen(port);\n\n  return {\n    port,\n    close: () =>\n      new Promise((resolve, reject) =>\n        server.close((err) => (err ? reject(err) : resolve())),\n      ),\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @useclickly/mcp-server — real implementation.
+ *
+ * Exposes a Model Context Protocol stdio server backed by an in-process
+ * HTTP bridge. AI coding agents connect via stdio; the browser component
+ * connects via HTTP on localhost:4747.
+ *
+ * MCP tools
+ * ─────────
+ *  clickly_list_sessions      List all annotation sessions
+ *  clickly_list_annotations   List annotations for a session
+ *  clickly_get_annotation     Fetch a single annotation by ID
+ *  clickly_acknowledge        Mark annotation as acknowledged
+ *  clickly_resolve            Mark annotation as resolved
+ *  clickly_dismiss            Mark annotation as dismissed
+ *  clickly_reply              Append a thread message to an annotation
+ */
+import { AnnotationStore } from "./store.js";
+export { AnnotationStore } from "./store.js";
+export interface ServerOptions {
+    /** HTTP port for the browser bridge. Default: 4747. */
+    port?: number;
+    /** On-disk path for session persistence. Default: ~/.clickly/sessions.json. */
+    storePath?: string;
+    /** Custom store instance (useful for testing). */
+    store?: AnnotationStore;
+}
+export interface ServerHandle {
+    port: number;
+    close(): Promise<void>;
+}
+export declare function createServer(options?: ServerOptions): Promise<ServerHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAmCD,wBAAsB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAsNrF"}

package/dist/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Annotation + Session store.
+ *
+ * Holds everything in-memory for fast reads.
+ * Persists to a JSON file on every mutating operation so the MCP client
+ * can survive a server restart without losing annotations.
+ */
+import type { Annotation } from "@useclickly/core";
+export interface Session {
+    id: string;
+    url: string;
+    createdAt: number;
+    /** Monotonically increasing counter — incremented on every annotation mutation. */
+    seq: number;
+}
+export interface AnnotationRecord extends Annotation {
+    sessionId: string;
+}
+export interface StoreOptions {
+    /**
+     * Where to persist sessions + annotations.
+     * Defaults to `~/.clickly/sessions.json`.
+     */
+    storePath?: string;
+}
+export declare class AnnotationStore {
+    private sessions;
+    /** sessionId → (annotationId → AnnotationRecord) */
+    private annotations;
+    /** Listeners waiting for new annotations in a session (SSE bridge) */
+    private listeners;
+    readonly storePath: string;
+    constructor(options?: StoreOptions);
+    createSession(url: string): Session;
+    getSession(sessionId: string): Session | undefined;
+    listSessions(): Session[];
+    addAnnotation(sessionId: string, annotation: Annotation): AnnotationRecord;
+    getAnnotation(sessionId: string, annotationId: string): AnnotationRecord | undefined;
+    listAnnotations(sessionId: string): AnnotationRecord[];
+    updateAnnotation(sessionId: string, annotationId: string, patch: Partial<Annotation>): AnnotationRecord;
+    subscribe(sessionId: string, cb: (annotation: AnnotationRecord, seq: number) => void): () => void;
+    private _emit;
+    private _persist;
+    private _load;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAA8B;IAC9C,oDAAoD;IACpD,OAAO,CAAC,WAAW,CAAoD;IACvE,sEAAsE;IACtE,OAAO,CAAC,SAAS,CAAsE;IAEvF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,GAAE,YAAiB;IAQtC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IASnC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIlD,YAAY,IAAI,OAAO,EAAE;IAMzB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,gBAAgB;IAgB1E,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIpF,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAMtD,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GACzB,gBAAgB;IAqBnB,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,GACtD,MAAM,IAAI;IAQb,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,KAAK;CAiBd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useclickly/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Model Context Protocol stdio server that exposes Clickly annotations to AI coding agents (Claude Code, Cursor, Codex, Windsurf).",
   "license": "MIT",
   "author": "Clickly contributors",
@@ -41,9 +41,18 @@
       "require": "./dist/index.cjs"
     }
   },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist .turbo",
+    "start": "node dist/cli.js server"
+  },
   "dependencies": {
+    "@useclickly/core": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@useclickly/core": "1.0.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^20.16.10",
@@ -57,13 +66,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run --passWithNoTests",
-    "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist .turbo",
-    "start": "node dist/cli.js server"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Clickly contributors
-
-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.