@useclickly/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,64 @@
+# @useclickly/mcp-server
+
+> Model Context Protocol stdio server that exposes Clickly annotations to AI coding agents.
+
+Works with any MCP-aware tool: Claude Code, Cursor, Codex, Windsurf, and more. When your `<Clickly />` browser component is connected, the agent can list pending annotations, acknowledge them, resolve them with a summary, or dismiss them with a reason — all from inside the agent's chat.
+
+## Install
+
+```bash
+npm install -g @useclickly/mcp-server
+# or run on demand:
+npx @useclickly/mcp-server server
+```
+
+## Quick wire-up
+
+The fastest way to configure Clickly across every installed agent:
+
+```bash
+npx add-mcp "npx -y @useclickly/mcp-server server"
+```
+
+`add-mcp` auto-detects your installed agents (Claude Code, Cursor, etc.) and writes the right config.
+
+## Manual MCP entry
+
+Add this to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "clickly": {
+      "command": "npx",
+      "args": ["-y", "@useclickly/mcp-server", "server"]
+    }
+  }
+}
+```
+
+## Connecting the browser component
+
+In your React app:
+
+```tsx
+<Clickly endpoint="http://localhost:4747" />
+```
+
+The component will POST annotations to the server and keep its session in sync.
+
+## CLI
+
+```
+clickly-mcp server          run the MCP server (stdio + HTTP bridge on :4747)
+clickly-mcp doctor          verify Node, port availability, store writability
+clickly-mcp init            interactive setup wizard
+```
+
+## Status
+
+🚧 Phase 10 ships the package scaffold. The MCP tool definitions and HTTP bridge land before v0.2.0.
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+// src/cli.ts
+var [, , cmd] = process.argv;
+switch (cmd) {
+  case "server":
+  case "doctor":
+  case "init":
+    console.error(`clickly-mcp: "${cmd}" not yet implemented (Phase 2 scaffold)`);
+    process.exit(2);
+    break;
+  default:
+    console.log("usage: clickly-mcp <server|doctor|init>");
+    process.exit(cmd ? 1 : 0);
+}
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"names":[],"mappings":";;;AAUA,IAAM,KAAK,GAAG,IAAI,OAAA,CAAQ,IAAA;AAE1B,QAAQ,GAAA;AAAK,EACX,KAAK,QAAA;AAAA,EACL,KAAK,QAAA;AAAA,EACL,KAAK,MAAA;AACH,IAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,cAAA,EAAkB,GAAG,CAAA,wCAAA,CAA2C,CAAA;AAC9E,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AACd,IAAA;AAAA,EACF;AACE,IAAA,OAAA,CAAQ,IAAI,yCAAyC,CAAA;AACrD,IAAA,OAAA,CAAQ,IAAA,CAAK,GAAA,GAAM,CAAA,GAAI,CAAC,CAAA;AAC5B","file":"cli.cjs","sourcesContent":["/**\n * `clickly-mcp` CLI. (Shebang prepended by tsup banner.)\n *\n * Subcommands (planned):\n *   server        Run the MCP server (stdio + HTTP bridge on :4747)\n *   doctor        Verify Node version, port availability, store writability\n *   init          Interactive setup for Claude Code / Cursor / Codex\n *\n * Phase 2 stub.\n */\nconst [, , cmd] = process.argv;\n\nswitch (cmd) {\n  case \"server\":\n  case \"doctor\":\n  case \"init\":\n    console.error(`clickly-mcp: \\\"${cmd}\\\" not yet implemented (Phase 2 scaffold)`);\n    process.exit(2);\n    break;\n  default:\n    console.log(\"usage: clickly-mcp <server|doctor|init>\");\n    process.exit(cmd ? 1 : 0);\n}\n"]}

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// src/cli.ts
+var [, , cmd] = process.argv;
+switch (cmd) {
+  case "server":
+  case "doctor":
+  case "init":
+    console.error(`clickly-mcp: "${cmd}" not yet implemented (Phase 2 scaffold)`);
+    process.exit(2);
+    break;
+  default:
+    console.log("usage: clickly-mcp <server|doctor|init>");
+    process.exit(cmd ? 1 : 0);
+}
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"names":[],"mappings":";;AAUA,IAAM,KAAK,GAAG,IAAI,OAAA,CAAQ,IAAA;AAE1B,QAAQ,GAAA;AAAK,EACX,KAAK,QAAA;AAAA,EACL,KAAK,QAAA;AAAA,EACL,KAAK,MAAA;AACH,IAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,cAAA,EAAkB,GAAG,CAAA,wCAAA,CAA2C,CAAA;AAC9E,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AACd,IAAA;AAAA,EACF;AACE,IAAA,OAAA,CAAQ,IAAI,yCAAyC,CAAA;AACrD,IAAA,OAAA,CAAQ,IAAA,CAAK,GAAA,GAAM,CAAA,GAAI,CAAC,CAAA;AAC5B","file":"cli.js","sourcesContent":["/**\n * `clickly-mcp` CLI. (Shebang prepended by tsup banner.)\n *\n * Subcommands (planned):\n *   server        Run the MCP server (stdio + HTTP bridge on :4747)\n *   doctor        Verify Node version, port availability, store writability\n *   init          Interactive setup for Claude Code / Cursor / Codex\n *\n * Phase 2 stub.\n */\nconst [, , cmd] = process.argv;\n\nswitch (cmd) {\n  case \"server\":\n  case \"doctor\":\n  case \"init\":\n    console.error(`clickly-mcp: \\\"${cmd}\\\" not yet implemented (Phase 2 scaffold)`);\n    process.exit(2);\n    break;\n  default:\n    console.log(\"usage: clickly-mcp <server|doctor|init>\");\n    process.exit(cmd ? 1 : 0);\n}\n"]}

package/dist/index.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+// src/server.ts
+async function createServer(_options = {}) {
+  throw new Error("@useclickly/mcp-server: not yet implemented (Phase 2 scaffold)");
+}
+
+exports.createServer = createServer;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"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.cjs","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"]}

package/dist/index.d.cts

@@ -0,0 +1,21 @@
+import { Annotation } from '@useclickly/core';
+
+interface ServerOptions {
+    /** HTTP port for the browser bridge. Default: 4747. */
+    port?: number;
+    /** On-disk path for session persistence. Default: ~/.clickly/sessions.json. */
+    storePath?: string;
+}
+interface ServerHandle {
+    port: number;
+    close(): Promise<void>;
+    getAnnotations(sessionId: string): Annotation[];
+}
+/**
+ * Phase 2 stub. Real MCP wiring + HTTP/SSE bridge + tool definitions
+ * arrive after Phase 8 (output format) so we have a stable schema to
+ * advertise to MCP clients.
+ */
+declare function createServer(_options?: ServerOptions): Promise<ServerHandle>;
+
+export { type ServerOptions, createServer };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { Annotation } from '@useclickly/core';
+
+interface ServerOptions {
+    /** HTTP port for the browser bridge. Default: 4747. */
+    port?: number;
+    /** On-disk path for session persistence. Default: ~/.clickly/sessions.json. */
+    storePath?: string;
+}
+interface ServerHandle {
+    port: number;
+    close(): Promise<void>;
+    getAnnotations(sessionId: string): Annotation[];
+}
+/**
+ * Phase 2 stub. Real MCP wiring + HTTP/SSE bridge + tool definitions
+ * arrive after Phase 8 (output format) so we have a stable schema to
+ * advertise to MCP clients.
+ */
+declare function createServer(_options?: ServerOptions): Promise<ServerHandle>;
+
+export { type ServerOptions, createServer };

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// src/server.ts
+async function createServer(_options = {}) {
+  throw new Error("@useclickly/mcp-server: not yet implemented (Phase 2 scaffold)");
+}
+
+export { createServer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"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"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@useclickly/mcp-server",
+  "version": "0.2.0",
+  "description": "Model Context Protocol stdio server that exposes Clickly annotations to AI coding agents (Claude Code, Cursor, Codex, Windsurf).",
+  "license": "MIT",
+  "author": "Clickly contributors",
+  "homepage": "https://github.com/clickly/clickly#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clickly/clickly.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/clickly/clickly/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "clickly",
+    "claude",
+    "cursor",
+    "ai",
+    "agent"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "clickly-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@useclickly/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.10",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "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"
+  }
+}