comment-kit-mcp 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,28 +22,22 @@ Contributors using the repository can run `npm ci --prefix mcp` and
22
22
 
23
23
  Add the server to your agent's MCP config. The server reads these environment variables:
24
24
 
25
- - `COMMENT_KIT_API_KEY` — required, your project API key
26
- - `COMMENT_KIT_PROJECT_ID` — required, the project **slug** used by `/api/projects/{slug}`
27
- - `COMMENT_KIT_BASE_URL` — optional, defaults to `https://api.commentkit.dev/api`. Must be an `https://` URL (plain `http://` is only allowed for localhost/loopback hosts); the server refuses to start otherwise.
28
- - `COMMENT_KIT_ACCESS_TOKEN` — SDK Bearer token with the `sdk` ability. Required by the private production default. A project API key alone does not grant access to private comments.
29
-
30
- Create the project key and slug in CommentKit. A member of that project's team
31
- can obtain the supported SDK token through the OTP flow:
32
-
33
- 1. `POST /api/auth/otp/request` with header `X-API-Key: <project key>` and JSON `{"email":"<team member email>"}`. The backend emails a short-lived code to that member.
34
- 2. `POST /api/auth/otp/verify` with the same header and JSON `{"email":"<team member email>","otp":"<six-digit code>"}`.
35
- 3. If the response has `mfaRequired: true`, it does not contain an authenticated session. Complete `POST /api/auth/mfa/verify` with the same `X-API-Key` header and JSON `{"challenge":"<challenge from the response>","code":"<authenticator or unused recovery code>"}`. The challenge expires after five minutes and can be completed once; restart email sign-in if it expires.
36
- 4. Only after a response confirms `verified: true` and supplies a `token`, save that token as `COMMENT_KIT_ACCESS_TOKEN` in your private local MCP host configuration. Keep email codes, second-factor proofs and challenge values out of project files and agent prompts.
37
-
38
- The default SDK token expires after 30 days; re-run OTP verification when it
39
- expires. Revoke it at dashboard **Settings → Sessions**, or ask an administrator
40
- to revoke it. This token carries the SDK's `sdk` ability, which can also write
41
- comments outside this read-only MCP process. The backend does not currently
42
- issue a narrower read-only machine token, so keep the token private and grant
43
- the MCP host's configuration only to trusted local users. Leave
44
- `COMMENTKIT_MACHINE_READ_ENABLED` off: the project key appears in browser code.
45
- The server sends credentials only to the configured API origin; it refuses
46
- non-HTTPS remote base URLs and HTTP redirects.
25
+ - `COMMENT_KIT_PROJECT_ID` — required, the numeric project ID shown in **Project → Installation**.
26
+ - `COMMENT_KIT_ACCESS_TOKEN` — required, a dedicated read-only agent token created in that project's Installation screen. SDK sign-in tokens are not accepted.
27
+ - `COMMENT_KIT_BASE_URL` — optional, defaults to `https://api.commentkit.dev/api`. Remote URLs must use HTTPS; plain HTTP is allowed only on loopback.
28
+
29
+ Workspace members can create an agent token after signing in to the dashboard.
30
+ It grants reads for one project, expires after 30 days, and is shown only once.
31
+ Save it in your private local MCP host configuration. Revoke it from Installation
32
+ or account token settings. Project reviewers cannot issue or use agent tokens.
33
+ Removing the user's workspace membership also stops agent reads immediately.
34
+
35
+ This version uses `/api/agent/projects/{id}/comments`; it requires the backend
36
+ release with dedicated agent credentials. It does not fall back to SDK or public
37
+ API-key authentication. Existing MCP configurations must replace their SDK token
38
+ and slug with an agent token and numeric project ID. The public project key is
39
+ no longer required or transmitted. Keep credentials out of source files and
40
+ agent prompts. HTTP redirects are refused.
47
41
 
48
42
  ### Claude Desktop
49
43
 
@@ -56,9 +50,8 @@ non-HTTPS remote base URLs and HTTP redirects.
56
50
  "command": "npx",
57
51
  "args": ["-y", "comment-kit-mcp"],
58
52
  "env": {
59
- "COMMENT_KIT_API_KEY": "ck_...",
60
- "COMMENT_KIT_PROJECT_ID": "your-project-slug",
61
- "COMMENT_KIT_ACCESS_TOKEN": "<SDK token from OTP verification>"
53
+ "COMMENT_KIT_PROJECT_ID": "42",
54
+ "COMMENT_KIT_ACCESS_TOKEN": "<project agent token>"
62
55
  }
63
56
  }
64
57
  }
@@ -122,7 +115,7 @@ import { createServer } from "comment-kit-mcp";
122
115
  import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
123
116
 
124
117
  const server = createServer({
125
- apiKey: process.env.COMMENT_KIT_API_KEY!,
118
+ accessToken: process.env.COMMENT_KIT_ACCESS_TOKEN!,
126
119
  projectId: process.env.COMMENT_KIT_PROJECT_ID!,
127
120
  });
128
121
 
@@ -140,4 +133,4 @@ See [LICENSE](./LICENSE) for the terms and third-party rights.
140
133
 
141
134
  ### Backend compatibility for cursor reads
142
135
 
143
- MCP 0.1.1 requires the audit-hardening backend. Deploy and verify that backend before promoting this MCP update to `latest`. List calls request `view=summary&pagination=cursor`; search and priority filters run on the server. Thread reads request up to 100 replies and expose `repliesPagination`. For older replies, call `get_comment` with `replies_before` set to its next cursor. This is separate from `context_offset`/`snapshot_sha256`, which paginate a frozen JSON context when its text is large. Repeat detail reads before changing code if feedback may have changed.
136
+ MCP 0.2.0 requires the project-reviewer backend with dedicated agent credentials. This is a breaking configuration change from 0.1.x: replace the SDK token and project slug together with a dedicated agent token and numeric project ID. Deploy and verify that backend before promoting this MCP update to `latest`. List calls request `view=summary&pagination=cursor`; search and priority filters run on the server. Thread reads request up to 100 replies and expose `repliesPagination`. For older replies, call `get_comment` with `replies_before` set to its next cursor. This is separate from `context_offset`/`snapshot_sha256`, which paginate a frozen JSON context when its text is large. Repeat detail reads before changing code if feedback may have changed.
@@ -1,21 +1,17 @@
1
1
  #!/usr/bin/env node
2
- // CLI entry: reads COMMENT_KIT_API_KEY + COMMENT_KIT_PROJECT_ID from env
3
- // (optional COMMENT_KIT_ACCESS_TOKEN) and starts a stdio MCP server.
2
+ // CLI entry: a project ID and dedicated read-only agent token are required.
4
3
 
5
4
  import { readFileSync } from "node:fs";
6
5
  import { run, validateAccessToken, validateBaseUrl } from "../dist/index.js";
7
6
 
8
- const apiKey = process.env.COMMENT_KIT_API_KEY;
9
7
  const projectId = process.env.COMMENT_KIT_PROJECT_ID;
10
8
  const accessToken = process.env.COMMENT_KIT_ACCESS_TOKEN;
11
9
  const baseUrl = process.env.COMMENT_KIT_BASE_URL;
12
10
 
13
- if (!apiKey || !projectId) {
11
+ if (!accessToken || !projectId) {
14
12
  process.stderr.write(
15
- "comment-kit-mcp: missing COMMENT_KIT_API_KEY and/or COMMENT_KIT_PROJECT_ID.\n" +
16
- "Comment reads use API-key-only machine auth when the backend enables it.\n" +
17
- "Optional COMMENT_KIT_ACCESS_TOKEN (Sanctum Bearer, sdk ability) for deployments\n" +
18
- "that disable machine read. Never use X-User-Email.\n" +
13
+ "comment-kit-mcp: missing COMMENT_KIT_ACCESS_TOKEN and/or COMMENT_KIT_PROJECT_ID.\n" +
14
+ "Create a read-only agent token in Project → Installation. SDK tokens and public API keys are not agent credentials.\n" +
19
15
  "See https://github.com/commentkit/comment-kit/tree/main/mcp\n",
20
16
  );
21
17
  process.exit(1);
@@ -51,7 +47,7 @@ try {
51
47
  // Fall back to the server's built-in default.
52
48
  }
53
49
 
54
- run({ apiKey, projectId, accessToken, baseUrl, serverVersion }).catch((error) => {
50
+ run({ projectId, accessToken, baseUrl, serverVersion }).catch((error) => {
55
51
  process.stderr.write(
56
52
  `comment-kit-mcp: fatal: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
57
53
  );
@@ -116,18 +116,15 @@ export declare function validateBaseUrl(raw: string): string;
116
116
  export declare function validateAccessToken(raw: string): string;
117
117
  export declare class CommentKitApiClient {
118
118
  private readonly baseUrl;
119
- private readonly apiKey;
120
119
  private readonly projectId;
121
120
  private readonly accessToken;
122
121
  constructor(options: {
123
122
  baseUrl?: string;
124
- apiKey: string;
123
+ /** Legacy option accepted but never transmitted. */
124
+ apiKey?: string;
125
125
  projectId: string;
126
- /**
127
- * Optional Bearer token. Comment **reads** work with API key alone when
128
- * backend machine-read is enabled. Mutations still require Bearer.
129
- */
130
- accessToken?: string;
126
+ /** Dedicated read-only project credential from Project → Installation. */
127
+ accessToken: string;
131
128
  });
132
129
  private request;
133
130
  listComments(options?: ListCommentsOptions): Promise<CommentListResult>;
@@ -1,5 +1,4 @@
1
- // Minimal HTTP client against the CommentKit API. Mirrors the project endpoints
2
- // the browser SDK uses, but only the read paths needed by the MCP server.
1
+ // Minimal HTTP client for the dedicated project-scoped agent read endpoints.
3
2
  // Includes the backend's /api route prefix (kept in sync with the SDK client).
4
3
  const DEFAULT_BASE_URL = "https://api.commentkit.dev/api";
5
4
  const MAX_LIMIT = 100; // backend max, matching the core SDK client
@@ -24,20 +23,18 @@ export function validateBaseUrl(raw) {
24
23
  url = new URL(raw);
25
24
  }
26
25
  catch {
27
- throw new Error(`Invalid CommentKit base URL "${raw}": not a parseable URL.`);
26
+ throw new Error("Invalid CommentKit base URL: not a parseable URL.");
28
27
  }
29
- if (url.protocol !== "https:" && !isLoopbackHostname(url.hostname)) {
30
- throw new Error(`Invalid CommentKit base URL "${raw}": must use https:// (plain http is only allowed for localhost/loopback hosts).`);
28
+ if (url.protocol !== "https:" &&
29
+ !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) {
30
+ throw new Error("Invalid CommentKit base URL: must use https:// (plain http is only allowed for localhost/loopback hosts).");
31
+ }
32
+ if (url.username || url.password || url.search || url.hash) {
33
+ throw new Error("Invalid CommentKit base URL: credentials, query strings and fragments are not allowed.");
31
34
  }
32
35
  return url.toString().replace(/\/+$/, "");
33
36
  }
34
- /**
35
- * Optional Sanctum Bearer token (ability `sdk`). Not required for MCP comment
36
- * reads when backend `COMMENTKIT_MACHINE_READ_ENABLED` is on (API-key-only GET).
37
- * Still preferred for deployments that disable machine read.
38
- *
39
- * Intentionally does **not** support `X-User-Email` (spoofable; gated off in prod).
40
- */
37
+ /** Never accept header delimiters in the dedicated project agent credential. */
41
38
  function containsLineBreakOrNull(value) {
42
39
  for (let index = 0; index < value.length; index += 1) {
43
40
  const code = value.charCodeAt(index);
@@ -48,44 +45,36 @@ function containsLineBreakOrNull(value) {
48
45
  return false;
49
46
  }
50
47
  export function validateAccessToken(raw) {
51
- const token = raw.trim();
48
+ const token = typeof raw === "string" ? raw.trim() : "";
52
49
  if (!token || token.length > 4096 || containsLineBreakOrNull(token)) {
53
- throw new Error("Invalid COMMENT_KIT_ACCESS_TOKEN: must be a non-empty Sanctum Bearer token (sdk ability).");
50
+ throw new Error("Invalid COMMENT_KIT_ACCESS_TOKEN: must be a non-empty project-scoped agent read token.");
54
51
  }
55
52
  return token;
56
53
  }
57
54
  export class CommentKitApiClient {
58
55
  baseUrl;
59
- apiKey;
60
56
  projectId;
61
57
  accessToken;
62
58
  constructor(options) {
63
59
  this.baseUrl = validateBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
64
- this.apiKey = options.apiKey;
60
+ if (!/^[1-9][0-9]*$/.test(options.projectId)) {
61
+ throw new Error("Invalid COMMENT_KIT_PROJECT_ID: use the numeric project ID from Installation.");
62
+ }
65
63
  this.projectId = options.projectId;
66
- this.accessToken =
67
- options.accessToken && options.accessToken.trim()
68
- ? validateAccessToken(options.accessToken)
69
- : null;
64
+ this.accessToken = validateAccessToken(options.accessToken);
70
65
  }
71
66
  async request(endpoint) {
72
67
  const url = `${this.baseUrl}${endpoint}`;
73
68
  const headers = {
74
- "x-api-key": this.apiKey,
75
69
  accept: "application/json",
76
70
  };
77
- // Prefer Bearer when provided; never send X-User-Email.
78
- if (this.accessToken) {
79
- headers.authorization = `Bearer ${this.accessToken}`;
80
- }
71
+ headers.authorization = `Bearer ${this.accessToken}`;
81
72
  let response;
82
73
  try {
83
74
  response = await fetch(url, {
84
75
  method: "GET",
85
76
  headers,
86
- // Never follow redirects: undici strips `authorization` on
87
- // cross-origin redirects but NOT custom headers, so a compromised /
88
- // open-redirecting backend could otherwise exfiltrate the API key.
77
+ // Credentials stay bound to the configured server; no redirected request.
89
78
  redirect: "error",
90
79
  signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
91
80
  });
@@ -143,7 +132,7 @@ export class CommentKitApiClient {
143
132
  params.set("page", String(Math.floor(options.page)));
144
133
  }
145
134
  const qs = params.toString();
146
- const endpoint = `/projects/${encodePath(this.projectId)}/comments${qs ? `?${qs}` : ""}`;
135
+ const endpoint = `/agent/projects/${encodePath(this.projectId)}/comments${qs ? `?${qs}` : ""}`;
147
136
  const data = await this.request(endpoint);
148
137
  if (Array.isArray(data)) {
149
138
  return { comments: data, hasMore: false };
@@ -194,7 +183,7 @@ export class CommentKitApiClient {
194
183
  const params = new URLSearchParams({ replies_limit: "100" });
195
184
  if (repliesBefore)
196
185
  params.set("replies_before", repliesBefore);
197
- const data = await this.request(`/projects/${encodePath(this.projectId)}/comments/${encodePath(commentId)}?${params}`);
186
+ const data = await this.request(`/agent/projects/${encodePath(this.projectId)}/comments/${encodePath(commentId)}?${params}`);
198
187
  // The backend wraps the comment: `{ "success": true, "comment": {...} }`.
199
188
  // Unwrap it (with a legacy fallback for a bare comment object).
200
189
  if (data && typeof data === "object" && "comment" in data && data.comment) {
package/dist/server.d.ts CHANGED
@@ -1,13 +1,11 @@
1
1
  import { McpServer } from "@modelcontextprotocol/server";
2
2
  export interface ServerConfig {
3
3
  baseUrl?: string;
4
- apiKey: string;
4
+ /** Legacy option, no longer sent by the client. */
5
+ apiKey?: string;
5
6
  projectId: string;
6
- /**
7
- * Optional Sanctum Bearer (`sdk`). Comment **reads** work with API key alone
8
- * when backend `COMMENTKIT_MACHINE_READ_ENABLED` is on. Do not use X-User-Email.
9
- */
10
- accessToken?: string;
7
+ /** Dedicated read-only project credential; SDK session tokens are not accepted. */
8
+ accessToken: string;
11
9
  serverName?: string;
12
10
  serverVersion?: string;
13
11
  }
package/dist/server.js CHANGED
@@ -73,7 +73,7 @@ export function createServer(config) {
73
73
  });
74
74
  const server = new McpServer({
75
75
  name: config.serverName ?? "comment-kit-mcp",
76
- version: config.serverVersion ?? "0.1.1",
76
+ version: config.serverVersion ?? "0.2.0",
77
77
  });
78
78
  const snapshots = new Map();
79
79
  const snapshotKey = (id, hash) => `${id}:${hash}`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "comment-kit-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Model Context Protocol server for CommentKit — expose stakeholder comments to your coding agent.",
5
5
  "keywords": [
6
6
  "agent",