comment-kit-mcp 0.1.0 → 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 +30 -31
- package/bin/comment-kit-mcp.js +5 -9
- package/dist/api-client.d.ts +14 -8
- package/dist/api-client.js +46 -35
- package/dist/format.d.ts +5 -0
- package/dist/format.js +3 -1
- package/dist/server.d.ts +4 -6
- package/dist/server.js +53 -47
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -22,26 +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
|
-
- `
|
|
26
|
-
- `
|
|
27
|
-
- `COMMENT_KIT_BASE_URL` — optional, defaults to `https://api.commentkit.dev/api`.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
the MCP host's configuration only to trusted local users. Leave
|
|
42
|
-
`COMMENTKIT_MACHINE_READ_ENABLED` off: the project key appears in browser code.
|
|
43
|
-
The server sends credentials only to the configured API origin; it refuses
|
|
44
|
-
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.
|
|
45
41
|
|
|
46
42
|
### Claude Desktop
|
|
47
43
|
|
|
@@ -54,9 +50,8 @@ non-HTTPS remote base URLs and HTTP redirects.
|
|
|
54
50
|
"command": "npx",
|
|
55
51
|
"args": ["-y", "comment-kit-mcp"],
|
|
56
52
|
"env": {
|
|
57
|
-
"
|
|
58
|
-
"
|
|
59
|
-
"COMMENT_KIT_ACCESS_TOKEN": "<SDK token from OTP verification>"
|
|
53
|
+
"COMMENT_KIT_PROJECT_ID": "42",
|
|
54
|
+
"COMMENT_KIT_ACCESS_TOKEN": "<project agent token>"
|
|
60
55
|
}
|
|
61
56
|
}
|
|
62
57
|
}
|
|
@@ -80,11 +75,11 @@ claude mcp add comment-kit -- npx -y comment-kit-mcp
|
|
|
80
75
|
|
|
81
76
|
## Tools
|
|
82
77
|
|
|
83
|
-
| Tool | Description
|
|
84
|
-
| ----------------- |
|
|
85
|
-
| `list_comments` | List comments. Filter by `status`, `branch`, `environment`, `page_path`, `priority`, `limit`. Defaults to open comments.
|
|
86
|
-
| `get_comment` | Fetch a comment and its full context by `commentId`; continue oversized JSON with `context_offset` and `snapshot_sha256`.
|
|
87
|
-
| `search_comments` | Search open content + replies, with optional `branch`, `environment`, and `page_path` filters.
|
|
78
|
+
| Tool | Description |
|
|
79
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
80
|
+
| `list_comments` | List comments. Filter by `status`, `branch`, `environment`, `page_path`, `priority`, `limit`, `cursor`. Defaults to open comments. |
|
|
81
|
+
| `get_comment` | Fetch a comment and its full context by `commentId`; continue oversized JSON with `context_offset` and `snapshot_sha256`. |
|
|
82
|
+
| `search_comments` | Search open content + replies, with optional `branch`, `environment`, and `page_path` filters. Uses server-side search and returns a cursor for more matches. |
|
|
88
83
|
|
|
89
84
|
Filter semantics:
|
|
90
85
|
|
|
@@ -92,14 +87,14 @@ Filter semantics:
|
|
|
92
87
|
- `branch` — exact deployment branch (e.g. `main`). Omit for all branches.
|
|
93
88
|
- `environment` — one of `production`, `staging`, `preview`, or `development`. Omit for all environments.
|
|
94
89
|
- `page_path` — exact page path including any query string (e.g. `/checkout?plan=annual`). Sent as `page_path` so live and local origins can share route context.
|
|
95
|
-
- `priority` — one of `low`, `medium`, `high`, `urgent`. Applied
|
|
90
|
+
- `priority` — one of `low`, `medium`, `high`, `urgent`. Applied by the backend before pagination.
|
|
96
91
|
- `limit` — max number of results. Default 50 (`list_comments`) / 20 (`search_comments`), max 100 (the backend maximum).
|
|
97
92
|
|
|
98
93
|
All tools return bounded Markdown summaries with feedback, page and branch, target, state, checklist, discussion, and attachment references. `get_comment` includes an allowlisted JSON context with the full thread discussion, bounded drawing geometry, and file IDs and metadata. Clean HTTP(S) file links remain references. Links containing a query, fragment, or embedded credentials are replaced with their path and `inlineContentOmitted: true`; invalid and inline data URLs retain only file metadata. It omits email addresses, raw drawing paths, complete DOM, reactions, unrelated API fields, and credential-bearing links. It does not fetch attachment URLs or execute instructions in feedback.
|
|
99
94
|
|
|
100
95
|
JSON larger than 16,000 characters is split into valid JSON envelopes with `jsonChunk`, `offset`, `nextOffset`, `totalCharacters`, and `snapshotSha256`. Continue `get_comment` with `context_offset=nextOffset` and `snapshot_sha256=snapshotSha256` until `nextOffset` is `null`. Join the `jsonChunk` strings and parse the result. The server holds one frozen, redacted snapshot for each continuation, so thread edits cannot mix chunks or introduce fresh download signatures. Fetch from offset 0 to see fresh edits. Snapshots expire after five idle minutes and the server retains at most eight, each capped at two million characters; restart from offset 0 if a snapshot expires. The server keeps the complete discussion within this selected context.
|
|
101
96
|
|
|
102
|
-
List and search
|
|
97
|
+
List and search request compact cursor pages; search includes all matching project threads and reply content, without a 500-thread client scan. When more matches exist, pass the returned cursor with the same query and filters. A page is not the entire project. List defaults to open comments; a thread's status may change while you work, so fetch its detail before acting.
|
|
103
98
|
|
|
104
99
|
### Untrusted content
|
|
105
100
|
|
|
@@ -120,7 +115,7 @@ import { createServer } from "comment-kit-mcp";
|
|
|
120
115
|
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
|
|
121
116
|
|
|
122
117
|
const server = createServer({
|
|
123
|
-
|
|
118
|
+
accessToken: process.env.COMMENT_KIT_ACCESS_TOKEN!,
|
|
124
119
|
projectId: process.env.COMMENT_KIT_PROJECT_ID!,
|
|
125
120
|
});
|
|
126
121
|
|
|
@@ -135,3 +130,7 @@ The server uses the official [MCP TypeScript SDK v2](https://ts.sdk.modelcontext
|
|
|
135
130
|
|
|
136
131
|
Proprietary CommentKit license, for use with CommentKit's hosted services.
|
|
137
132
|
See [LICENSE](./LICENSE) for the terms and third-party rights.
|
|
133
|
+
|
|
134
|
+
### Backend compatibility for cursor reads
|
|
135
|
+
|
|
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.
|
package/bin/comment-kit-mcp.js
CHANGED
|
@@ -1,21 +1,17 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// CLI entry:
|
|
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 (!
|
|
11
|
+
if (!accessToken || !projectId) {
|
|
14
12
|
process.stderr.write(
|
|
15
|
-
"comment-kit-mcp: missing
|
|
16
|
-
"
|
|
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({
|
|
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
|
);
|
package/dist/api-client.d.ts
CHANGED
|
@@ -59,6 +59,11 @@ export interface McpComment {
|
|
|
59
59
|
};
|
|
60
60
|
createdAt: string;
|
|
61
61
|
updatedAt: string;
|
|
62
|
+
repliesCount?: number;
|
|
63
|
+
repliesPagination?: {
|
|
64
|
+
hasMore: boolean;
|
|
65
|
+
nextCursor: string | null;
|
|
66
|
+
};
|
|
62
67
|
replies: Array<{
|
|
63
68
|
id: string;
|
|
64
69
|
content: string;
|
|
@@ -90,6 +95,9 @@ export interface ListCommentsOptions {
|
|
|
90
95
|
environment?: "production" | "staging" | "preview" | "development";
|
|
91
96
|
/** Exact page path filter — sent to the backend as `page_path`. */
|
|
92
97
|
pagePath?: string;
|
|
98
|
+
priority?: "low" | "medium" | "high" | "urgent";
|
|
99
|
+
search?: string;
|
|
100
|
+
cursor?: string;
|
|
93
101
|
limit?: number;
|
|
94
102
|
/** 1-based page number — sent to the backend as `page`. */
|
|
95
103
|
page?: number;
|
|
@@ -98,6 +106,7 @@ export interface CommentListResult {
|
|
|
98
106
|
comments: McpComment[];
|
|
99
107
|
/** Whether the backend reported more results beyond this page. */
|
|
100
108
|
hasMore: boolean;
|
|
109
|
+
nextCursor?: string | null;
|
|
101
110
|
}
|
|
102
111
|
/**
|
|
103
112
|
* Parse and validate a CommentKit base URL. Requires https: unless the host
|
|
@@ -107,18 +116,15 @@ export declare function validateBaseUrl(raw: string): string;
|
|
|
107
116
|
export declare function validateAccessToken(raw: string): string;
|
|
108
117
|
export declare class CommentKitApiClient {
|
|
109
118
|
private readonly baseUrl;
|
|
110
|
-
private readonly apiKey;
|
|
111
119
|
private readonly projectId;
|
|
112
120
|
private readonly accessToken;
|
|
113
121
|
constructor(options: {
|
|
114
122
|
baseUrl?: string;
|
|
115
|
-
|
|
123
|
+
/** Legacy option accepted but never transmitted. */
|
|
124
|
+
apiKey?: string;
|
|
116
125
|
projectId: string;
|
|
117
|
-
/**
|
|
118
|
-
|
|
119
|
-
* backend machine-read is enabled. Mutations still require Bearer.
|
|
120
|
-
*/
|
|
121
|
-
accessToken?: string;
|
|
126
|
+
/** Dedicated read-only project credential from Project → Installation. */
|
|
127
|
+
accessToken: string;
|
|
122
128
|
});
|
|
123
129
|
private request;
|
|
124
130
|
listComments(options?: ListCommentsOptions): Promise<CommentListResult>;
|
|
@@ -128,5 +134,5 @@ export declare class CommentKitApiClient {
|
|
|
128
134
|
* silently corrupting agent decisions on real-sized projects.
|
|
129
135
|
*/
|
|
130
136
|
listCommentsPaged(options?: Omit<ListCommentsOptions, "limit" | "page">, maxTotal?: number): Promise<CommentListResult>;
|
|
131
|
-
getComment(commentId: string): Promise<McpComment>;
|
|
137
|
+
getComment(commentId: string, repliesBefore?: string): Promise<McpComment>;
|
|
132
138
|
}
|
package/dist/api-client.js
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
// Minimal HTTP client
|
|
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(
|
|
26
|
+
throw new Error("Invalid CommentKit base URL: not a parseable URL.");
|
|
28
27
|
}
|
|
29
|
-
if (url.protocol !== "https:" &&
|
|
30
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
});
|
|
@@ -112,8 +101,14 @@ export class CommentKitApiClient {
|
|
|
112
101
|
return body;
|
|
113
102
|
}
|
|
114
103
|
async listComments(options = {}) {
|
|
115
|
-
const params = new URLSearchParams();
|
|
116
|
-
|
|
104
|
+
const params = new URLSearchParams({ view: "summary", pagination: "cursor" });
|
|
105
|
+
if (options.cursor)
|
|
106
|
+
params.set("cursor", options.cursor);
|
|
107
|
+
if (options.priority)
|
|
108
|
+
params.set("priority", options.priority);
|
|
109
|
+
if (options.search)
|
|
110
|
+
params.set("search", options.search);
|
|
111
|
+
// Cursor pagination is stable across insertions/deletions. page remains a legacy fallback.
|
|
117
112
|
if (options.pagePath)
|
|
118
113
|
params.set("page_path", options.pagePath);
|
|
119
114
|
if (options.branch)
|
|
@@ -129,11 +124,15 @@ export class CommentKitApiClient {
|
|
|
129
124
|
: MAX_LIMIT;
|
|
130
125
|
params.set("limit", String(safeLimit));
|
|
131
126
|
}
|
|
132
|
-
if (
|
|
127
|
+
if (!options.cursor &&
|
|
128
|
+
typeof options.page === "number" &&
|
|
129
|
+
Number.isFinite(options.page) &&
|
|
130
|
+
options.page > 1) {
|
|
131
|
+
params.delete("pagination");
|
|
133
132
|
params.set("page", String(Math.floor(options.page)));
|
|
134
133
|
}
|
|
135
134
|
const qs = params.toString();
|
|
136
|
-
const endpoint = `/projects/${encodePath(this.projectId)}/comments${qs ? `?${qs}` : ""}`;
|
|
135
|
+
const endpoint = `/agent/projects/${encodePath(this.projectId)}/comments${qs ? `?${qs}` : ""}`;
|
|
137
136
|
const data = await this.request(endpoint);
|
|
138
137
|
if (Array.isArray(data)) {
|
|
139
138
|
return { comments: data, hasMore: false };
|
|
@@ -142,6 +141,7 @@ export class CommentKitApiClient {
|
|
|
142
141
|
return {
|
|
143
142
|
comments: data.comments ?? [],
|
|
144
143
|
hasMore: data.pagination?.hasMore === true,
|
|
144
|
+
nextCursor: data.pagination?.nextCursor ?? null,
|
|
145
145
|
};
|
|
146
146
|
}
|
|
147
147
|
return { comments: [], hasMore: false };
|
|
@@ -155,15 +155,23 @@ export class CommentKitApiClient {
|
|
|
155
155
|
const collected = [];
|
|
156
156
|
let page = 1;
|
|
157
157
|
let hasMore = true;
|
|
158
|
+
let cursor;
|
|
159
|
+
const seenCursors = new Set();
|
|
158
160
|
// Hard cap on requests as a defense against a backend that always
|
|
159
161
|
// reports hasMore.
|
|
160
162
|
const maxPages = Math.max(1, Math.ceil(maxTotal / MAX_LIMIT));
|
|
161
163
|
while (collected.length < maxTotal && hasMore && page <= maxPages) {
|
|
162
|
-
const result = await this.listComments({ ...options, limit: MAX_LIMIT, page });
|
|
164
|
+
const result = await this.listComments({ ...options, limit: MAX_LIMIT, page, cursor });
|
|
163
165
|
collected.push(...result.comments);
|
|
164
166
|
hasMore = result.hasMore;
|
|
165
167
|
if (result.comments.length === 0)
|
|
166
168
|
break;
|
|
169
|
+
if (result.nextCursor) {
|
|
170
|
+
if (seenCursors.has(result.nextCursor))
|
|
171
|
+
break;
|
|
172
|
+
seenCursors.add(result.nextCursor);
|
|
173
|
+
cursor = result.nextCursor;
|
|
174
|
+
}
|
|
167
175
|
page += 1;
|
|
168
176
|
}
|
|
169
177
|
return {
|
|
@@ -171,8 +179,11 @@ export class CommentKitApiClient {
|
|
|
171
179
|
hasMore: hasMore || collected.length > maxTotal,
|
|
172
180
|
};
|
|
173
181
|
}
|
|
174
|
-
async getComment(commentId) {
|
|
175
|
-
const
|
|
182
|
+
async getComment(commentId, repliesBefore) {
|
|
183
|
+
const params = new URLSearchParams({ replies_limit: "100" });
|
|
184
|
+
if (repliesBefore)
|
|
185
|
+
params.set("replies_before", repliesBefore);
|
|
186
|
+
const data = await this.request(`/agent/projects/${encodePath(this.projectId)}/comments/${encodePath(commentId)}?${params}`);
|
|
176
187
|
// The backend wraps the comment: `{ "success": true, "comment": {...} }`.
|
|
177
188
|
// Unwrap it (with a legacy fallback for a bare comment object).
|
|
178
189
|
if (data && typeof data === "object" && "comment" in data && data.comment) {
|
package/dist/format.d.ts
CHANGED
|
@@ -60,6 +60,11 @@ export declare function toAgentComment(comment: McpComment): {
|
|
|
60
60
|
mimeType?: string | undefined;
|
|
61
61
|
size?: number | undefined;
|
|
62
62
|
}[];
|
|
63
|
+
repliesPagination?: {
|
|
64
|
+
hasMore: boolean;
|
|
65
|
+
nextCursor: string | null;
|
|
66
|
+
} | undefined;
|
|
67
|
+
repliesCount?: number | undefined;
|
|
63
68
|
replies: {
|
|
64
69
|
id: string;
|
|
65
70
|
content: string;
|
package/dist/format.js
CHANGED
|
@@ -131,6 +131,8 @@ export function toAgentComment(comment) {
|
|
|
131
131
|
? { checklist: comment.checklist.map(({ label, done }) => ({ label, done })) }
|
|
132
132
|
: {}),
|
|
133
133
|
attachments: attachments(comment.attachments),
|
|
134
|
+
...(comment.repliesPagination ? { repliesPagination: comment.repliesPagination } : {}),
|
|
135
|
+
...(comment.repliesCount !== undefined ? { repliesCount: comment.repliesCount } : {}),
|
|
134
136
|
replies: (comment.replies ?? []).map((reply) => ({
|
|
135
137
|
id: reply.id,
|
|
136
138
|
content: reply.content,
|
|
@@ -206,7 +208,7 @@ export function summarizeComment(comment) {
|
|
|
206
208
|
`- Page: ${pageTitle ? untrusted(pageTitle) : "(untitled)"} — ${pageLocation ? untrusted(pageLocation) : "(unknown)"}`,
|
|
207
209
|
`- Selector: ${element ? untrusted(element) : "none"}`,
|
|
208
210
|
`- XPath: ${xpath ? untrusted(xpath) : "none"}`,
|
|
209
|
-
`- Replies: ${replies.length}`,
|
|
211
|
+
`- Replies: ${comment.repliesCount ?? replies.length}${comment.repliesCount !== undefined && comment.repliesCount > replies.length ? ` (${replies.length} included; fetch get_comment for details)` : ""}`,
|
|
210
212
|
assignees.length
|
|
211
213
|
? `- Assignees (${assignees.length}): ${assignees
|
|
212
214
|
.slice(0, MAX_SUMMARY_ITEMS)
|
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
|
-
|
|
4
|
+
/** Legacy option, no longer sent by the client. */
|
|
5
|
+
apiKey?: string;
|
|
5
6
|
projectId: string;
|
|
6
|
-
/**
|
|
7
|
-
|
|
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
|
@@ -7,9 +7,6 @@ const STATUS_VALUES = ["open", "resolved", "complete", "all"];
|
|
|
7
7
|
const ENVIRONMENT_VALUES = ["production", "staging", "preview", "development"];
|
|
8
8
|
const PRIORITY_VALUES = ["low", "medium", "high", "urgent"];
|
|
9
9
|
const MAX_LIMIT = 100; // backend max per page
|
|
10
|
-
// Cap on paged scans (search / client-side priority filtering): 5 backend
|
|
11
|
-
// requests of MAX_LIMIT each.
|
|
12
|
-
const SCAN_CAP = 500;
|
|
13
10
|
const SNAPSHOT_TTL_MS = 5 * 60_000;
|
|
14
11
|
const MAX_SNAPSHOTS = 8;
|
|
15
12
|
const MAX_SNAPSHOT_CHARACTERS = 2_000_000;
|
|
@@ -22,11 +19,23 @@ const listSchema = z.strictObject({
|
|
|
22
19
|
page_path: z.string().trim().max(2048).optional().describe("Exact page path, including query"),
|
|
23
20
|
branch: z.string().trim().max(255).optional().describe("Exact deployment branch"),
|
|
24
21
|
environment: z.enum(ENVIRONMENT_VALUES).optional(),
|
|
25
|
-
priority: z.enum(PRIORITY_VALUES).optional().describe("
|
|
22
|
+
priority: z.enum(PRIORITY_VALUES).optional().describe("Exact server-side priority filter"),
|
|
26
23
|
limit: z.number().int().min(1).max(MAX_LIMIT).optional(),
|
|
24
|
+
cursor: z
|
|
25
|
+
.string()
|
|
26
|
+
.trim()
|
|
27
|
+
.min(1)
|
|
28
|
+
.max(2048)
|
|
29
|
+
.optional()
|
|
30
|
+
.describe("nextCursor from the previous result; keep all filters unchanged"),
|
|
27
31
|
});
|
|
28
32
|
const getSchema = z.strictObject({
|
|
29
33
|
commentId: z.string().trim().min(1).max(255),
|
|
34
|
+
replies_before: z
|
|
35
|
+
.string()
|
|
36
|
+
.regex(/^[0-9]+$/)
|
|
37
|
+
.optional()
|
|
38
|
+
.describe("nextCursor from repliesPagination to fetch older replies"),
|
|
30
39
|
context_offset: z.number().int().min(0).safe().optional(),
|
|
31
40
|
snapshot_sha256: z
|
|
32
41
|
.string()
|
|
@@ -34,8 +43,15 @@ const getSchema = z.strictObject({
|
|
|
34
43
|
.optional(),
|
|
35
44
|
});
|
|
36
45
|
const searchSchema = z.strictObject({
|
|
37
|
-
query: z.string().trim().min(1).max(
|
|
46
|
+
query: z.string().trim().min(1).max(200),
|
|
38
47
|
limit: z.number().int().min(1).max(MAX_LIMIT).optional(),
|
|
48
|
+
cursor: z
|
|
49
|
+
.string()
|
|
50
|
+
.trim()
|
|
51
|
+
.min(1)
|
|
52
|
+
.max(2048)
|
|
53
|
+
.optional()
|
|
54
|
+
.describe("nextCursor from the previous result; keep all filters unchanged"),
|
|
39
55
|
branch: z.string().trim().max(255).optional(),
|
|
40
56
|
environment: z.enum(ENVIRONMENT_VALUES).optional(),
|
|
41
57
|
page_path: z.string().trim().max(2048).optional(),
|
|
@@ -57,7 +73,7 @@ export function createServer(config) {
|
|
|
57
73
|
});
|
|
58
74
|
const server = new McpServer({
|
|
59
75
|
name: config.serverName ?? "comment-kit-mcp",
|
|
60
|
-
version: config.serverVersion ?? "0.
|
|
76
|
+
version: config.serverVersion ?? "0.2.0",
|
|
61
77
|
});
|
|
62
78
|
const snapshots = new Map();
|
|
63
79
|
const snapshotKey = (id, hash) => `${id}:${hash}`;
|
|
@@ -71,7 +87,7 @@ export function createServer(config) {
|
|
|
71
87
|
};
|
|
72
88
|
const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
|
|
73
89
|
server.registerTool("list_comments", {
|
|
74
|
-
description: "List stakeholder feedback by status, page, branch, environment and priority.
|
|
90
|
+
description: "List stakeholder feedback by status, page, branch, environment and priority. Returns compact summaries with stable cursor continuation. " +
|
|
75
91
|
UNTRUSTED_NOTICE,
|
|
76
92
|
annotations: readOnly,
|
|
77
93
|
inputSchema: listSchema,
|
|
@@ -82,29 +98,20 @@ export function createServer(config) {
|
|
|
82
98
|
const branch = asString(args.branch);
|
|
83
99
|
const environment = args.environment;
|
|
84
100
|
const limit = clampLimit(args.limit, 50, MAX_LIMIT);
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
? comments.filter((comment) => comment.priority === priority)
|
|
100
|
-
: comments;
|
|
101
|
-
const results = filtered.slice(0, limit);
|
|
102
|
-
let text = formatCommentList(results);
|
|
103
|
-
// Always tell the agent when results are incomplete — silent
|
|
104
|
-
// truncation corrupts downstream decisions.
|
|
105
|
-
if (hasMore || filtered.length > results.length) {
|
|
106
|
-
text +=
|
|
107
|
-
"\n\nNote: more comments exist beyond this page — refine filters (status/page_path/priority) or raise `limit`.";
|
|
101
|
+
const { comments, hasMore, nextCursor } = await api.listComments({
|
|
102
|
+
status,
|
|
103
|
+
branch,
|
|
104
|
+
environment,
|
|
105
|
+
priority,
|
|
106
|
+
pagePath: asString(args.page_path),
|
|
107
|
+
limit,
|
|
108
|
+
cursor: args.cursor,
|
|
109
|
+
});
|
|
110
|
+
let text = formatCommentList(comments);
|
|
111
|
+
if (hasMore) {
|
|
112
|
+
text += nextCursor
|
|
113
|
+
? `\n\nMore results. Call list_comments with the same filters and cursor: ${JSON.stringify(nextCursor)}`
|
|
114
|
+
: "\n\nMore results exist. This backend did not provide a cursor; refine filters or upgrade the backend.";
|
|
108
115
|
}
|
|
109
116
|
return { content: [{ type: "text", text }] };
|
|
110
117
|
}
|
|
@@ -113,7 +120,7 @@ export function createServer(config) {
|
|
|
113
120
|
}
|
|
114
121
|
});
|
|
115
122
|
server.registerTool("get_comment", {
|
|
116
|
-
description: "Fetch one thread with useful target, state, replies and file references. Large context uses nextOffset continuation with snapshot_sha256. " +
|
|
123
|
+
description: "Fetch one thread with useful target, state, replies and file references. Fetches at most 100 replies; use replies_before from repliesPagination for older replies. Large context uses nextOffset continuation with snapshot_sha256. " +
|
|
117
124
|
UNTRUSTED_NOTICE,
|
|
118
125
|
annotations: readOnly,
|
|
119
126
|
inputSchema: getSchema,
|
|
@@ -135,7 +142,7 @@ export function createServer(config) {
|
|
|
135
142
|
snapshot = entry.value;
|
|
136
143
|
}
|
|
137
144
|
else {
|
|
138
|
-
snapshot = createCommentDetailSnapshot(await api.getComment(id));
|
|
145
|
+
snapshot = createCommentDetailSnapshot(await api.getComment(id, args.replies_before));
|
|
139
146
|
if (snapshot.serialized.length > MAX_SNAPSHOT_CHARACTERS)
|
|
140
147
|
throw new Error("Comment context exceeds the 2 million character snapshot limit");
|
|
141
148
|
if (snapshot.serialized.length > 16_000) {
|
|
@@ -160,7 +167,7 @@ export function createServer(config) {
|
|
|
160
167
|
}
|
|
161
168
|
});
|
|
162
169
|
server.registerTool("search_comments", {
|
|
163
|
-
description: "Search open feedback and replies, with optional branch, environment and exact page filters.
|
|
170
|
+
description: "Search open feedback and replies, with optional branch, environment and exact page filters. Search runs across all matching threads on the server; results have cursor continuation. " +
|
|
164
171
|
UNTRUSTED_NOTICE,
|
|
165
172
|
annotations: readOnly,
|
|
166
173
|
inputSchema: searchSchema,
|
|
@@ -170,21 +177,20 @@ export function createServer(config) {
|
|
|
170
177
|
const limit = clampLimit(args.limit, 20, MAX_LIMIT);
|
|
171
178
|
const branch = asString(args.branch);
|
|
172
179
|
const environment = args.environment;
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
return (comment.replies ?? []).some((reply) => (reply?.content ?? "").toLowerCase().includes(needle));
|
|
180
|
+
const { comments, hasMore, nextCursor } = await api.listComments({
|
|
181
|
+
status: "open",
|
|
182
|
+
branch,
|
|
183
|
+
environment,
|
|
184
|
+
pagePath: asString(args.page_path),
|
|
185
|
+
search: query,
|
|
186
|
+
limit,
|
|
187
|
+
cursor: args.cursor,
|
|
182
188
|
});
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
189
|
+
let text = formatCommentList(comments);
|
|
190
|
+
if (hasMore) {
|
|
191
|
+
text += nextCursor
|
|
192
|
+
? `\n\nMore matches. Call search_comments with the same query and filters and cursor: ${JSON.stringify(nextCursor)}`
|
|
193
|
+
: "\n\nMore matches exist. This backend did not provide a cursor; refine filters or upgrade the backend.";
|
|
188
194
|
}
|
|
189
195
|
return { content: [{ type: "text", text }] };
|
|
190
196
|
}
|