@productbrain/mcp 0.0.1-beta.2 → 0.0.1-beta.21
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/.env.mcp.example +8 -13
- package/dist/chunk-CXYNWTRQ.js +1425 -0
- package/dist/chunk-CXYNWTRQ.js.map +1 -0
- package/dist/chunk-N47IMYAQ.js +4546 -0
- package/dist/chunk-N47IMYAQ.js.map +1 -0
- package/dist/chunk-XBMI6QHR.js +100 -0
- package/dist/chunk-XBMI6QHR.js.map +1 -0
- package/dist/cli/index.js +1 -1
- package/dist/http.js +374 -0
- package/dist/http.js.map +1 -0
- package/dist/index.js +46 -4222
- package/dist/index.js.map +1 -1
- package/dist/setup-GZ5OZ5OP.js +365 -0
- package/dist/setup-GZ5OZ5OP.js.map +1 -0
- package/dist/smart-capture-2N7E4OAJ.js +14 -0
- package/package.json +5 -1
- package/dist/chunk-DGUM43GV.js +0 -11
- package/dist/setup-V6HIAYXL.js +0 -227
- package/dist/setup-V6HIAYXL.js.map +0 -1
- /package/dist/{chunk-DGUM43GV.js.map → smart-capture-2N7E4OAJ.js.map} +0 -0
package/dist/index.js
CHANGED
|
@@ -1,4169 +1,30 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import
|
|
2
|
+
import {
|
|
3
|
+
SERVER_VERSION,
|
|
4
|
+
createProductBrainServer
|
|
5
|
+
} from "./chunk-N47IMYAQ.js";
|
|
6
|
+
import {
|
|
7
|
+
bootstrap,
|
|
8
|
+
getAgentSessionId,
|
|
9
|
+
getWorkspaceId,
|
|
10
|
+
orphanAgentSession,
|
|
11
|
+
recoverSessionState,
|
|
12
|
+
startAgentSession
|
|
13
|
+
} from "./chunk-CXYNWTRQ.js";
|
|
14
|
+
import {
|
|
15
|
+
initAnalytics,
|
|
16
|
+
shutdownAnalytics,
|
|
17
|
+
trackSessionStarted
|
|
18
|
+
} from "./chunk-XBMI6QHR.js";
|
|
3
19
|
|
|
4
20
|
// src/index.ts
|
|
5
|
-
import { readFileSync
|
|
6
|
-
import { resolve as resolve3 } from "path";
|
|
7
|
-
import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
8
|
-
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
9
|
-
|
|
10
|
-
// src/tools/knowledge.ts
|
|
11
|
-
import { z } from "zod";
|
|
12
|
-
|
|
13
|
-
// src/analytics.ts
|
|
14
|
-
import { userInfo } from "os";
|
|
15
|
-
import { PostHog } from "posthog-node";
|
|
16
|
-
var client = null;
|
|
17
|
-
var distinctId = "anonymous";
|
|
18
|
-
var POSTHOG_HOST = "https://eu.i.posthog.com";
|
|
19
|
-
function log(msg) {
|
|
20
|
-
if (process.env.MCP_DEBUG === "1") {
|
|
21
|
-
process.stderr.write(msg);
|
|
22
|
-
}
|
|
23
|
-
}
|
|
24
|
-
function initAnalytics() {
|
|
25
|
-
const apiKey = process.env.POSTHOG_MCP_KEY || "";
|
|
26
|
-
if (!apiKey) {
|
|
27
|
-
log("[MCP-ANALYTICS] No PostHog key \u2014 tracking disabled (set SYNERGYOS_POSTHOG_KEY at build time for publish)\n");
|
|
28
|
-
return;
|
|
29
|
-
}
|
|
30
|
-
client = new PostHog(apiKey, {
|
|
31
|
-
host: POSTHOG_HOST,
|
|
32
|
-
flushAt: 1,
|
|
33
|
-
flushInterval: 5e3
|
|
34
|
-
});
|
|
35
|
-
distinctId = process.env.MCP_USER_ID || fallbackDistinctId();
|
|
36
|
-
log(`[MCP-ANALYTICS] Initialized \u2014 host=${POSTHOG_HOST} distinctId=${distinctId}
|
|
37
|
-
`);
|
|
38
|
-
}
|
|
39
|
-
function fallbackDistinctId() {
|
|
40
|
-
try {
|
|
41
|
-
return userInfo().username;
|
|
42
|
-
} catch {
|
|
43
|
-
return `os-${process.pid}`;
|
|
44
|
-
}
|
|
45
|
-
}
|
|
46
|
-
function trackSessionStarted(workspaceSlug, workspaceId2, serverVersion) {
|
|
47
|
-
if (!client) return;
|
|
48
|
-
client.capture({
|
|
49
|
-
distinctId,
|
|
50
|
-
event: "mcp_session_started",
|
|
51
|
-
properties: {
|
|
52
|
-
workspace_slug: workspaceSlug,
|
|
53
|
-
workspace_id: workspaceId2,
|
|
54
|
-
server_version: serverVersion,
|
|
55
|
-
source: "mcp-server",
|
|
56
|
-
$groups: { workspace: workspaceId2 }
|
|
57
|
-
}
|
|
58
|
-
});
|
|
59
|
-
}
|
|
60
|
-
function trackToolCall(fn, status, durationMs, workspaceId2, errorMsg) {
|
|
61
|
-
const properties = {
|
|
62
|
-
tool: fn,
|
|
63
|
-
status,
|
|
64
|
-
duration_ms: durationMs,
|
|
65
|
-
workspace_slug: process.env.WORKSPACE_SLUG ?? "unknown",
|
|
66
|
-
source: "mcp-server",
|
|
67
|
-
$groups: { workspace: workspaceId2 }
|
|
68
|
-
};
|
|
69
|
-
if (errorMsg) properties.error = errorMsg;
|
|
70
|
-
if (!client) return;
|
|
71
|
-
client.capture({
|
|
72
|
-
distinctId,
|
|
73
|
-
event: "mcp_tool_called",
|
|
74
|
-
properties
|
|
75
|
-
});
|
|
76
|
-
}
|
|
77
|
-
async function shutdownAnalytics() {
|
|
78
|
-
await client?.shutdown();
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
// src/client.ts
|
|
82
|
-
var DEFAULT_CLOUD_URL = "https://trustworthy-kangaroo-277.convex.site";
|
|
83
|
-
var cachedWorkspaceId = null;
|
|
84
|
-
var cloudMode = false;
|
|
85
|
-
var AUDIT_BUFFER_SIZE = 50;
|
|
86
|
-
var auditBuffer = [];
|
|
87
|
-
function bootstrapCloudMode() {
|
|
88
|
-
const pbKey = process.env.PRODUCTBRAIN_API_KEY;
|
|
89
|
-
if (pbKey?.startsWith("pb_sk_")) {
|
|
90
|
-
const cloudUrl = process.env.PRODUCTBRAIN_URL ?? DEFAULT_CLOUD_URL;
|
|
91
|
-
process.env.CONVEX_SITE_URL ??= cloudUrl;
|
|
92
|
-
process.env.MCP_API_KEY ??= pbKey;
|
|
93
|
-
cloudMode = true;
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
function getEnv(key) {
|
|
97
|
-
const value = process.env[key];
|
|
98
|
-
if (!value) throw new Error(`${key} environment variable is required`);
|
|
99
|
-
return value;
|
|
100
|
-
}
|
|
101
|
-
function shouldLogAudit(status) {
|
|
102
|
-
return status === "error" || process.env.MCP_DEBUG === "1";
|
|
103
|
-
}
|
|
104
|
-
function audit(fn, status, durationMs, errorMsg) {
|
|
105
|
-
const ts = (/* @__PURE__ */ new Date()).toISOString();
|
|
106
|
-
const workspace = cachedWorkspaceId ?? "unresolved";
|
|
107
|
-
const entry = { ts, fn, workspace, status, durationMs };
|
|
108
|
-
if (errorMsg) entry.error = errorMsg;
|
|
109
|
-
auditBuffer.push(entry);
|
|
110
|
-
if (auditBuffer.length > AUDIT_BUFFER_SIZE) auditBuffer.shift();
|
|
111
|
-
trackToolCall(fn, status, durationMs, workspace, errorMsg);
|
|
112
|
-
if (!shouldLogAudit(status)) return;
|
|
113
|
-
const base = `[MCP-AUDIT] ${ts} fn=${fn} workspace=${workspace} status=${status} duration=${durationMs}ms`;
|
|
114
|
-
if (status === "error" && errorMsg) {
|
|
115
|
-
process.stderr.write(`${base} error=${JSON.stringify(errorMsg)}
|
|
116
|
-
`);
|
|
117
|
-
} else {
|
|
118
|
-
process.stderr.write(`${base}
|
|
119
|
-
`);
|
|
120
|
-
}
|
|
121
|
-
}
|
|
122
|
-
function getAuditLog() {
|
|
123
|
-
return auditBuffer;
|
|
124
|
-
}
|
|
125
|
-
async function mcpCall(fn, args = {}) {
|
|
126
|
-
const siteUrl = getEnv("CONVEX_SITE_URL").replace(/\/$/, "");
|
|
127
|
-
const apiKey = getEnv("MCP_API_KEY");
|
|
128
|
-
const start = Date.now();
|
|
129
|
-
let res;
|
|
130
|
-
try {
|
|
131
|
-
res = await fetch(`${siteUrl}/api/mcp`, {
|
|
132
|
-
method: "POST",
|
|
133
|
-
headers: {
|
|
134
|
-
"Content-Type": "application/json",
|
|
135
|
-
Authorization: `Bearer ${apiKey}`
|
|
136
|
-
},
|
|
137
|
-
body: JSON.stringify({ fn, args })
|
|
138
|
-
});
|
|
139
|
-
} catch (err) {
|
|
140
|
-
audit(fn, "error", Date.now() - start, err.message);
|
|
141
|
-
throw new Error(`MCP call "${fn}" network error: ${err.message}`);
|
|
142
|
-
}
|
|
143
|
-
const json = await res.json();
|
|
144
|
-
if (!res.ok || json.error) {
|
|
145
|
-
audit(fn, "error", Date.now() - start, json.error);
|
|
146
|
-
throw new Error(`MCP call "${fn}" failed (${res.status}): ${json.error ?? "unknown error"}`);
|
|
147
|
-
}
|
|
148
|
-
audit(fn, "ok", Date.now() - start);
|
|
149
|
-
return json.data;
|
|
150
|
-
}
|
|
151
|
-
async function getWorkspaceId() {
|
|
152
|
-
if (cachedWorkspaceId) return cachedWorkspaceId;
|
|
153
|
-
if (cloudMode) {
|
|
154
|
-
const workspace2 = await mcpCall(
|
|
155
|
-
"resolveWorkspace",
|
|
156
|
-
{ slug: "__cloud__" }
|
|
157
|
-
);
|
|
158
|
-
if (!workspace2) {
|
|
159
|
-
throw new Error("Cloud key is valid but no workspace is associated. Run `npx productbrain setup` again.");
|
|
160
|
-
}
|
|
161
|
-
cachedWorkspaceId = workspace2._id;
|
|
162
|
-
return cachedWorkspaceId;
|
|
163
|
-
}
|
|
164
|
-
const slug = getEnv("WORKSPACE_SLUG");
|
|
165
|
-
const workspace = await mcpCall(
|
|
166
|
-
"resolveWorkspace",
|
|
167
|
-
{ slug }
|
|
168
|
-
);
|
|
169
|
-
if (!workspace) {
|
|
170
|
-
throw new Error(`Workspace with slug "${slug}" not found`);
|
|
171
|
-
}
|
|
172
|
-
cachedWorkspaceId = workspace._id;
|
|
173
|
-
return cachedWorkspaceId;
|
|
174
|
-
}
|
|
175
|
-
async function mcpQuery(fn, args = {}) {
|
|
176
|
-
const workspaceId2 = await getWorkspaceId();
|
|
177
|
-
return mcpCall(fn, { ...args, workspaceId: workspaceId2 });
|
|
178
|
-
}
|
|
179
|
-
async function mcpMutation(fn, args = {}) {
|
|
180
|
-
const workspaceId2 = await getWorkspaceId();
|
|
181
|
-
return mcpCall(fn, { ...args, workspaceId: workspaceId2 });
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
// src/tools/knowledge.ts
|
|
185
|
-
function extractPreview(data, maxLen) {
|
|
186
|
-
if (!data || typeof data !== "object") return "";
|
|
187
|
-
const raw = data.description ?? data.canonical ?? data.detail ?? "";
|
|
188
|
-
if (typeof raw !== "string" || !raw) return "";
|
|
189
|
-
return raw.length > maxLen ? raw.substring(0, maxLen) + "..." : raw;
|
|
190
|
-
}
|
|
191
|
-
function registerKnowledgeTools(server2) {
|
|
192
|
-
server2.registerTool(
|
|
193
|
-
"list-collections",
|
|
194
|
-
{
|
|
195
|
-
title: "Browse Collections",
|
|
196
|
-
description: "List every knowledge collection in the workspace \u2014 glossary, business rules, tracking events, standards, etc. Returns each collection's slug, name, description, and field schema. Start here before create-entry so you know which collections exist and what fields they expect.",
|
|
197
|
-
annotations: { readOnlyHint: true }
|
|
198
|
-
},
|
|
199
|
-
async () => {
|
|
200
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
201
|
-
if (collections.length === 0) {
|
|
202
|
-
return { content: [{ type: "text", text: "No collections found in this workspace." }] };
|
|
203
|
-
}
|
|
204
|
-
const formatted = collections.map((c) => {
|
|
205
|
-
const fieldList = c.fields.map((f) => ` - \`${f.key}\` (${f.type}${f.required ? ", required" : ""}${f.searchable ? ", searchable" : ""})`).join("\n");
|
|
206
|
-
return `## ${c.name} (\`${c.slug}\`)
|
|
207
|
-
${c.description || "_No description_"}
|
|
208
|
-
|
|
209
|
-
**Fields:**
|
|
210
|
-
${fieldList}`;
|
|
211
|
-
}).join("\n\n---\n\n");
|
|
212
|
-
return {
|
|
213
|
-
content: [{ type: "text", text: `# Knowledge Collections (${collections.length})
|
|
214
|
-
|
|
215
|
-
${formatted}` }]
|
|
216
|
-
};
|
|
217
|
-
}
|
|
218
|
-
);
|
|
219
|
-
server2.registerTool(
|
|
220
|
-
"list-entries",
|
|
221
|
-
{
|
|
222
|
-
title: "Browse Entries",
|
|
223
|
-
description: "List entries in a collection, with optional filters for status, tag, or label. Returns entry IDs, names, status, and a data preview. Use list-collections first to discover available collection slugs.",
|
|
224
|
-
inputSchema: {
|
|
225
|
-
collection: z.string().optional().describe("Collection slug, e.g. 'glossary', 'tracking-events', 'business-rules'"),
|
|
226
|
-
status: z.string().optional().describe("Filter: draft | active | verified | deprecated"),
|
|
227
|
-
tag: z.string().optional().describe("Filter by internal tag, e.g. 'health:ambiguous'"),
|
|
228
|
-
label: z.string().optional().describe("Filter by label slug \u2014 matches entries across all collections")
|
|
229
|
-
},
|
|
230
|
-
annotations: { readOnlyHint: true }
|
|
231
|
-
},
|
|
232
|
-
async ({ collection, status, tag, label }) => {
|
|
233
|
-
let entries;
|
|
234
|
-
if (label) {
|
|
235
|
-
entries = await mcpQuery("kb.listEntriesByLabel", { labelSlug: label });
|
|
236
|
-
if (status) entries = entries.filter((e) => e.status === status);
|
|
237
|
-
} else {
|
|
238
|
-
entries = await mcpQuery("kb.listEntries", {
|
|
239
|
-
collectionSlug: collection,
|
|
240
|
-
status,
|
|
241
|
-
tag
|
|
242
|
-
});
|
|
243
|
-
}
|
|
244
|
-
if (entries.length === 0) {
|
|
245
|
-
return { content: [{ type: "text", text: "No entries match the given filters." }] };
|
|
246
|
-
}
|
|
247
|
-
const formatted = entries.map((e) => {
|
|
248
|
-
const id = e.entryId ? `**${e.entryId}:** ` : "";
|
|
249
|
-
const dataPreview = e.data ? Object.entries(e.data).slice(0, 4).map(([k, v]) => ` ${k}: ${typeof v === "string" ? v.substring(0, 120) : JSON.stringify(v)}`).join("\n") : "";
|
|
250
|
-
return `- ${id}${e.name} \`${e.status}\`${dataPreview ? `
|
|
251
|
-
${dataPreview}` : ""}`;
|
|
252
|
-
}).join("\n\n");
|
|
253
|
-
const scope = collection ? ` in \`${collection}\`` : "";
|
|
254
|
-
return {
|
|
255
|
-
content: [{ type: "text", text: `# Entries${scope} (${entries.length})
|
|
256
|
-
|
|
257
|
-
${formatted}` }]
|
|
258
|
-
};
|
|
259
|
-
}
|
|
260
|
-
);
|
|
261
|
-
server2.registerTool(
|
|
262
|
-
"get-entry",
|
|
263
|
-
{
|
|
264
|
-
title: "Look Up Entry",
|
|
265
|
-
description: "Retrieve a single knowledge entry by its human-readable ID (e.g. 'T-SUPPLIER', 'BR-001', 'EVT-workspace_created'). Returns the full record: all data fields, labels, relations, and change history. Use kb-search or list-entries first to discover entry IDs.",
|
|
266
|
-
inputSchema: {
|
|
267
|
-
entryId: z.string().describe("Entry ID, e.g. 'T-SUPPLIER', 'BR-001', 'EVT-workspace_created'")
|
|
268
|
-
},
|
|
269
|
-
annotations: { readOnlyHint: true }
|
|
270
|
-
},
|
|
271
|
-
async ({ entryId }) => {
|
|
272
|
-
const entry = await mcpQuery("kb.getEntry", { entryId });
|
|
273
|
-
if (!entry) {
|
|
274
|
-
return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try kb-search to find the right ID.` }] };
|
|
275
|
-
}
|
|
276
|
-
const lines = [
|
|
277
|
-
`# ${entry.entryId ? `${entry.entryId}: ` : ""}${entry.name}`,
|
|
278
|
-
"",
|
|
279
|
-
`**Status:** ${entry.status}`
|
|
280
|
-
];
|
|
281
|
-
if (entry.data && typeof entry.data === "object") {
|
|
282
|
-
lines.push("");
|
|
283
|
-
for (const [key, val] of Object.entries(entry.data)) {
|
|
284
|
-
const display = typeof val === "string" ? val : JSON.stringify(val);
|
|
285
|
-
lines.push(`**${key}:** ${display}`);
|
|
286
|
-
}
|
|
287
|
-
}
|
|
288
|
-
if (entry.tags?.length > 0) {
|
|
289
|
-
lines.push("", `**Tags:** ${entry.tags.join(", ")}`);
|
|
290
|
-
}
|
|
291
|
-
if (entry.labels?.length > 0) {
|
|
292
|
-
lines.push("", `**Labels:** ${entry.labels.map((l) => `\`${l.slug ?? l.name}\``).join(", ")}`);
|
|
293
|
-
}
|
|
294
|
-
if (entry.relations?.length > 0) {
|
|
295
|
-
lines.push("", "## Relations");
|
|
296
|
-
for (const r of entry.relations) {
|
|
297
|
-
const arrow = r.direction === "outgoing" ? "\u2192" : "\u2190";
|
|
298
|
-
const other = r.otherEntryId ? `${r.otherEntryId}: ${r.otherName}` : r.otherName ?? "unknown";
|
|
299
|
-
lines.push(`- ${arrow} **${r.type}** ${other}`);
|
|
300
|
-
}
|
|
301
|
-
}
|
|
302
|
-
if (entry.history?.length > 0) {
|
|
303
|
-
lines.push("", "## History (last 10)");
|
|
304
|
-
for (const h of entry.history.slice(-10)) {
|
|
305
|
-
const date = new Date(h.timestamp).toISOString().split("T")[0];
|
|
306
|
-
lines.push(`- ${date}: ${h.event}${h.changedBy ? ` _(${h.changedBy})_` : ""}`);
|
|
307
|
-
}
|
|
308
|
-
}
|
|
309
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
310
|
-
}
|
|
311
|
-
);
|
|
312
|
-
const governedCollections = /* @__PURE__ */ new Set([
|
|
313
|
-
"glossary",
|
|
314
|
-
"business-rules",
|
|
315
|
-
"principles",
|
|
316
|
-
"standards",
|
|
317
|
-
"strategy"
|
|
318
|
-
]);
|
|
319
|
-
server2.registerTool(
|
|
320
|
-
"create-entry",
|
|
321
|
-
{
|
|
322
|
-
title: "Create Entry",
|
|
323
|
-
description: "Create a new knowledge entry. Provide the collection slug, a display name, status, and data matching the collection's field schema. Call list-collections first to see available collections and their field definitions. Governed collections (glossary, business-rules, principles, standards, strategy) require status 'draft' \u2014 to promote to 'active' or 'verified', raise a tension or use update-entry after approval.",
|
|
324
|
-
inputSchema: {
|
|
325
|
-
collection: z.string().describe("Collection slug, e.g. 'tracking-events', 'standards', 'glossary'"),
|
|
326
|
-
entryId: z.string().optional().describe("Human-readable ID, e.g. 'EVT-workspace_created', 'STD-posthog-events'"),
|
|
327
|
-
name: z.string().describe("Display name"),
|
|
328
|
-
status: z.string().default("draft").describe("Lifecycle status: draft | active | verified | deprecated"),
|
|
329
|
-
data: z.record(z.unknown()).describe("Data object \u2014 keys must match the collection's field definitions"),
|
|
330
|
-
order: z.number().optional().describe("Manual sort order within the collection")
|
|
331
|
-
},
|
|
332
|
-
annotations: { destructiveHint: false }
|
|
333
|
-
},
|
|
334
|
-
async ({ collection, entryId, name, status, data, order }) => {
|
|
335
|
-
if (governedCollections.has(collection) && status !== "draft" && status !== "deprecated") {
|
|
336
|
-
return {
|
|
337
|
-
content: [{
|
|
338
|
-
type: "text",
|
|
339
|
-
text: `# Governance Required
|
|
340
|
-
|
|
341
|
-
The \`${collection}\` collection is governed. New entries must be created with status \`draft\`.
|
|
342
|
-
|
|
343
|
-
**How to proceed:**
|
|
344
|
-
1. Create the entry with status \`draft\` (treated as a proposal)
|
|
345
|
-
2. Raise a tension in the \`tensions\` collection to request promotion
|
|
346
|
-
3. After approval, use \`update-entry\` to change status to \`active\` or \`verified\``
|
|
347
|
-
}]
|
|
348
|
-
};
|
|
349
|
-
}
|
|
350
|
-
try {
|
|
351
|
-
const id = await mcpMutation("kb.createEntry", {
|
|
352
|
-
collectionSlug: collection,
|
|
353
|
-
entryId,
|
|
354
|
-
name,
|
|
355
|
-
status,
|
|
356
|
-
data,
|
|
357
|
-
order
|
|
358
|
-
});
|
|
359
|
-
return {
|
|
360
|
-
content: [{ type: "text", text: `# Entry Created
|
|
361
|
-
|
|
362
|
-
**${entryId ?? name}** added to \`${collection}\` as \`${status}\`.
|
|
363
|
-
|
|
364
|
-
Internal ID: ${id}` }]
|
|
365
|
-
};
|
|
366
|
-
} catch (error) {
|
|
367
|
-
const msg = error instanceof Error ? error.message : String(error);
|
|
368
|
-
if (msg.includes("Duplicate entry") || msg.includes("already exists")) {
|
|
369
|
-
return {
|
|
370
|
-
content: [{
|
|
371
|
-
type: "text",
|
|
372
|
-
text: `# Cannot Create \u2014 Duplicate Detected
|
|
373
|
-
|
|
374
|
-
${msg}
|
|
375
|
-
|
|
376
|
-
**What to do:**
|
|
377
|
-
- Use \`get-entry\` to inspect the existing entry
|
|
378
|
-
- Use \`update-entry\` to modify it
|
|
379
|
-
- If a genuinely new entry is needed, raise a tension to propose it`
|
|
380
|
-
}]
|
|
381
|
-
};
|
|
382
|
-
}
|
|
383
|
-
throw error;
|
|
384
|
-
}
|
|
385
|
-
}
|
|
386
|
-
);
|
|
387
|
-
server2.registerTool(
|
|
388
|
-
"update-entry",
|
|
389
|
-
{
|
|
390
|
-
title: "Update Entry",
|
|
391
|
-
description: "Update an existing entry by its human-readable ID. Only provide the fields you want to change \u2014 data fields are merged with existing values. Creates a draft version by default. Set autoPublish=true to publish immediately. Use get-entry first to see current values. SOS-020: Cannot update tension status via MCP \u2014 process decides (use Product Brain UI after approval).",
|
|
392
|
-
inputSchema: {
|
|
393
|
-
entryId: z.string().describe("Entry ID to update, e.g. 'T-SUPPLIER', 'BR-001'"),
|
|
394
|
-
name: z.string().optional().describe("New display name"),
|
|
395
|
-
status: z.string().optional().describe("New status: draft | active | verified | deprecated"),
|
|
396
|
-
data: z.record(z.unknown()).optional().describe("Fields to update (merged with existing data)"),
|
|
397
|
-
order: z.number().optional().describe("New sort order"),
|
|
398
|
-
autoPublish: z.boolean().optional().default(false).describe("If true, publishes the change immediately. If false (default), creates a draft version.")
|
|
399
|
-
},
|
|
400
|
-
annotations: { idempotentHint: true, destructiveHint: false }
|
|
401
|
-
},
|
|
402
|
-
async ({ entryId, name, status, data, order, autoPublish }) => {
|
|
403
|
-
try {
|
|
404
|
-
const id = await mcpMutation("kb.updateEntry", {
|
|
405
|
-
entryId,
|
|
406
|
-
name,
|
|
407
|
-
status,
|
|
408
|
-
data,
|
|
409
|
-
order,
|
|
410
|
-
autoPublish
|
|
411
|
-
});
|
|
412
|
-
const mode = autoPublish ? "published" : "saved as draft";
|
|
413
|
-
return {
|
|
414
|
-
content: [{ type: "text", text: `# Entry Updated
|
|
415
|
-
|
|
416
|
-
**${entryId}** has been ${mode}.
|
|
417
|
-
|
|
418
|
-
Internal ID: ${id}` }]
|
|
419
|
-
};
|
|
420
|
-
} catch (error) {
|
|
421
|
-
const msg = error instanceof Error ? error.message : String(error);
|
|
422
|
-
if (msg.includes("SOS-020")) {
|
|
423
|
-
return {
|
|
424
|
-
content: [{
|
|
425
|
-
type: "text",
|
|
426
|
-
text: `# SOS-020: Tension Status Cannot Be Changed via MCP
|
|
427
|
-
|
|
428
|
-
Tension status (open, in-progress, closed) must be changed through the defined process, not via MCP.
|
|
429
|
-
|
|
430
|
-
**What you can do:**
|
|
431
|
-
- Create tensions: \`create-entry collection=tensions name="..." status=open\`
|
|
432
|
-
- List tensions: \`list-entries collection=tensions\`
|
|
433
|
-
- Update non-status fields (raised, date, priority, description) via \`update-entry\`
|
|
434
|
-
- After process approval, a human uses the Product Brain UI to change status
|
|
435
|
-
|
|
436
|
-
Process criteria (TBD): e.g. 3+ users approved, or 7 days without valid concerns.`
|
|
437
|
-
}]
|
|
438
|
-
};
|
|
439
|
-
}
|
|
440
|
-
throw error;
|
|
441
|
-
}
|
|
442
|
-
}
|
|
443
|
-
);
|
|
444
|
-
server2.registerTool(
|
|
445
|
-
"kb-search",
|
|
446
|
-
{
|
|
447
|
-
title: "Search Knowledge Base",
|
|
448
|
-
description: "Full-text search across all knowledge entries. Returns entry names, collection, status, and a description preview. Scope results to a specific collection (e.g. collection='business-rules') or filter by status (e.g. status='active'). Use this to discover entries before calling get-entry for full details.",
|
|
449
|
-
inputSchema: {
|
|
450
|
-
query: z.string().describe("Search text (min 2 characters)"),
|
|
451
|
-
collection: z.string().optional().describe("Scope to a collection slug, e.g. 'business-rules', 'glossary', 'tracking-events'"),
|
|
452
|
-
status: z.string().optional().describe("Filter by status: draft | active | verified | deprecated")
|
|
453
|
-
},
|
|
454
|
-
annotations: { readOnlyHint: true, openWorldHint: true }
|
|
455
|
-
},
|
|
456
|
-
async ({ query, collection, status }) => {
|
|
457
|
-
const scope = collection ? ` in \`${collection}\`` : "";
|
|
458
|
-
await server2.sendLoggingMessage({ level: "info", data: `Searching${scope} for "${query}"...`, logger: "product-os" });
|
|
459
|
-
const [results, collections] = await Promise.all([
|
|
460
|
-
mcpQuery("kb.searchEntries", { query, collectionSlug: collection, status }),
|
|
461
|
-
mcpQuery("kb.listCollections")
|
|
462
|
-
]);
|
|
463
|
-
if (results.length === 0) {
|
|
464
|
-
return { content: [{ type: "text", text: `No results for "${query}"${scope}. Try a broader search or check list-collections for available data.` }] };
|
|
465
|
-
}
|
|
466
|
-
const collMap = /* @__PURE__ */ new Map();
|
|
467
|
-
for (const c of collections) {
|
|
468
|
-
collMap.set(c._id, { name: c.name, slug: c.slug });
|
|
469
|
-
}
|
|
470
|
-
const countsBySlug = /* @__PURE__ */ new Map();
|
|
471
|
-
for (const e of results) {
|
|
472
|
-
const col = collMap.get(e.collectionId);
|
|
473
|
-
const slug = col?.slug ?? "unknown";
|
|
474
|
-
countsBySlug.set(slug, (countsBySlug.get(slug) ?? 0) + 1);
|
|
475
|
-
}
|
|
476
|
-
const collSummary = [...countsBySlug.entries()].sort((a, b) => b[1] - a[1]).map(([slug, count]) => `${count} ${slug}`).join(", ");
|
|
477
|
-
const formatted = results.map((e) => {
|
|
478
|
-
const id = e.entryId ? `**${e.entryId}:** ` : "";
|
|
479
|
-
const col = collMap.get(e.collectionId);
|
|
480
|
-
const colTag = col ? ` [${col.slug}]` : "";
|
|
481
|
-
const desc = extractPreview(e.data, 150);
|
|
482
|
-
const preview = desc ? `
|
|
483
|
-
${desc}` : "";
|
|
484
|
-
return `- ${id}${e.name} \`${e.status}\`${colTag}${preview}`;
|
|
485
|
-
}).join("\n");
|
|
486
|
-
const header = `# Search Results for "${query}"${scope} (${results.length} match${results.length === 1 ? "" : "es"})
|
|
487
|
-
|
|
488
|
-
**By collection:** ${collSummary}`;
|
|
489
|
-
const footer = `_Tip: Use \`collection\` param to scope search. Use get-entry with an entry ID for full details._`;
|
|
490
|
-
return {
|
|
491
|
-
content: [{ type: "text", text: `${header}
|
|
492
|
-
|
|
493
|
-
${formatted}
|
|
494
|
-
|
|
495
|
-
${footer}` }]
|
|
496
|
-
};
|
|
497
|
-
}
|
|
498
|
-
);
|
|
499
|
-
server2.registerTool(
|
|
500
|
-
"get-history",
|
|
501
|
-
{
|
|
502
|
-
title: "Entry Change History",
|
|
503
|
-
description: "Get the audit trail for an entry \u2014 when it was created, updated, status-changed, etc. Returns timestamped events with change details.",
|
|
504
|
-
inputSchema: {
|
|
505
|
-
entryId: z.string().describe("Entry ID, e.g. 'T-SUPPLIER', 'BR-001'")
|
|
506
|
-
},
|
|
507
|
-
annotations: { readOnlyHint: true }
|
|
508
|
-
},
|
|
509
|
-
async ({ entryId }) => {
|
|
510
|
-
const history = await mcpQuery("kb.listEntryHistory", { entryId });
|
|
511
|
-
if (history.length === 0) {
|
|
512
|
-
return { content: [{ type: "text", text: `No history found for \`${entryId}\`.` }] };
|
|
513
|
-
}
|
|
514
|
-
const formatted = history.map((h) => {
|
|
515
|
-
const date = new Date(h.timestamp).toISOString();
|
|
516
|
-
const changes = h.changes ? ` \u2014 ${JSON.stringify(h.changes)}` : "";
|
|
517
|
-
return `- **${date}** ${h.event}${h.changedBy ? ` _(${h.changedBy})_` : ""}${changes}`;
|
|
518
|
-
}).join("\n");
|
|
519
|
-
return {
|
|
520
|
-
content: [{ type: "text", text: `# History for \`${entryId}\` (${history.length} events)
|
|
521
|
-
|
|
522
|
-
${formatted}` }]
|
|
523
|
-
};
|
|
524
|
-
}
|
|
525
|
-
);
|
|
526
|
-
server2.registerTool(
|
|
527
|
-
"relate-entries",
|
|
528
|
-
{
|
|
529
|
-
title: "Link Two Entries",
|
|
530
|
-
description: "Create a typed relation between two entries, building the knowledge graph. Use get-entry to see existing relations before adding new ones.\n\nRecommended relation types (extensible \u2014 any string is accepted):\n- related_to, depends_on, replaces, conflicts_with, references, confused_with\n- governs \u2014 a rule constrains behavior of a feature\n- defines_term_for \u2014 a glossary term is canonical vocabulary for a feature/area\n- belongs_to \u2014 a feature belongs to a product area or parent concept\n- informs \u2014 a decision or insight informs a feature\n- surfaces_tension_in \u2014 a tension exists within a feature area\n\nCheck glossary for relation type definitions if unsure which to use.",
|
|
531
|
-
inputSchema: {
|
|
532
|
-
from: z.string().describe("Source entry ID, e.g. 'T-SUPPLIER'"),
|
|
533
|
-
to: z.string().describe("Target entry ID, e.g. 'BR-001'"),
|
|
534
|
-
type: z.string().describe("Relation type \u2014 use a recommended type or any descriptive string")
|
|
535
|
-
},
|
|
536
|
-
annotations: { destructiveHint: false }
|
|
537
|
-
},
|
|
538
|
-
async ({ from, to, type }) => {
|
|
539
|
-
await mcpMutation("kb.createEntryRelation", {
|
|
540
|
-
fromEntryId: from,
|
|
541
|
-
toEntryId: to,
|
|
542
|
-
type
|
|
543
|
-
});
|
|
544
|
-
return {
|
|
545
|
-
content: [{ type: "text", text: `# Relation Created
|
|
546
|
-
|
|
547
|
-
**${from}** \u2014[${type}]\u2192 **${to}**` }]
|
|
548
|
-
};
|
|
549
|
-
}
|
|
550
|
-
);
|
|
551
|
-
server2.registerTool(
|
|
552
|
-
"find-related",
|
|
553
|
-
{
|
|
554
|
-
title: "Find Related Entries",
|
|
555
|
-
description: "Navigate the knowledge graph \u2014 find all entries related to a given entry. Shows incoming references (what points to this entry), outgoing references (what this entry points to), or both. Use after get-entry to explore connections, or to answer 'what depends on X?' or 'what references Y?'",
|
|
556
|
-
inputSchema: {
|
|
557
|
-
entryId: z.string().describe("Entry ID, e.g. 'GT-019', 'SOS-006'"),
|
|
558
|
-
direction: z.enum(["incoming", "outgoing", "both"]).default("both").describe("Filter: 'incoming' = what references this entry, 'outgoing' = what this entry references")
|
|
559
|
-
},
|
|
560
|
-
annotations: { readOnlyHint: true }
|
|
561
|
-
},
|
|
562
|
-
async ({ entryId, direction }) => {
|
|
563
|
-
const relations = await mcpQuery("kb.listEntryRelations", { entryId });
|
|
564
|
-
if (relations.length === 0) {
|
|
565
|
-
return { content: [{ type: "text", text: `No relations found for \`${entryId}\`. Use relate-entries to create connections.` }] };
|
|
566
|
-
}
|
|
567
|
-
const sourceEntry = await mcpQuery("kb.getEntry", { entryId });
|
|
568
|
-
if (!sourceEntry) {
|
|
569
|
-
return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try kb-search to find the right ID.` }] };
|
|
570
|
-
}
|
|
571
|
-
const sourceInternalId = sourceEntry._id;
|
|
572
|
-
const MAX_RELATIONS = 25;
|
|
573
|
-
const truncated = relations.length > MAX_RELATIONS;
|
|
574
|
-
const capped = relations.slice(0, MAX_RELATIONS);
|
|
575
|
-
const otherIds = /* @__PURE__ */ new Set();
|
|
576
|
-
for (const r of capped) {
|
|
577
|
-
const otherId = r.fromId === sourceInternalId ? r.toId : r.fromId;
|
|
578
|
-
otherIds.add(otherId);
|
|
579
|
-
}
|
|
580
|
-
const otherEntries = /* @__PURE__ */ new Map();
|
|
581
|
-
for (const id of otherIds) {
|
|
582
|
-
const entry = await mcpQuery("kb.getEntry", { id });
|
|
583
|
-
if (entry) {
|
|
584
|
-
otherEntries.set(entry._id, { entryId: entry.entryId, name: entry.name, collectionId: entry.collectionId });
|
|
585
|
-
}
|
|
586
|
-
}
|
|
587
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
588
|
-
const collMap = /* @__PURE__ */ new Map();
|
|
589
|
-
for (const c of collections) collMap.set(c._id, c.slug);
|
|
590
|
-
const lines = [`# Relations for ${entryId}: ${sourceEntry.name}`, ""];
|
|
591
|
-
const enriched = capped.map((r) => {
|
|
592
|
-
const isOutgoing = r.fromId === sourceInternalId;
|
|
593
|
-
const otherId = isOutgoing ? r.toId : r.fromId;
|
|
594
|
-
const other = otherEntries.get(otherId);
|
|
595
|
-
const otherLabel = other?.entryId ? `${other.entryId}: ${other.name}` : other?.name ?? "(deleted)";
|
|
596
|
-
const colSlug = other ? collMap.get(other.collectionId) ?? "unknown" : "unknown";
|
|
597
|
-
return { isOutgoing, type: r.type, otherLabel, colSlug };
|
|
598
|
-
});
|
|
599
|
-
const outgoing = enriched.filter((r) => r.isOutgoing);
|
|
600
|
-
const incoming = enriched.filter((r) => !r.isOutgoing);
|
|
601
|
-
if ((direction === "outgoing" || direction === "both") && outgoing.length > 0) {
|
|
602
|
-
lines.push(`## Outgoing (${outgoing.length})`);
|
|
603
|
-
for (const r of outgoing) {
|
|
604
|
-
lines.push(`- \u2192 **${r.type}** ${r.otherLabel} [${r.colSlug}]`);
|
|
605
|
-
}
|
|
606
|
-
lines.push("");
|
|
607
|
-
}
|
|
608
|
-
if ((direction === "incoming" || direction === "both") && incoming.length > 0) {
|
|
609
|
-
lines.push(`## Incoming (${incoming.length})`);
|
|
610
|
-
for (const r of incoming) {
|
|
611
|
-
lines.push(`- \u2190 **${r.type}** ${r.otherLabel} [${r.colSlug}]`);
|
|
612
|
-
}
|
|
613
|
-
lines.push("");
|
|
614
|
-
}
|
|
615
|
-
const shown = direction === "outgoing" ? outgoing : direction === "incoming" ? incoming : enriched;
|
|
616
|
-
if (shown.length === 0) {
|
|
617
|
-
lines.push(`No ${direction} relations found for \`${entryId}\`.`);
|
|
618
|
-
}
|
|
619
|
-
if (truncated) {
|
|
620
|
-
lines.push(`_Showing first ${MAX_RELATIONS} of ${relations.length} relations. Use get-entry for the full picture._`);
|
|
621
|
-
}
|
|
622
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
623
|
-
}
|
|
624
|
-
);
|
|
625
|
-
server2.registerTool(
|
|
626
|
-
"gather-context",
|
|
627
|
-
{
|
|
628
|
-
title: "Gather Full Context",
|
|
629
|
-
description: "Assemble the full knowledge context around an entry by traversing the knowledge graph. Returns all related entries grouped by collection \u2014 glossary terms, business rules, tensions, decisions, features, etc. Use this when starting work on a feature or investigating an area to get the complete picture in one call.\n\nExample: gather-context entryId='FEAT-001' returns all glossary terms, business rules, and tensions linked to that feature.",
|
|
630
|
-
inputSchema: {
|
|
631
|
-
entryId: z.string().describe("Entry ID, e.g. 'FEAT-001', 'GT-019', 'BR-007'"),
|
|
632
|
-
maxHops: z.number().min(1).max(3).default(2).describe("How many relation hops to traverse (1=direct only, 2=default, 3=wide net)")
|
|
633
|
-
},
|
|
634
|
-
annotations: { readOnlyHint: true }
|
|
635
|
-
},
|
|
636
|
-
async ({ entryId, maxHops }) => {
|
|
637
|
-
const result = await mcpQuery("kb.gatherContext", { entryId, maxHops });
|
|
638
|
-
if (!result?.root) {
|
|
639
|
-
return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try kb-search to find the right ID.` }] };
|
|
640
|
-
}
|
|
641
|
-
if (result.related.length === 0) {
|
|
642
|
-
return {
|
|
643
|
-
content: [{
|
|
644
|
-
type: "text",
|
|
645
|
-
text: `# Context for ${result.root.entryId}: ${result.root.name}
|
|
646
|
-
|
|
647
|
-
_No relations found._ This entry is not yet connected to the knowledge graph.
|
|
648
|
-
|
|
649
|
-
Use \`suggest-links\` to discover potential connections, or \`relate-entries\` to link manually.`
|
|
650
|
-
}]
|
|
651
|
-
};
|
|
652
|
-
}
|
|
653
|
-
const byCollection = /* @__PURE__ */ new Map();
|
|
654
|
-
for (const entry of result.related) {
|
|
655
|
-
const key = entry.collectionName;
|
|
656
|
-
if (!byCollection.has(key)) byCollection.set(key, []);
|
|
657
|
-
byCollection.get(key).push(entry);
|
|
658
|
-
}
|
|
659
|
-
const lines = [
|
|
660
|
-
`# Context for ${result.root.entryId}: ${result.root.name}`,
|
|
661
|
-
`_${result.totalRelations} related entries across ${byCollection.size} collections (${result.hopsTraversed} hops traversed)_`,
|
|
662
|
-
""
|
|
663
|
-
];
|
|
664
|
-
for (const [collName, entries] of byCollection) {
|
|
665
|
-
lines.push(`## ${collName} (${entries.length})`);
|
|
666
|
-
for (const e of entries) {
|
|
667
|
-
const arrow = e.relationDirection === "outgoing" ? "\u2192" : "\u2190";
|
|
668
|
-
const hopLabel = e.hop > 1 ? ` (hop ${e.hop})` : "";
|
|
669
|
-
const id = e.entryId ? `${e.entryId}: ` : "";
|
|
670
|
-
lines.push(`- ${arrow} **${e.relationType}** ${id}${e.name}${hopLabel}`);
|
|
671
|
-
}
|
|
672
|
-
lines.push("");
|
|
673
|
-
}
|
|
674
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
675
|
-
}
|
|
676
|
-
);
|
|
677
|
-
server2.registerTool(
|
|
678
|
-
"suggest-links",
|
|
679
|
-
{
|
|
680
|
-
title: "Suggest Links",
|
|
681
|
-
description: "Discover potential connections for an entry by scanning the knowledge base for related content. Returns ranked suggestions based on text similarity \u2014 review them and use relate-entries to create the ones that make sense.\n\nThis is a discovery tool, not auto-linking. Always review suggestions before linking.",
|
|
682
|
-
inputSchema: {
|
|
683
|
-
entryId: z.string().describe("Entry ID to find suggestions for, e.g. 'FEAT-001'"),
|
|
684
|
-
limit: z.number().min(1).max(20).default(10).describe("Max number of suggestions to return")
|
|
685
|
-
},
|
|
686
|
-
annotations: { readOnlyHint: true }
|
|
687
|
-
},
|
|
688
|
-
async ({ entryId, limit }) => {
|
|
689
|
-
const entry = await mcpQuery("kb.getEntry", { entryId });
|
|
690
|
-
if (!entry) {
|
|
691
|
-
return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try kb-search to find the right ID.` }] };
|
|
692
|
-
}
|
|
693
|
-
const searchTerms = [entry.name];
|
|
694
|
-
if (entry.data?.description) searchTerms.push(entry.data.description);
|
|
695
|
-
if (entry.data?.canonical) searchTerms.push(entry.data.canonical);
|
|
696
|
-
if (entry.data?.rationale) searchTerms.push(entry.data.rationale);
|
|
697
|
-
if (entry.data?.rule) searchTerms.push(entry.data.rule);
|
|
698
|
-
const queryText = searchTerms.join(" ").replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length > 3).slice(0, 8).join(" ");
|
|
699
|
-
if (!queryText) {
|
|
700
|
-
return { content: [{ type: "text", text: `Entry \`${entryId}\` has too little text content to generate suggestions.` }] };
|
|
701
|
-
}
|
|
702
|
-
const results = await mcpQuery("kb.searchEntries", { query: queryText });
|
|
703
|
-
if (!results || results.length === 0) {
|
|
704
|
-
return { content: [{ type: "text", text: `No suggestions found for \`${entryId}\`. The knowledge base may need more entries.` }] };
|
|
705
|
-
}
|
|
706
|
-
const existingRelations = await mcpQuery("kb.listEntryRelations", { entryId });
|
|
707
|
-
const relatedIds = new Set(
|
|
708
|
-
existingRelations.flatMap((r) => [r.fromId, r.toId])
|
|
709
|
-
);
|
|
710
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
711
|
-
const collMap = /* @__PURE__ */ new Map();
|
|
712
|
-
for (const c of collections) collMap.set(c._id, c.slug);
|
|
713
|
-
const suggestions = results.filter((r) => r._id !== entry._id && !relatedIds.has(r._id)).slice(0, limit).map((r) => ({
|
|
714
|
-
entryId: r.entryId,
|
|
715
|
-
name: r.name,
|
|
716
|
-
collection: collMap.get(r.collectionId) ?? "unknown",
|
|
717
|
-
preview: extractPreview(r.data, 80)
|
|
718
|
-
}));
|
|
719
|
-
if (suggestions.length === 0) {
|
|
720
|
-
return { content: [{ type: "text", text: `No new link suggestions for \`${entryId}\` \u2014 it may already be well-connected, or no similar entries exist.` }] };
|
|
721
|
-
}
|
|
722
|
-
const lines = [
|
|
723
|
-
`# Link Suggestions for ${entryId}: ${entry.name}`,
|
|
724
|
-
`_${suggestions.length} potential connections found. Review and use \`relate-entries\` to create the ones that make sense._`,
|
|
725
|
-
""
|
|
726
|
-
];
|
|
727
|
-
for (let i = 0; i < suggestions.length; i++) {
|
|
728
|
-
const s = suggestions[i];
|
|
729
|
-
const preview = s.preview ? ` \u2014 ${s.preview}` : "";
|
|
730
|
-
lines.push(`${i + 1}. **${s.entryId ?? "(no ID)"}**: ${s.name} [${s.collection}]${preview}`);
|
|
731
|
-
}
|
|
732
|
-
lines.push("");
|
|
733
|
-
lines.push("**To link:** `relate-entries from='FEAT-001' to='GT-019' type='defines_term_for'`");
|
|
734
|
-
lines.push("");
|
|
735
|
-
lines.push("_Recommended relation types: governs, defines_term_for, belongs_to, informs, surfaces_tension_in, related_to, depends_on_");
|
|
736
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
737
|
-
}
|
|
738
|
-
);
|
|
739
|
-
server2.registerTool(
|
|
740
|
-
"quick-capture",
|
|
741
|
-
{
|
|
742
|
-
title: "Quick Capture",
|
|
743
|
-
description: "Quickly capture a knowledge entry with just a name and description \u2014 no need to look up the full field schema first. Always creates as 'draft' status with sensible defaults for remaining fields. Use update-entry later to fill in details. Embodies 'Capture Now, Curate Later' (PRI-81cbdq).",
|
|
744
|
-
inputSchema: {
|
|
745
|
-
collection: z.string().describe("Collection slug, e.g. 'business-rules', 'glossary', 'tensions', 'decisions'"),
|
|
746
|
-
name: z.string().describe("Display name for the entry"),
|
|
747
|
-
description: z.string().describe("Short description \u2014 the essential context to capture now"),
|
|
748
|
-
entryId: z.string().optional().describe("Optional human-readable ID (e.g. 'SOS-020', 'GT-031')")
|
|
749
|
-
},
|
|
750
|
-
annotations: { destructiveHint: false }
|
|
751
|
-
},
|
|
752
|
-
async ({ collection, name, description, entryId }) => {
|
|
753
|
-
const col = await mcpQuery("kb.getCollection", { slug: collection });
|
|
754
|
-
if (!col) {
|
|
755
|
-
return { content: [{ type: "text", text: `Collection \`${collection}\` not found. Use list-collections to see available collections.` }] };
|
|
756
|
-
}
|
|
757
|
-
const data = {};
|
|
758
|
-
const emptyFields = [];
|
|
759
|
-
for (const field of col.fields ?? []) {
|
|
760
|
-
const key = field.key;
|
|
761
|
-
if (key === "description" || key === "canonical" || key === "detail") {
|
|
762
|
-
data[key] = description;
|
|
763
|
-
} else if (field.type === "array" || field.type === "multi-select") {
|
|
764
|
-
data[key] = [];
|
|
765
|
-
emptyFields.push(key);
|
|
766
|
-
} else if (field.type === "select") {
|
|
767
|
-
data[key] = field.options?.[0] ?? "";
|
|
768
|
-
emptyFields.push(key);
|
|
769
|
-
} else {
|
|
770
|
-
data[key] = "";
|
|
771
|
-
emptyFields.push(key);
|
|
772
|
-
}
|
|
773
|
-
}
|
|
774
|
-
if (!data.description && !data.canonical && !data.detail) {
|
|
775
|
-
data.description = description;
|
|
776
|
-
}
|
|
777
|
-
try {
|
|
778
|
-
const id = await mcpMutation("kb.createEntry", {
|
|
779
|
-
collectionSlug: collection,
|
|
780
|
-
entryId,
|
|
781
|
-
name,
|
|
782
|
-
status: "draft",
|
|
783
|
-
data
|
|
784
|
-
});
|
|
785
|
-
const emptyNote = emptyFields.length > 0 ? `
|
|
786
|
-
|
|
787
|
-
**Fields to fill later** (via \`update-entry\`):
|
|
788
|
-
${emptyFields.map((f) => `- \`${f}\``).join("\n")}` : "";
|
|
789
|
-
return {
|
|
790
|
-
content: [{
|
|
791
|
-
type: "text",
|
|
792
|
-
text: `# Quick Capture \u2014 Done
|
|
793
|
-
|
|
794
|
-
**${entryId ?? name}** added to \`${collection}\` as \`draft\`.
|
|
795
|
-
|
|
796
|
-
Internal ID: ${id}${emptyNote}
|
|
797
|
-
|
|
798
|
-
_Use \`update-entry\` to fill in details when ready. Use \`get-entry\` to review._`
|
|
799
|
-
}]
|
|
800
|
-
};
|
|
801
|
-
} catch (error) {
|
|
802
|
-
const msg = error instanceof Error ? error.message : String(error);
|
|
803
|
-
if (msg.includes("Duplicate") || msg.includes("already exists")) {
|
|
804
|
-
return {
|
|
805
|
-
content: [{
|
|
806
|
-
type: "text",
|
|
807
|
-
text: `# Cannot Capture \u2014 Duplicate Detected
|
|
808
|
-
|
|
809
|
-
${msg}
|
|
810
|
-
|
|
811
|
-
Use \`get-entry\` to inspect the existing entry, or \`update-entry\` to modify it.`
|
|
812
|
-
}]
|
|
813
|
-
};
|
|
814
|
-
}
|
|
815
|
-
throw error;
|
|
816
|
-
}
|
|
817
|
-
}
|
|
818
|
-
);
|
|
819
|
-
server2.registerTool(
|
|
820
|
-
"load-context-for-task",
|
|
821
|
-
{
|
|
822
|
-
title: "Load Context for Task",
|
|
823
|
-
description: "Auto-load relevant domain knowledge for a task in a single call. Pass a natural-language task description; the tool searches the KB, traverses the knowledge graph, and returns a ranked set of entries (business rules, glossary terms, decisions, features, etc.) grouped by collection with a confidence score.\n\nUse this at the start of a conversation to ground the agent in domain context before writing code or making recommendations.\n\nConfidence levels:\n- high: 3+ direct KB matches \u2014 strong domain coverage\n- medium: 1-2 direct matches \u2014 partial coverage, may want to drill deeper\n- low: no direct matches but related entries found via graph traversal\n- none: no relevant entries found \u2014 KB may not cover this area yet",
|
|
824
|
-
inputSchema: {
|
|
825
|
-
taskDescription: z.string().describe("Natural-language description of the task or user message"),
|
|
826
|
-
maxResults: z.number().min(1).max(25).default(10).optional().describe("Max entries to return (default 10)"),
|
|
827
|
-
maxHops: z.number().min(1).max(3).default(2).optional().describe("Graph traversal depth from each search hit (default 2)")
|
|
828
|
-
},
|
|
829
|
-
annotations: { readOnlyHint: true, openWorldHint: true }
|
|
830
|
-
},
|
|
831
|
-
async ({ taskDescription, maxResults, maxHops }) => {
|
|
832
|
-
await server2.sendLoggingMessage({
|
|
833
|
-
level: "info",
|
|
834
|
-
data: `Loading context for task: "${taskDescription.substring(0, 80)}..."`,
|
|
835
|
-
logger: "product-brain"
|
|
836
|
-
});
|
|
837
|
-
const result = await mcpQuery("kb.loadContextForTask", {
|
|
838
|
-
taskDescription,
|
|
839
|
-
maxResults: maxResults ?? 10,
|
|
840
|
-
maxHops: maxHops ?? 2
|
|
841
|
-
});
|
|
842
|
-
if (result.confidence === "none" || result.entries.length === 0) {
|
|
843
|
-
return {
|
|
844
|
-
content: [{
|
|
845
|
-
type: "text",
|
|
846
|
-
text: `# Context Loaded
|
|
847
|
-
|
|
848
|
-
**Confidence:** None
|
|
849
|
-
|
|
850
|
-
No KB context found for this task. The knowledge base may not cover this area yet.
|
|
851
|
-
|
|
852
|
-
_Consider capturing domain knowledge discovered during this task via \`smart-capture\`._`
|
|
853
|
-
}]
|
|
854
|
-
};
|
|
855
|
-
}
|
|
856
|
-
const byCollection = /* @__PURE__ */ new Map();
|
|
857
|
-
for (const entry of result.entries) {
|
|
858
|
-
const key = entry.collectionName;
|
|
859
|
-
if (!byCollection.has(key)) byCollection.set(key, []);
|
|
860
|
-
byCollection.get(key).push(entry);
|
|
861
|
-
}
|
|
862
|
-
const lines = [
|
|
863
|
-
`# Context Loaded`,
|
|
864
|
-
`**Confidence:** ${result.confidence.charAt(0).toUpperCase() + result.confidence.slice(1)}`,
|
|
865
|
-
`**Matched:** ${result.entries.length} entries across ${byCollection.size} collection${byCollection.size === 1 ? "" : "s"}`,
|
|
866
|
-
""
|
|
867
|
-
];
|
|
868
|
-
for (const [collName, entries] of byCollection) {
|
|
869
|
-
lines.push(`### ${collName} (${entries.length})`);
|
|
870
|
-
for (const e of entries) {
|
|
871
|
-
const id = e.entryId ? `**${e.entryId}:** ` : "";
|
|
872
|
-
const hopLabel = e.hop > 0 ? ` _(hop ${e.hop}${e.relationType ? `, ${e.relationType}` : ""})_` : "";
|
|
873
|
-
const preview = e.descriptionPreview ? `
|
|
874
|
-
${e.descriptionPreview}` : "";
|
|
875
|
-
const codePaths = e.codePaths.length > 0 ? `
|
|
876
|
-
Code: ${e.codePaths.join(", ")}` : "";
|
|
877
|
-
lines.push(`- ${id}${e.name}${hopLabel}${preview}${codePaths}`);
|
|
878
|
-
}
|
|
879
|
-
lines.push("");
|
|
880
|
-
}
|
|
881
|
-
lines.push(`_Use \`get-entry\` for full details on any entry._`);
|
|
882
|
-
return {
|
|
883
|
-
content: [{ type: "text", text: lines.join("\n") }]
|
|
884
|
-
};
|
|
885
|
-
}
|
|
886
|
-
);
|
|
887
|
-
server2.registerTool(
|
|
888
|
-
"review-rules",
|
|
889
|
-
{
|
|
890
|
-
title: "Review Business Rules",
|
|
891
|
-
description: "Surface all active business rules for a domain, formatted for compliance review. Use when reviewing code, designs, or decisions against Product Brain governance. Optionally provide context (what you're building or reviewing) to help focus the review. This is the tool form of the review-against-rules prompt.",
|
|
892
|
-
inputSchema: {
|
|
893
|
-
domain: z.string().describe("Business rule domain, e.g. 'AI & MCP Integration', 'Governance & Decision-Making'"),
|
|
894
|
-
context: z.string().optional().describe("What you're reviewing \u2014 code change, design decision, file path, etc.")
|
|
895
|
-
},
|
|
896
|
-
annotations: { readOnlyHint: true }
|
|
897
|
-
},
|
|
898
|
-
async ({ domain, context }) => {
|
|
899
|
-
const entries = await mcpQuery("kb.listEntries", { collectionSlug: "business-rules" });
|
|
900
|
-
const domainLower = domain.toLowerCase();
|
|
901
|
-
const rules = entries.filter((e) => {
|
|
902
|
-
const ruleDomain = e.data?.domain ?? "";
|
|
903
|
-
return ruleDomain.toLowerCase() === domainLower || ruleDomain.toLowerCase().includes(domainLower);
|
|
904
|
-
});
|
|
905
|
-
if (rules.length === 0) {
|
|
906
|
-
const allDomains = [...new Set(entries.map((e) => e.data?.domain).filter(Boolean))];
|
|
907
|
-
return {
|
|
908
|
-
content: [{
|
|
909
|
-
type: "text",
|
|
910
|
-
text: `# No Rules Found for "${domain}"
|
|
911
|
-
|
|
912
|
-
Available domains:
|
|
913
|
-
${allDomains.map((d) => `- ${d}`).join("\n")}
|
|
914
|
-
|
|
915
|
-
_Try one of the domains above, or use kb-search to find rules by keyword._`
|
|
916
|
-
}]
|
|
917
|
-
};
|
|
918
|
-
}
|
|
919
|
-
const header = context ? `# Business Rules: ${domain}
|
|
920
|
-
|
|
921
|
-
**Review context:** ${context}
|
|
922
|
-
|
|
923
|
-
For each rule, assess: compliant, at risk, violation, or not applicable.
|
|
924
|
-
` : `# Business Rules: ${domain}
|
|
925
|
-
`;
|
|
926
|
-
const formatted = rules.map((r) => {
|
|
927
|
-
const id = r.entryId ? `**${r.entryId}:** ` : "";
|
|
928
|
-
const severity = r.data?.severity ? ` | Severity: ${r.data.severity}` : "";
|
|
929
|
-
const desc = r.data?.description ?? "";
|
|
930
|
-
const impact = r.data?.dataImpact ? `
|
|
931
|
-
Data impact: ${r.data.dataImpact}` : "";
|
|
932
|
-
const related = (r.data?.relatedRules ?? []).length > 0 ? `
|
|
933
|
-
Related: ${r.data.relatedRules.join(", ")}` : "";
|
|
934
|
-
return `### ${id}${r.name} \`${r.status}\`${severity}
|
|
935
|
-
|
|
936
|
-
${desc}${impact}${related}`;
|
|
937
|
-
}).join("\n\n---\n\n");
|
|
938
|
-
const footer = `
|
|
939
|
-
_${rules.length} rule${rules.length === 1 ? "" : "s"} in this domain. Use \`get-entry\` for full details. Use the \`draft-rule-from-context\` prompt to propose new rules._`;
|
|
940
|
-
return {
|
|
941
|
-
content: [{ type: "text", text: `${header}
|
|
942
|
-
${formatted}
|
|
943
|
-
${footer}` }]
|
|
944
|
-
};
|
|
945
|
-
}
|
|
946
|
-
);
|
|
947
|
-
}
|
|
948
|
-
|
|
949
|
-
// src/tools/labels.ts
|
|
950
|
-
import { z as z2 } from "zod";
|
|
951
|
-
function registerLabelTools(server2) {
|
|
952
|
-
server2.registerTool(
|
|
953
|
-
"list-labels",
|
|
954
|
-
{
|
|
955
|
-
title: "Browse Labels",
|
|
956
|
-
description: "List all workspace labels with their groups and hierarchy. Labels can be applied to any entry across any collection for cross-domain filtering. Similar to labels in Linear or GitHub.",
|
|
957
|
-
annotations: { readOnlyHint: true }
|
|
958
|
-
},
|
|
959
|
-
async () => {
|
|
960
|
-
const labels = await mcpQuery("kb.listLabels");
|
|
961
|
-
if (labels.length === 0) {
|
|
962
|
-
return { content: [{ type: "text", text: "No labels defined in this workspace yet." }] };
|
|
963
|
-
}
|
|
964
|
-
const groups = labels.filter((l) => l.isGroup);
|
|
965
|
-
const ungrouped = labels.filter((l) => !l.isGroup && !l.parentId);
|
|
966
|
-
const children = (parentId) => labels.filter((l) => l.parentId === parentId);
|
|
967
|
-
const lines = ["# Workspace Labels"];
|
|
968
|
-
for (const group of groups) {
|
|
969
|
-
lines.push(`
|
|
970
|
-
## ${group.name}`);
|
|
971
|
-
if (group.description) lines.push(`_${group.description}_`);
|
|
972
|
-
for (const child of children(group._id)) {
|
|
973
|
-
const color = child.color ? ` ${child.color}` : "";
|
|
974
|
-
lines.push(` - \`${child.slug}\` ${child.name}${color}`);
|
|
975
|
-
}
|
|
976
|
-
}
|
|
977
|
-
if (ungrouped.length > 0) {
|
|
978
|
-
lines.push("\n## Ungrouped");
|
|
979
|
-
for (const label of ungrouped) {
|
|
980
|
-
const color = label.color ? ` ${label.color}` : "";
|
|
981
|
-
lines.push(`- \`${label.slug}\` ${label.name}${color}${label.description ? ` \u2014 _${label.description}_` : ""}`);
|
|
982
|
-
}
|
|
983
|
-
}
|
|
984
|
-
return {
|
|
985
|
-
content: [{ type: "text", text: lines.join("\n") }]
|
|
986
|
-
};
|
|
987
|
-
}
|
|
988
|
-
);
|
|
989
|
-
server2.registerTool(
|
|
990
|
-
"manage-labels",
|
|
991
|
-
{
|
|
992
|
-
title: "Manage Labels",
|
|
993
|
-
description: "Create, update, or delete a workspace label. Labels support hierarchy (groups with children). Use list-labels first to see what exists.",
|
|
994
|
-
inputSchema: {
|
|
995
|
-
action: z2.enum(["create", "update", "delete"]).describe("What to do"),
|
|
996
|
-
slug: z2.string().describe("Label slug (machine name), e.g. 'p1-critical', 'needs-review'"),
|
|
997
|
-
name: z2.string().optional().describe("Display name (required for create)"),
|
|
998
|
-
color: z2.string().optional().describe("Hex color, e.g. '#ef4444'"),
|
|
999
|
-
description: z2.string().optional().describe("What this label means"),
|
|
1000
|
-
parentSlug: z2.string().optional().describe("Parent group slug for label hierarchy"),
|
|
1001
|
-
isGroup: z2.boolean().optional().describe("True if this is a group container, not a taggable label"),
|
|
1002
|
-
order: z2.number().optional().describe("Sort order within its group")
|
|
1003
|
-
}
|
|
1004
|
-
},
|
|
1005
|
-
async ({ action, slug, name, color, description, parentSlug, isGroup, order }) => {
|
|
1006
|
-
if (action === "create") {
|
|
1007
|
-
if (!name) {
|
|
1008
|
-
return { content: [{ type: "text", text: "Cannot create a label without a name." }] };
|
|
1009
|
-
}
|
|
1010
|
-
let parentId;
|
|
1011
|
-
if (parentSlug) {
|
|
1012
|
-
const labels = await mcpQuery("kb.listLabels");
|
|
1013
|
-
const parent = labels.find((l) => l.slug === parentSlug);
|
|
1014
|
-
if (!parent) {
|
|
1015
|
-
return { content: [{ type: "text", text: `Parent label \`${parentSlug}\` not found. Use list-labels to see available groups.` }] };
|
|
1016
|
-
}
|
|
1017
|
-
parentId = parent._id;
|
|
1018
|
-
}
|
|
1019
|
-
await mcpMutation("kb.createLabel", { slug, name, color, description, parentId, isGroup, order });
|
|
1020
|
-
return { content: [{ type: "text", text: `# Label Created
|
|
1021
|
-
|
|
1022
|
-
**${name}** (\`${slug}\`)` }] };
|
|
1023
|
-
}
|
|
1024
|
-
if (action === "update") {
|
|
1025
|
-
await mcpMutation("kb.updateLabel", { slug, name, color, description, isGroup, order });
|
|
1026
|
-
return { content: [{ type: "text", text: `# Label Updated
|
|
1027
|
-
|
|
1028
|
-
\`${slug}\` has been updated.` }] };
|
|
1029
|
-
}
|
|
1030
|
-
if (action === "delete") {
|
|
1031
|
-
await mcpMutation("kb.deleteLabel", { slug });
|
|
1032
|
-
return { content: [{ type: "text", text: `# Label Deleted
|
|
1033
|
-
|
|
1034
|
-
\`${slug}\` removed from all entries and deleted.` }] };
|
|
1035
|
-
}
|
|
1036
|
-
return { content: [{ type: "text", text: "Unknown action." }] };
|
|
1037
|
-
}
|
|
1038
|
-
);
|
|
1039
|
-
server2.registerTool(
|
|
1040
|
-
"label-entry",
|
|
1041
|
-
{
|
|
1042
|
-
title: "Tag Entry with Label",
|
|
1043
|
-
description: "Apply or remove a label from a knowledge entry. Labels work across all collections for cross-domain filtering. Use list-labels to see available label slugs.",
|
|
1044
|
-
inputSchema: {
|
|
1045
|
-
action: z2.enum(["apply", "remove"]).describe("Apply or remove the label"),
|
|
1046
|
-
entryId: z2.string().describe("Entry ID, e.g. 'T-SUPPLIER', 'EVT-workspace_created'"),
|
|
1047
|
-
label: z2.string().describe("Label slug to apply/remove")
|
|
1048
|
-
}
|
|
1049
|
-
},
|
|
1050
|
-
async ({ action, entryId, label }) => {
|
|
1051
|
-
if (action === "apply") {
|
|
1052
|
-
await mcpMutation("kb.applyLabel", { entryId, labelSlug: label });
|
|
1053
|
-
return { content: [{ type: "text", text: `Label \`${label}\` applied to **${entryId}**.` }] };
|
|
1054
|
-
}
|
|
1055
|
-
await mcpMutation("kb.removeLabel", { entryId, labelSlug: label });
|
|
1056
|
-
return { content: [{ type: "text", text: `Label \`${label}\` removed from **${entryId}**.` }] };
|
|
1057
|
-
}
|
|
1058
|
-
);
|
|
1059
|
-
}
|
|
1060
|
-
|
|
1061
|
-
// src/tools/health.ts
|
|
1062
|
-
import { z as z3 } from "zod";
|
|
1063
|
-
var CALL_CATEGORIES = {
|
|
1064
|
-
"kb.getEntry": "read",
|
|
1065
|
-
"kb.listEntries": "read",
|
|
1066
|
-
"kb.listEntryHistory": "read",
|
|
1067
|
-
"kb.listEntryRelations": "read",
|
|
1068
|
-
"kb.listEntriesByLabel": "read",
|
|
1069
|
-
"kb.searchEntries": "search",
|
|
1070
|
-
"kb.createEntry": "write",
|
|
1071
|
-
"kb.updateEntry": "write",
|
|
1072
|
-
"kb.createEntryRelation": "write",
|
|
1073
|
-
"kb.applyLabel": "label",
|
|
1074
|
-
"kb.removeLabel": "label",
|
|
1075
|
-
"kb.createLabel": "label",
|
|
1076
|
-
"kb.updateLabel": "label",
|
|
1077
|
-
"kb.deleteLabel": "label",
|
|
1078
|
-
"kb.listCollections": "meta",
|
|
1079
|
-
"kb.getCollection": "meta",
|
|
1080
|
-
"kb.listLabels": "meta",
|
|
1081
|
-
"resolveWorkspace": "meta"
|
|
1082
|
-
};
|
|
1083
|
-
function categorize(fn) {
|
|
1084
|
-
return CALL_CATEGORIES[fn] ?? "meta";
|
|
1085
|
-
}
|
|
1086
|
-
function formatDuration(ms) {
|
|
1087
|
-
if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
|
|
1088
|
-
const mins = Math.floor(ms / 6e4);
|
|
1089
|
-
const secs = Math.round(ms % 6e4 / 1e3);
|
|
1090
|
-
return `${mins}m ${secs}s`;
|
|
1091
|
-
}
|
|
1092
|
-
function buildSessionSummary(log2) {
|
|
1093
|
-
if (log2.length === 0) return "";
|
|
1094
|
-
const byCategory = /* @__PURE__ */ new Map();
|
|
1095
|
-
let errorCount = 0;
|
|
1096
|
-
let writeCreates = 0;
|
|
1097
|
-
let writeUpdates = 0;
|
|
1098
|
-
for (const entry of log2) {
|
|
1099
|
-
const cat = categorize(entry.fn);
|
|
1100
|
-
if (!byCategory.has(cat)) byCategory.set(cat, /* @__PURE__ */ new Map());
|
|
1101
|
-
const fnCounts = byCategory.get(cat);
|
|
1102
|
-
fnCounts.set(entry.fn, (fnCounts.get(entry.fn) ?? 0) + 1);
|
|
1103
|
-
if (entry.status === "error") errorCount++;
|
|
1104
|
-
if (entry.fn === "kb.createEntry" && entry.status === "ok") writeCreates++;
|
|
1105
|
-
if (entry.fn === "kb.updateEntry" && entry.status === "ok") writeUpdates++;
|
|
1106
|
-
}
|
|
1107
|
-
const firstTs = new Date(log2[0].ts).getTime();
|
|
1108
|
-
const lastTs = new Date(log2[log2.length - 1].ts).getTime();
|
|
1109
|
-
const duration = formatDuration(lastTs - firstTs);
|
|
1110
|
-
const lines = [`# Session Summary (${duration})
|
|
1111
|
-
`];
|
|
1112
|
-
const categoryLabels = [
|
|
1113
|
-
["read", "Reads"],
|
|
1114
|
-
["search", "Searches"],
|
|
1115
|
-
["write", "Writes"],
|
|
1116
|
-
["label", "Labels"],
|
|
1117
|
-
["meta", "Meta"]
|
|
1118
|
-
];
|
|
1119
|
-
for (const [cat, label] of categoryLabels) {
|
|
1120
|
-
const fnCounts = byCategory.get(cat);
|
|
1121
|
-
if (!fnCounts || fnCounts.size === 0) continue;
|
|
1122
|
-
const total = [...fnCounts.values()].reduce((a, b) => a + b, 0);
|
|
1123
|
-
const detail = [...fnCounts.entries()].sort((a, b) => b[1] - a[1]).map(([fn, count]) => `${fn.replace("kb.", "")} x${count}`).join(", ");
|
|
1124
|
-
lines.push(`- **${label}:** ${total} call${total === 1 ? "" : "s"} (${detail})`);
|
|
1125
|
-
}
|
|
1126
|
-
lines.push(`- **Errors:** ${errorCount}`);
|
|
1127
|
-
if (writeCreates > 0 || writeUpdates > 0) {
|
|
1128
|
-
lines.push("");
|
|
1129
|
-
lines.push("## Knowledge Contribution");
|
|
1130
|
-
if (writeCreates > 0) lines.push(`- ${writeCreates} entr${writeCreates === 1 ? "y" : "ies"} created`);
|
|
1131
|
-
if (writeUpdates > 0) lines.push(`- ${writeUpdates} entr${writeUpdates === 1 ? "y" : "ies"} updated`);
|
|
1132
|
-
}
|
|
1133
|
-
return lines.join("\n");
|
|
1134
|
-
}
|
|
1135
|
-
function registerHealthTools(server2) {
|
|
1136
|
-
server2.registerTool(
|
|
1137
|
-
"health",
|
|
1138
|
-
{
|
|
1139
|
-
title: "Health Check",
|
|
1140
|
-
description: "Verify that Product Brain is running and can reach its backend. Returns workspace status, collection count, entry count, and latency. Use this to confirm connectivity before doing real work.",
|
|
1141
|
-
annotations: { readOnlyHint: true }
|
|
1142
|
-
},
|
|
1143
|
-
async () => {
|
|
1144
|
-
const start = Date.now();
|
|
1145
|
-
const errors = [];
|
|
1146
|
-
let workspaceId2;
|
|
1147
|
-
try {
|
|
1148
|
-
workspaceId2 = await getWorkspaceId();
|
|
1149
|
-
} catch (e) {
|
|
1150
|
-
errors.push(`Workspace resolution failed: ${e.message}`);
|
|
1151
|
-
}
|
|
1152
|
-
let collections = [];
|
|
1153
|
-
try {
|
|
1154
|
-
collections = await mcpQuery("kb.listCollections");
|
|
1155
|
-
} catch (e) {
|
|
1156
|
-
errors.push(`Collection fetch failed: ${e.message}`);
|
|
1157
|
-
}
|
|
1158
|
-
let totalEntries = 0;
|
|
1159
|
-
if (collections.length > 0) {
|
|
1160
|
-
try {
|
|
1161
|
-
const entries = await mcpQuery("kb.listEntries", {});
|
|
1162
|
-
totalEntries = entries.length;
|
|
1163
|
-
} catch (e) {
|
|
1164
|
-
errors.push(`Entry count failed: ${e.message}`);
|
|
1165
|
-
}
|
|
1166
|
-
}
|
|
1167
|
-
const durationMs = Date.now() - start;
|
|
1168
|
-
const healthy = errors.length === 0;
|
|
1169
|
-
const lines = [
|
|
1170
|
-
`# ${healthy ? "Healthy" : "Degraded"}`,
|
|
1171
|
-
"",
|
|
1172
|
-
`**Workspace:** ${workspaceId2 ?? "unresolved"}`,
|
|
1173
|
-
`**Collections:** ${collections.length}`,
|
|
1174
|
-
`**Entries:** ${totalEntries}`,
|
|
1175
|
-
`**Latency:** ${durationMs}ms`
|
|
1176
|
-
];
|
|
1177
|
-
if (errors.length > 0) {
|
|
1178
|
-
lines.push("", "## Errors");
|
|
1179
|
-
for (const err of errors) {
|
|
1180
|
-
lines.push(`- ${err}`);
|
|
1181
|
-
}
|
|
1182
|
-
}
|
|
1183
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
1184
|
-
}
|
|
1185
|
-
);
|
|
1186
|
-
server2.registerTool(
|
|
1187
|
-
"mcp-audit",
|
|
1188
|
-
{
|
|
1189
|
-
title: "Session Audit Log",
|
|
1190
|
-
description: "Show a session summary (reads, writes, searches, contributions) and the last N backend calls. Useful for debugging, tracing tool behavior, and seeing what you contributed to the knowledge base.",
|
|
1191
|
-
inputSchema: {
|
|
1192
|
-
limit: z3.number().min(1).max(50).default(20).describe("How many recent calls to show (max 50)")
|
|
1193
|
-
},
|
|
1194
|
-
annotations: { readOnlyHint: true }
|
|
1195
|
-
},
|
|
1196
|
-
async ({ limit }) => {
|
|
1197
|
-
const log2 = getAuditLog();
|
|
1198
|
-
const recent = log2.slice(-limit);
|
|
1199
|
-
if (recent.length === 0) {
|
|
1200
|
-
return { content: [{ type: "text", text: "No calls recorded yet this session." }] };
|
|
1201
|
-
}
|
|
1202
|
-
const summary = buildSessionSummary(log2);
|
|
1203
|
-
const logLines = [`# Audit Log (last ${recent.length} of ${log2.length} total)
|
|
1204
|
-
`];
|
|
1205
|
-
for (const entry of recent) {
|
|
1206
|
-
const icon = entry.status === "ok" ? "\u2713" : "\u2717";
|
|
1207
|
-
const errPart = entry.error ? ` \u2014 ${entry.error}` : "";
|
|
1208
|
-
logLines.push(`${icon} \`${entry.fn}\` ${entry.durationMs}ms ${entry.status}${errPart}`);
|
|
1209
|
-
}
|
|
1210
|
-
return {
|
|
1211
|
-
content: [{ type: "text", text: `${summary}
|
|
1212
|
-
|
|
1213
|
-
---
|
|
1214
|
-
|
|
1215
|
-
${logLines.join("\n")}` }]
|
|
1216
|
-
};
|
|
1217
|
-
}
|
|
1218
|
-
);
|
|
1219
|
-
}
|
|
1220
|
-
|
|
1221
|
-
// src/tools/verify.ts
|
|
1222
|
-
import { existsSync, readFileSync } from "fs";
|
|
21
|
+
import { readFileSync } from "fs";
|
|
1223
22
|
import { resolve } from "path";
|
|
1224
|
-
import {
|
|
1225
|
-
function resolveProjectRoot() {
|
|
1226
|
-
const candidates = [
|
|
1227
|
-
process.env.WORKSPACE_PATH,
|
|
1228
|
-
process.cwd(),
|
|
1229
|
-
resolve(process.cwd(), "..")
|
|
1230
|
-
].filter(Boolean);
|
|
1231
|
-
for (const dir of candidates) {
|
|
1232
|
-
const resolved = resolve(dir);
|
|
1233
|
-
if (existsSync(resolve(resolved, "convex/schema.ts"))) return resolved;
|
|
1234
|
-
}
|
|
1235
|
-
return null;
|
|
1236
|
-
}
|
|
1237
|
-
function parseConvexSchema(schemaPath) {
|
|
1238
|
-
const content = readFileSync(schemaPath, "utf-8");
|
|
1239
|
-
const tables = /* @__PURE__ */ new Map();
|
|
1240
|
-
let currentTable = null;
|
|
1241
|
-
for (const line of content.split("\n")) {
|
|
1242
|
-
const tableMatch = line.match(/^\t(\w+):\s*defineTable\(/);
|
|
1243
|
-
if (tableMatch) {
|
|
1244
|
-
currentTable = tableMatch[1];
|
|
1245
|
-
tables.set(currentTable, /* @__PURE__ */ new Set());
|
|
1246
|
-
continue;
|
|
1247
|
-
}
|
|
1248
|
-
if (currentTable && /^\t[}\)]/.test(line) && !/^\t\t/.test(line)) {
|
|
1249
|
-
currentTable = null;
|
|
1250
|
-
continue;
|
|
1251
|
-
}
|
|
1252
|
-
if (currentTable) {
|
|
1253
|
-
const fieldMatch = line.match(/^\t\t(\w+):\s*v\./);
|
|
1254
|
-
if (fieldMatch) tables.get(currentTable).add(fieldMatch[1]);
|
|
1255
|
-
}
|
|
1256
|
-
}
|
|
1257
|
-
return tables;
|
|
1258
|
-
}
|
|
1259
|
-
function cleanFieldRef(field) {
|
|
1260
|
-
return field.replace(/\s*\(.*\)\s*$/, "").replace(/\s*=\s*.*$/, "").trim();
|
|
1261
|
-
}
|
|
1262
|
-
function splitMultiRefs(field) {
|
|
1263
|
-
if (field.includes(" + ")) return field.split(/\s*\+\s*/);
|
|
1264
|
-
return [field];
|
|
1265
|
-
}
|
|
1266
|
-
var FILE_EXT_RE = /\.(ts|js|svelte|json|css|md|jsx|tsx|mjs|cjs)(?:\s|$)/i;
|
|
1267
|
-
function classifyRef(cleaned) {
|
|
1268
|
-
if (cleaned.includes("/") || FILE_EXT_RE.test(cleaned) || /^\.\w+/.test(cleaned)) {
|
|
1269
|
-
return "file";
|
|
1270
|
-
}
|
|
1271
|
-
if (/^\w+\.\w+$/.test(cleaned)) return "schema";
|
|
1272
|
-
if (/^\w+\s+table$/i.test(cleaned)) return "schema";
|
|
1273
|
-
return "conceptual";
|
|
1274
|
-
}
|
|
1275
|
-
function checkFileRef(ref, root) {
|
|
1276
|
-
const filePart = ref.split(/\s+/)[0];
|
|
1277
|
-
const fullPath = resolve(root, filePart);
|
|
1278
|
-
if (existsSync(fullPath)) return { result: "verified", reason: "exists" };
|
|
1279
|
-
return { result: "drifted", reason: `not found: ${filePart}` };
|
|
1280
|
-
}
|
|
1281
|
-
function checkSchemaRef(ref, schema) {
|
|
1282
|
-
const tableOnlyMatch = ref.match(/^(\w+)\s+table$/i);
|
|
1283
|
-
if (tableOnlyMatch) {
|
|
1284
|
-
const table = tableOnlyMatch[1];
|
|
1285
|
-
if (schema.has(table)) return { result: "verified", reason: `table "${table}" exists` };
|
|
1286
|
-
return { result: "drifted", reason: `table "${table}" not found in schema` };
|
|
1287
|
-
}
|
|
1288
|
-
const dotIdx = ref.indexOf(".");
|
|
1289
|
-
if (dotIdx > 0) {
|
|
1290
|
-
const table = ref.slice(0, dotIdx);
|
|
1291
|
-
const field = ref.slice(dotIdx + 1);
|
|
1292
|
-
if (!schema.has(table)) return { result: "drifted", reason: `table "${table}" not found in schema` };
|
|
1293
|
-
if (!schema.get(table).has(field)) return { result: "drifted", reason: `field "${field}" not found in table "${table}"` };
|
|
1294
|
-
return { result: "verified", reason: `${table}.${field} exists` };
|
|
1295
|
-
}
|
|
1296
|
-
return { result: "unverifiable", reason: "could not parse schema reference" };
|
|
1297
|
-
}
|
|
1298
|
-
function formatTrustReport(collection, entryCount, mappings, refs, fixes, mode, schemaTableCount, projectRoot) {
|
|
1299
|
-
const verified = mappings.filter((c) => c.result === "verified").length;
|
|
1300
|
-
const drifted = mappings.filter((c) => c.result === "drifted").length;
|
|
1301
|
-
const unverifiable = mappings.filter((c) => c.result === "unverifiable").length;
|
|
1302
|
-
const refsValid = refs.filter((c) => c.found).length;
|
|
1303
|
-
const refsBroken = refs.filter((c) => !c.found).length;
|
|
1304
|
-
const totalChecks = mappings.length + refs.length;
|
|
1305
|
-
const totalPassed = verified + refsValid;
|
|
1306
|
-
const trustScore = totalChecks > 0 ? Math.round(totalPassed / totalChecks * 100) : 100;
|
|
1307
|
-
const lines = [
|
|
1308
|
-
`# Trust Report: ${collection} (${entryCount} entries scanned)`,
|
|
1309
|
-
""
|
|
1310
|
-
];
|
|
1311
|
-
if (mappings.length > 0) {
|
|
1312
|
-
lines.push(
|
|
1313
|
-
"## Code Mapping Verification",
|
|
1314
|
-
`- ${mappings.length} mappings checked`,
|
|
1315
|
-
`- ${verified} verified (${Math.round(verified / mappings.length * 100)}%)`,
|
|
1316
|
-
`- ${drifted} drifted (file/schema not found)`,
|
|
1317
|
-
`- ${unverifiable} unverifiable (conceptual \u2014 skipped)`,
|
|
1318
|
-
""
|
|
1319
|
-
);
|
|
1320
|
-
}
|
|
1321
|
-
if (drifted > 0) {
|
|
1322
|
-
lines.push("### Drifted Mappings");
|
|
1323
|
-
for (const mc of mappings.filter((c) => c.result === "drifted")) {
|
|
1324
|
-
lines.push(`- **${mc.entryId}** (${mc.entryName}): \`${mc.field}\` \u2014 ${mc.reason}`);
|
|
1325
|
-
}
|
|
1326
|
-
lines.push("");
|
|
1327
|
-
}
|
|
1328
|
-
if (unverifiable > 0) {
|
|
1329
|
-
lines.push("### Unverifiable (Conceptual)");
|
|
1330
|
-
for (const mc of mappings.filter((c) => c.result === "unverifiable")) {
|
|
1331
|
-
lines.push(`- **${mc.entryId}** (${mc.entryName}): \`${mc.field}\``);
|
|
1332
|
-
}
|
|
1333
|
-
lines.push("");
|
|
1334
|
-
}
|
|
1335
|
-
if (refs.length > 0) {
|
|
1336
|
-
lines.push(
|
|
1337
|
-
"## Cross-Reference Verification",
|
|
1338
|
-
`- ${refs.length} references checked`,
|
|
1339
|
-
`- ${refsValid} valid (${refs.length > 0 ? Math.round(refsValid / refs.length * 100) : 0}%)`,
|
|
1340
|
-
`- ${refsBroken} broken`,
|
|
1341
|
-
""
|
|
1342
|
-
);
|
|
1343
|
-
}
|
|
1344
|
-
if (refsBroken > 0) {
|
|
1345
|
-
lines.push("### Broken References");
|
|
1346
|
-
for (const rc of refs.filter((c) => !c.found)) {
|
|
1347
|
-
lines.push(`- **${rc.entryId}** (${rc.entryName}): relatedRules \`${rc.refValue}\` \u2014 entry not found`);
|
|
1348
|
-
}
|
|
1349
|
-
lines.push("");
|
|
1350
|
-
}
|
|
1351
|
-
lines.push(`## Trust Score: ${trustScore}% (${totalPassed} of ${totalChecks} checks passed)`);
|
|
1352
|
-
if (mode === "fix" && fixes.length > 0) {
|
|
1353
|
-
lines.push(
|
|
1354
|
-
"",
|
|
1355
|
-
"## Applied Fixes",
|
|
1356
|
-
`Updated codeMapping status from \`aligned\` \u2192 \`drifted\` on ${fixes.length} entr${fixes.length === 1 ? "y" : "ies"}:`
|
|
1357
|
-
);
|
|
1358
|
-
for (const eid of fixes) lines.push(`- ${eid}`);
|
|
1359
|
-
} else if (mode === "report" && drifted > 0) {
|
|
1360
|
-
const fixable = mappings.filter((c) => c.result === "drifted" && c.currentStatus === "aligned").length;
|
|
1361
|
-
if (fixable > 0) {
|
|
1362
|
-
lines.push("", `_${fixable} mapping(s) marked "aligned" but actually drifted. Run with mode="fix" to update._`);
|
|
1363
|
-
}
|
|
1364
|
-
}
|
|
1365
|
-
lines.push("", "---", `_Schema: ${schemaTableCount} tables parsed from convex/schema.ts. Project root: ${projectRoot}_`);
|
|
1366
|
-
return lines.join("\n");
|
|
1367
|
-
}
|
|
1368
|
-
function registerVerifyTools(server2) {
|
|
1369
|
-
server2.registerTool(
|
|
1370
|
-
"verify",
|
|
1371
|
-
{
|
|
1372
|
-
title: "Verify Knowledge Base",
|
|
1373
|
-
description: "Verify knowledge entries against the actual codebase. Checks glossary code mappings (do referenced files and schema fields still exist?) and validates cross-references (do relatedRules point to real entries?). Produces a trust report with a trust score. Use mode='fix' to auto-update drifted codeMapping statuses.",
|
|
1374
|
-
inputSchema: {
|
|
1375
|
-
collection: z4.string().default("glossary").describe("Collection slug to verify (default: glossary)"),
|
|
1376
|
-
mode: z4.enum(["report", "fix"]).default("report").describe("'report' = read-only trust report. 'fix' = also update drifted codeMapping statuses.")
|
|
1377
|
-
},
|
|
1378
|
-
annotations: { readOnlyHint: false }
|
|
1379
|
-
},
|
|
1380
|
-
async ({ collection, mode }) => {
|
|
1381
|
-
const projectRoot = resolveProjectRoot();
|
|
1382
|
-
if (!projectRoot) {
|
|
1383
|
-
return {
|
|
1384
|
-
content: [{
|
|
1385
|
-
type: "text",
|
|
1386
|
-
text: "# Verification Failed\n\nCannot find project root (looked for `convex/schema.ts` in cwd and parent directory).\n\nSet `WORKSPACE_PATH` in `.env.mcp` to the absolute path of the Product Brain project root."
|
|
1387
|
-
}]
|
|
1388
|
-
};
|
|
1389
|
-
}
|
|
1390
|
-
const schema = parseConvexSchema(resolve(projectRoot, "convex/schema.ts"));
|
|
1391
|
-
await server2.sendLoggingMessage({
|
|
1392
|
-
level: "info",
|
|
1393
|
-
data: `Verifying "${collection}" against ${schema.size} schema tables at ${projectRoot}`,
|
|
1394
|
-
logger: "product-os"
|
|
1395
|
-
});
|
|
1396
|
-
const scopedEntries = await mcpQuery("kb.listEntries", { collectionSlug: collection });
|
|
1397
|
-
if (scopedEntries.length === 0) {
|
|
1398
|
-
return {
|
|
1399
|
-
content: [{ type: "text", text: `No entries found in \`${collection}\`. Nothing to verify.` }]
|
|
1400
|
-
};
|
|
1401
|
-
}
|
|
1402
|
-
let allEntryIds;
|
|
1403
|
-
try {
|
|
1404
|
-
const allEntries = await mcpQuery("kb.listEntries", {});
|
|
1405
|
-
allEntryIds = new Set(allEntries.map((e) => e.entryId).filter(Boolean));
|
|
1406
|
-
} catch {
|
|
1407
|
-
allEntryIds = new Set(scopedEntries.map((e) => e.entryId).filter(Boolean));
|
|
1408
|
-
}
|
|
1409
|
-
const mappingChecks = [];
|
|
1410
|
-
const refChecks = [];
|
|
1411
|
-
for (const entry of scopedEntries) {
|
|
1412
|
-
const eid = entry.entryId ?? entry.name;
|
|
1413
|
-
const ename = entry.name;
|
|
1414
|
-
const codeMappings = entry.data?.codeMapping ?? [];
|
|
1415
|
-
for (const cm of codeMappings) {
|
|
1416
|
-
const rawField = cm.field ?? "";
|
|
1417
|
-
for (const rawRef of splitMultiRefs(rawField)) {
|
|
1418
|
-
const cleaned = cleanFieldRef(rawRef);
|
|
1419
|
-
if (!cleaned) continue;
|
|
1420
|
-
const kind = classifyRef(cleaned);
|
|
1421
|
-
let result;
|
|
1422
|
-
let reason;
|
|
1423
|
-
if (kind === "file") {
|
|
1424
|
-
({ result, reason } = checkFileRef(cleaned, projectRoot));
|
|
1425
|
-
} else if (kind === "schema") {
|
|
1426
|
-
({ result, reason } = checkSchemaRef(cleaned, schema));
|
|
1427
|
-
} else {
|
|
1428
|
-
result = "unverifiable";
|
|
1429
|
-
reason = "conceptual reference";
|
|
1430
|
-
}
|
|
1431
|
-
mappingChecks.push({
|
|
1432
|
-
entryId: eid,
|
|
1433
|
-
entryName: ename,
|
|
1434
|
-
field: rawRef.trim(),
|
|
1435
|
-
kind,
|
|
1436
|
-
result,
|
|
1437
|
-
reason,
|
|
1438
|
-
currentStatus: cm.status ?? "unknown"
|
|
1439
|
-
});
|
|
1440
|
-
}
|
|
1441
|
-
}
|
|
1442
|
-
const MAX_CROSS_REFS = 50;
|
|
1443
|
-
const relatedRules = entry.data?.relatedRules ?? [];
|
|
1444
|
-
for (const ruleId of relatedRules) {
|
|
1445
|
-
if (refChecks.length >= MAX_CROSS_REFS) break;
|
|
1446
|
-
refChecks.push({
|
|
1447
|
-
entryId: eid,
|
|
1448
|
-
entryName: ename,
|
|
1449
|
-
refValue: ruleId,
|
|
1450
|
-
found: allEntryIds.has(ruleId)
|
|
1451
|
-
});
|
|
1452
|
-
}
|
|
1453
|
-
}
|
|
1454
|
-
const fixes = [];
|
|
1455
|
-
if (mode === "fix") {
|
|
1456
|
-
const driftedByEntry = /* @__PURE__ */ new Map();
|
|
1457
|
-
for (const mc of mappingChecks) {
|
|
1458
|
-
if (mc.result === "drifted" && mc.currentStatus === "aligned") {
|
|
1459
|
-
if (!driftedByEntry.has(mc.entryId)) driftedByEntry.set(mc.entryId, /* @__PURE__ */ new Set());
|
|
1460
|
-
driftedByEntry.get(mc.entryId).add(mc.field);
|
|
1461
|
-
}
|
|
1462
|
-
}
|
|
1463
|
-
for (const [eid, driftedFields] of driftedByEntry) {
|
|
1464
|
-
const entry = scopedEntries.find((e) => (e.entryId ?? e.name) === eid);
|
|
1465
|
-
if (!entry?.entryId) continue;
|
|
1466
|
-
const updated = (entry.data?.codeMapping ?? []).map(
|
|
1467
|
-
(cm) => cm.status === "aligned" && driftedFields.has(cm.field) ? { ...cm, status: "drifted" } : cm
|
|
1468
|
-
);
|
|
1469
|
-
await mcpMutation("kb.updateEntry", {
|
|
1470
|
-
entryId: entry.entryId,
|
|
1471
|
-
data: { codeMapping: updated }
|
|
1472
|
-
});
|
|
1473
|
-
fixes.push(entry.entryId);
|
|
1474
|
-
}
|
|
1475
|
-
}
|
|
1476
|
-
const report = formatTrustReport(
|
|
1477
|
-
collection,
|
|
1478
|
-
scopedEntries.length,
|
|
1479
|
-
mappingChecks,
|
|
1480
|
-
refChecks,
|
|
1481
|
-
fixes,
|
|
1482
|
-
mode,
|
|
1483
|
-
schema.size,
|
|
1484
|
-
projectRoot
|
|
1485
|
-
);
|
|
1486
|
-
return { content: [{ type: "text", text: report }] };
|
|
1487
|
-
}
|
|
1488
|
-
);
|
|
1489
|
-
}
|
|
1490
|
-
|
|
1491
|
-
// src/tools/smart-capture.ts
|
|
1492
|
-
import { z as z5 } from "zod";
|
|
1493
|
-
var AREA_KEYWORDS = {
|
|
1494
|
-
"Architecture": ["convex", "schema", "database", "migration", "api", "backend", "infrastructure", "scaling", "performance"],
|
|
1495
|
-
"Knowledge Base": ["knowledge", "glossary", "entry", "collection", "terminology", "drift", "graph"],
|
|
1496
|
-
"AI & MCP Integration": ["mcp", "ai", "cursor", "agent", "tool", "llm", "prompt", "context"],
|
|
1497
|
-
"Developer Experience": ["dx", "developer", "ide", "workflow", "friction", "ceremony"],
|
|
1498
|
-
"Governance & Decision-Making": ["governance", "decision", "rule", "policy", "compliance", "approval"],
|
|
1499
|
-
"Analytics & Tracking": ["analytics", "posthog", "tracking", "event", "metric", "funnel"],
|
|
1500
|
-
"Security": ["security", "auth", "api key", "permission", "access", "token"]
|
|
1501
|
-
};
|
|
1502
|
-
function inferArea(text) {
|
|
1503
|
-
const lower = text.toLowerCase();
|
|
1504
|
-
let bestArea = "";
|
|
1505
|
-
let bestScore = 0;
|
|
1506
|
-
for (const [area, keywords] of Object.entries(AREA_KEYWORDS)) {
|
|
1507
|
-
const score = keywords.filter((kw) => lower.includes(kw)).length;
|
|
1508
|
-
if (score > bestScore) {
|
|
1509
|
-
bestScore = score;
|
|
1510
|
-
bestArea = area;
|
|
1511
|
-
}
|
|
1512
|
-
}
|
|
1513
|
-
return bestArea;
|
|
1514
|
-
}
|
|
1515
|
-
function inferDomain(text) {
|
|
1516
|
-
return inferArea(text) || "";
|
|
1517
|
-
}
|
|
1518
|
-
var COMMON_CHECKS = {
|
|
1519
|
-
clearName: {
|
|
1520
|
-
id: "clear-name",
|
|
1521
|
-
label: "Clear, specific name (not vague)",
|
|
1522
|
-
check: (ctx) => ctx.name.length > 10 && !["new tension", "new entry", "untitled", "test"].includes(ctx.name.toLowerCase()),
|
|
1523
|
-
suggestion: () => "Rename to something specific \u2014 describe the actual problem or concept."
|
|
1524
|
-
},
|
|
1525
|
-
hasDescription: {
|
|
1526
|
-
id: "has-description",
|
|
1527
|
-
label: "Description provided (>50 chars)",
|
|
1528
|
-
check: (ctx) => ctx.description.length > 50,
|
|
1529
|
-
suggestion: () => "Add a fuller description explaining context and impact."
|
|
1530
|
-
},
|
|
1531
|
-
hasRelations: {
|
|
1532
|
-
id: "has-relations",
|
|
1533
|
-
label: "At least 1 relation created",
|
|
1534
|
-
check: (ctx) => ctx.linksCreated.length >= 1,
|
|
1535
|
-
suggestion: () => "Use `suggest-links` and `relate-entries` to connect this entry to related knowledge."
|
|
1536
|
-
},
|
|
1537
|
-
diverseRelations: {
|
|
1538
|
-
id: "diverse-relations",
|
|
1539
|
-
label: "Relations span multiple collections",
|
|
1540
|
-
check: (ctx) => {
|
|
1541
|
-
const colls = new Set(ctx.linksCreated.map((l) => l.targetCollection));
|
|
1542
|
-
return colls.size >= 2;
|
|
1543
|
-
},
|
|
1544
|
-
suggestion: () => "Try linking to entries in different collections (glossary, business-rules, strategy)."
|
|
1545
|
-
}
|
|
1546
|
-
};
|
|
1547
|
-
var PROFILES = /* @__PURE__ */ new Map([
|
|
1548
|
-
["tensions", {
|
|
1549
|
-
idPrefix: "TEN",
|
|
1550
|
-
governedDraft: false,
|
|
1551
|
-
descriptionField: "description",
|
|
1552
|
-
defaults: [
|
|
1553
|
-
{ key: "priority", value: "medium" },
|
|
1554
|
-
{ key: "date", value: "today" },
|
|
1555
|
-
{ key: "raised", value: "infer" },
|
|
1556
|
-
{ key: "severity", value: "infer" }
|
|
1557
|
-
],
|
|
1558
|
-
recommendedRelationTypes: ["surfaces_tension_in", "references", "belongs_to", "related_to"],
|
|
1559
|
-
inferField: (ctx) => {
|
|
1560
|
-
const fields = {};
|
|
1561
|
-
const text = `${ctx.name} ${ctx.description}`;
|
|
1562
|
-
const area = inferArea(text);
|
|
1563
|
-
if (area) fields.raised = area;
|
|
1564
|
-
if (text.toLowerCase().includes("critical") || text.toLowerCase().includes("blocker")) {
|
|
1565
|
-
fields.severity = "critical";
|
|
1566
|
-
} else if (text.toLowerCase().includes("bottleneck") || text.toLowerCase().includes("scaling") || text.toLowerCase().includes("breaking")) {
|
|
1567
|
-
fields.severity = "high";
|
|
1568
|
-
} else {
|
|
1569
|
-
fields.severity = "medium";
|
|
1570
|
-
}
|
|
1571
|
-
if (area) fields.affectedArea = area;
|
|
1572
|
-
return fields;
|
|
1573
|
-
},
|
|
1574
|
-
qualityChecks: [
|
|
1575
|
-
COMMON_CHECKS.clearName,
|
|
1576
|
-
COMMON_CHECKS.hasDescription,
|
|
1577
|
-
COMMON_CHECKS.hasRelations,
|
|
1578
|
-
{
|
|
1579
|
-
id: "has-severity",
|
|
1580
|
-
label: "Severity specified",
|
|
1581
|
-
check: (ctx) => !!ctx.data.severity && ctx.data.severity !== "",
|
|
1582
|
-
suggestion: (ctx) => {
|
|
1583
|
-
const text = `${ctx.name} ${ctx.description}`.toLowerCase();
|
|
1584
|
-
const inferred = text.includes("critical") ? "critical" : text.includes("bottleneck") ? "high" : "medium";
|
|
1585
|
-
return `Set severity \u2014 suggest: ${inferred} (based on description keywords).`;
|
|
1586
|
-
}
|
|
1587
|
-
},
|
|
1588
|
-
{
|
|
1589
|
-
id: "has-affected-area",
|
|
1590
|
-
label: "Affected area identified",
|
|
1591
|
-
check: (ctx) => !!ctx.data.affectedArea && ctx.data.affectedArea !== "",
|
|
1592
|
-
suggestion: (ctx) => {
|
|
1593
|
-
const area = inferArea(`${ctx.name} ${ctx.description}`);
|
|
1594
|
-
return area ? `Set affectedArea \u2014 suggest: "${area}" (inferred from content).` : "Specify which product area or domain this tension impacts.";
|
|
1595
|
-
}
|
|
1596
|
-
}
|
|
1597
|
-
]
|
|
1598
|
-
}],
|
|
1599
|
-
["business-rules", {
|
|
1600
|
-
idPrefix: "SOS",
|
|
1601
|
-
governedDraft: true,
|
|
1602
|
-
descriptionField: "description",
|
|
1603
|
-
defaults: [
|
|
1604
|
-
{ key: "severity", value: "medium" },
|
|
1605
|
-
{ key: "domain", value: "infer" }
|
|
1606
|
-
],
|
|
1607
|
-
recommendedRelationTypes: ["governs", "references", "conflicts_with", "related_to"],
|
|
1608
|
-
inferField: (ctx) => {
|
|
1609
|
-
const fields = {};
|
|
1610
|
-
const domain = inferDomain(`${ctx.name} ${ctx.description}`);
|
|
1611
|
-
if (domain) fields.domain = domain;
|
|
1612
|
-
return fields;
|
|
1613
|
-
},
|
|
1614
|
-
qualityChecks: [
|
|
1615
|
-
COMMON_CHECKS.clearName,
|
|
1616
|
-
COMMON_CHECKS.hasDescription,
|
|
1617
|
-
COMMON_CHECKS.hasRelations,
|
|
1618
|
-
{
|
|
1619
|
-
id: "has-rationale",
|
|
1620
|
-
label: "Rationale provided",
|
|
1621
|
-
check: (ctx) => typeof ctx.data.rationale === "string" && ctx.data.rationale.length > 10,
|
|
1622
|
-
suggestion: () => "Add a rationale explaining why this rule exists via `update-entry`."
|
|
1623
|
-
},
|
|
1624
|
-
{
|
|
1625
|
-
id: "has-domain",
|
|
1626
|
-
label: "Domain specified",
|
|
1627
|
-
check: (ctx) => !!ctx.data.domain && ctx.data.domain !== "",
|
|
1628
|
-
suggestion: (ctx) => {
|
|
1629
|
-
const domain = inferDomain(`${ctx.name} ${ctx.description}`);
|
|
1630
|
-
return domain ? `Set domain \u2014 suggest: "${domain}" (inferred from content).` : "Specify the business domain this rule belongs to.";
|
|
1631
|
-
}
|
|
1632
|
-
}
|
|
1633
|
-
]
|
|
1634
|
-
}],
|
|
1635
|
-
["glossary", {
|
|
1636
|
-
idPrefix: "GT",
|
|
1637
|
-
governedDraft: true,
|
|
1638
|
-
descriptionField: "canonical",
|
|
1639
|
-
defaults: [
|
|
1640
|
-
{ key: "category", value: "infer" }
|
|
1641
|
-
],
|
|
1642
|
-
recommendedRelationTypes: ["defines_term_for", "confused_with", "related_to", "references"],
|
|
1643
|
-
inferField: (ctx) => {
|
|
1644
|
-
const fields = {};
|
|
1645
|
-
const area = inferArea(`${ctx.name} ${ctx.description}`);
|
|
1646
|
-
if (area) {
|
|
1647
|
-
const categoryMap = {
|
|
1648
|
-
"Architecture": "Platform & Architecture",
|
|
1649
|
-
"Knowledge Base": "Knowledge Management",
|
|
1650
|
-
"AI & MCP Integration": "AI & Developer Tools",
|
|
1651
|
-
"Developer Experience": "AI & Developer Tools",
|
|
1652
|
-
"Governance & Decision-Making": "Governance & Process",
|
|
1653
|
-
"Analytics & Tracking": "Platform & Architecture",
|
|
1654
|
-
"Security": "Platform & Architecture"
|
|
1655
|
-
};
|
|
1656
|
-
fields.category = categoryMap[area] ?? "";
|
|
1657
|
-
}
|
|
1658
|
-
return fields;
|
|
1659
|
-
},
|
|
1660
|
-
qualityChecks: [
|
|
1661
|
-
COMMON_CHECKS.clearName,
|
|
1662
|
-
{
|
|
1663
|
-
id: "has-canonical",
|
|
1664
|
-
label: "Canonical definition provided (>20 chars)",
|
|
1665
|
-
check: (ctx) => {
|
|
1666
|
-
const canonical = ctx.data.canonical;
|
|
1667
|
-
return typeof canonical === "string" && canonical.length > 20;
|
|
1668
|
-
},
|
|
1669
|
-
suggestion: () => "Add a clear canonical definition \u2014 this is the single source of truth for this term."
|
|
1670
|
-
},
|
|
1671
|
-
COMMON_CHECKS.hasRelations,
|
|
1672
|
-
{
|
|
1673
|
-
id: "has-category",
|
|
1674
|
-
label: "Category assigned",
|
|
1675
|
-
check: (ctx) => !!ctx.data.category && ctx.data.category !== "",
|
|
1676
|
-
suggestion: () => "Assign a category (e.g., 'Platform & Architecture', 'Governance & Process')."
|
|
1677
|
-
}
|
|
1678
|
-
]
|
|
1679
|
-
}],
|
|
1680
|
-
["decisions", {
|
|
1681
|
-
idPrefix: "DEC",
|
|
1682
|
-
governedDraft: false,
|
|
1683
|
-
descriptionField: "rationale",
|
|
1684
|
-
defaults: [
|
|
1685
|
-
{ key: "date", value: "today" },
|
|
1686
|
-
{ key: "decidedBy", value: "infer" }
|
|
1687
|
-
],
|
|
1688
|
-
recommendedRelationTypes: ["informs", "references", "replaces", "related_to"],
|
|
1689
|
-
inferField: (ctx) => {
|
|
1690
|
-
const fields = {};
|
|
1691
|
-
const area = inferArea(`${ctx.name} ${ctx.description}`);
|
|
1692
|
-
if (area) fields.decidedBy = area;
|
|
1693
|
-
return fields;
|
|
1694
|
-
},
|
|
1695
|
-
qualityChecks: [
|
|
1696
|
-
COMMON_CHECKS.clearName,
|
|
1697
|
-
{
|
|
1698
|
-
id: "has-rationale",
|
|
1699
|
-
label: "Rationale provided (>30 chars)",
|
|
1700
|
-
check: (ctx) => {
|
|
1701
|
-
const rationale = ctx.data.rationale;
|
|
1702
|
-
return typeof rationale === "string" && rationale.length > 30;
|
|
1703
|
-
},
|
|
1704
|
-
suggestion: () => "Explain why this decision was made \u2014 what was considered and rejected?"
|
|
1705
|
-
},
|
|
1706
|
-
COMMON_CHECKS.hasRelations,
|
|
1707
|
-
{
|
|
1708
|
-
id: "has-date",
|
|
1709
|
-
label: "Decision date recorded",
|
|
1710
|
-
check: (ctx) => !!ctx.data.date && ctx.data.date !== "",
|
|
1711
|
-
suggestion: () => "Record when this decision was made."
|
|
1712
|
-
}
|
|
1713
|
-
]
|
|
1714
|
-
}],
|
|
1715
|
-
["features", {
|
|
1716
|
-
idPrefix: "FEAT",
|
|
1717
|
-
governedDraft: false,
|
|
1718
|
-
descriptionField: "description",
|
|
1719
|
-
defaults: [],
|
|
1720
|
-
recommendedRelationTypes: ["belongs_to", "depends_on", "surfaces_tension_in", "related_to"],
|
|
1721
|
-
qualityChecks: [
|
|
1722
|
-
COMMON_CHECKS.clearName,
|
|
1723
|
-
COMMON_CHECKS.hasDescription,
|
|
1724
|
-
COMMON_CHECKS.hasRelations,
|
|
1725
|
-
{
|
|
1726
|
-
id: "has-owner",
|
|
1727
|
-
label: "Owner assigned",
|
|
1728
|
-
check: (ctx) => !!ctx.data.owner && ctx.data.owner !== "",
|
|
1729
|
-
suggestion: () => "Assign an owner team or product area."
|
|
1730
|
-
},
|
|
1731
|
-
{
|
|
1732
|
-
id: "has-rationale",
|
|
1733
|
-
label: "Rationale documented",
|
|
1734
|
-
check: (ctx) => !!ctx.data.rationale && String(ctx.data.rationale).length > 20,
|
|
1735
|
-
suggestion: () => "Explain why this feature matters \u2014 what problem does it solve?"
|
|
1736
|
-
}
|
|
1737
|
-
]
|
|
1738
|
-
}]
|
|
1739
|
-
]);
|
|
1740
|
-
var FALLBACK_PROFILE = {
|
|
1741
|
-
idPrefix: "",
|
|
1742
|
-
governedDraft: false,
|
|
1743
|
-
descriptionField: "description",
|
|
1744
|
-
defaults: [],
|
|
1745
|
-
recommendedRelationTypes: ["related_to", "references"],
|
|
1746
|
-
qualityChecks: [
|
|
1747
|
-
COMMON_CHECKS.clearName,
|
|
1748
|
-
COMMON_CHECKS.hasDescription,
|
|
1749
|
-
COMMON_CHECKS.hasRelations
|
|
1750
|
-
]
|
|
1751
|
-
};
|
|
1752
|
-
function generateEntryId(prefix) {
|
|
1753
|
-
if (!prefix) return "";
|
|
1754
|
-
const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
|
|
1755
|
-
let suffix = "";
|
|
1756
|
-
for (let i = 0; i < 6; i++) {
|
|
1757
|
-
suffix += chars[Math.floor(Math.random() * chars.length)];
|
|
1758
|
-
}
|
|
1759
|
-
return `${prefix}-${suffix}`;
|
|
1760
|
-
}
|
|
1761
|
-
function extractSearchTerms(name, description) {
|
|
1762
|
-
const text = `${name} ${description}`;
|
|
1763
|
-
return text.replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length > 3).slice(0, 8).join(" ");
|
|
1764
|
-
}
|
|
1765
|
-
function computeLinkConfidence(candidate, sourceName, sourceDescription, sourceCollection, candidateCollection) {
|
|
1766
|
-
const text = `${sourceName} ${sourceDescription}`.toLowerCase();
|
|
1767
|
-
const candidateName = candidate.name.toLowerCase();
|
|
1768
|
-
let score = 0;
|
|
1769
|
-
if (text.includes(candidateName) && candidateName.length > 3) {
|
|
1770
|
-
score += 40;
|
|
1771
|
-
}
|
|
1772
|
-
const candidateWords = candidateName.split(/\s+/).filter((w) => w.length > 3);
|
|
1773
|
-
const matchingWords = candidateWords.filter((w) => text.includes(w));
|
|
1774
|
-
score += matchingWords.length / Math.max(candidateWords.length, 1) * 30;
|
|
1775
|
-
const HUB_COLLECTIONS = /* @__PURE__ */ new Set(["strategy", "features"]);
|
|
1776
|
-
if (HUB_COLLECTIONS.has(candidateCollection)) {
|
|
1777
|
-
score += 15;
|
|
1778
|
-
}
|
|
1779
|
-
if (candidateCollection !== sourceCollection) {
|
|
1780
|
-
score += 10;
|
|
1781
|
-
}
|
|
1782
|
-
return Math.min(score, 100);
|
|
1783
|
-
}
|
|
1784
|
-
function inferRelationType(sourceCollection, targetCollection, profile) {
|
|
1785
|
-
const typeMap = {
|
|
1786
|
-
tensions: {
|
|
1787
|
-
glossary: "surfaces_tension_in",
|
|
1788
|
-
"business-rules": "references",
|
|
1789
|
-
strategy: "belongs_to",
|
|
1790
|
-
features: "surfaces_tension_in",
|
|
1791
|
-
decisions: "references"
|
|
1792
|
-
},
|
|
1793
|
-
"business-rules": {
|
|
1794
|
-
glossary: "references",
|
|
1795
|
-
features: "governs",
|
|
1796
|
-
strategy: "belongs_to",
|
|
1797
|
-
tensions: "references"
|
|
1798
|
-
},
|
|
1799
|
-
glossary: {
|
|
1800
|
-
features: "defines_term_for",
|
|
1801
|
-
"business-rules": "references",
|
|
1802
|
-
strategy: "references"
|
|
1803
|
-
},
|
|
1804
|
-
decisions: {
|
|
1805
|
-
features: "informs",
|
|
1806
|
-
"business-rules": "references",
|
|
1807
|
-
strategy: "references",
|
|
1808
|
-
tensions: "references"
|
|
1809
|
-
}
|
|
1810
|
-
};
|
|
1811
|
-
return typeMap[sourceCollection]?.[targetCollection] ?? profile.recommendedRelationTypes[0] ?? "related_to";
|
|
1812
|
-
}
|
|
1813
|
-
function scoreQuality(ctx, profile) {
|
|
1814
|
-
const checks = profile.qualityChecks.map((qc) => {
|
|
1815
|
-
const passed2 = qc.check(ctx);
|
|
1816
|
-
return {
|
|
1817
|
-
id: qc.id,
|
|
1818
|
-
label: qc.label,
|
|
1819
|
-
passed: passed2,
|
|
1820
|
-
suggestion: passed2 ? void 0 : qc.suggestion?.(ctx)
|
|
1821
|
-
};
|
|
1822
|
-
});
|
|
1823
|
-
const passed = checks.filter((c) => c.passed).length;
|
|
1824
|
-
const total = checks.length;
|
|
1825
|
-
const score = total > 0 ? Math.round(passed / total * 10) : 10;
|
|
1826
|
-
return { score, maxScore: 10, checks };
|
|
1827
|
-
}
|
|
1828
|
-
function formatQualityReport(result) {
|
|
1829
|
-
const lines = [`## Quality: ${result.score}/${result.maxScore}`];
|
|
1830
|
-
for (const check of result.checks) {
|
|
1831
|
-
const icon = check.passed ? "[x]" : "[ ]";
|
|
1832
|
-
const suggestion = check.passed ? "" : ` -- ${check.suggestion ?? ""}`;
|
|
1833
|
-
lines.push(`${icon} ${check.label}${suggestion}`);
|
|
1834
|
-
}
|
|
1835
|
-
return lines.join("\n");
|
|
1836
|
-
}
|
|
1837
|
-
async function checkEntryQuality(entryId) {
|
|
1838
|
-
const entry = await mcpQuery("kb.getEntry", { entryId });
|
|
1839
|
-
if (!entry) {
|
|
1840
|
-
return {
|
|
1841
|
-
text: `Entry \`${entryId}\` not found. Try kb-search to find the right ID.`,
|
|
1842
|
-
quality: { score: 0, maxScore: 10, checks: [] }
|
|
1843
|
-
};
|
|
1844
|
-
}
|
|
1845
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
1846
|
-
const collMap = /* @__PURE__ */ new Map();
|
|
1847
|
-
for (const c of collections) collMap.set(c._id, c.slug);
|
|
1848
|
-
const collectionSlug = collMap.get(entry.collectionId) ?? "unknown";
|
|
1849
|
-
const profile = PROFILES.get(collectionSlug) ?? FALLBACK_PROFILE;
|
|
1850
|
-
const relations = await mcpQuery("kb.listEntryRelations", { entryId });
|
|
1851
|
-
const linksCreated = [];
|
|
1852
|
-
for (const r of relations) {
|
|
1853
|
-
const otherId = r.fromId === entry._id ? r.toId : r.fromId;
|
|
1854
|
-
linksCreated.push({
|
|
1855
|
-
targetEntryId: otherId,
|
|
1856
|
-
targetName: "",
|
|
1857
|
-
targetCollection: "",
|
|
1858
|
-
relationType: r.type
|
|
1859
|
-
});
|
|
1860
|
-
}
|
|
1861
|
-
const descField = profile.descriptionField;
|
|
1862
|
-
const description = typeof entry.data?.[descField] === "string" ? entry.data[descField] : "";
|
|
1863
|
-
const ctx = {
|
|
1864
|
-
collection: collectionSlug,
|
|
1865
|
-
name: entry.name,
|
|
1866
|
-
description,
|
|
1867
|
-
data: entry.data ?? {},
|
|
1868
|
-
entryId: entry.entryId ?? "",
|
|
1869
|
-
linksCreated,
|
|
1870
|
-
linksSuggested: [],
|
|
1871
|
-
collectionFields: []
|
|
1872
|
-
};
|
|
1873
|
-
const quality = scoreQuality(ctx, profile);
|
|
1874
|
-
const lines = [
|
|
1875
|
-
`# Quality Check: ${entry.entryId ?? entry.name}`,
|
|
1876
|
-
`**${entry.name}** in \`${collectionSlug}\` [${entry.status}]`,
|
|
1877
|
-
"",
|
|
1878
|
-
formatQualityReport(quality)
|
|
1879
|
-
];
|
|
1880
|
-
if (quality.score < 10) {
|
|
1881
|
-
const failedChecks = quality.checks.filter((c) => !c.passed && c.suggestion);
|
|
1882
|
-
if (failedChecks.length > 0) {
|
|
1883
|
-
lines.push("");
|
|
1884
|
-
lines.push(`_To improve: use \`update-entry\` to fill missing fields, or \`relate-entries\` to add connections._`);
|
|
1885
|
-
}
|
|
1886
|
-
}
|
|
1887
|
-
return { text: lines.join("\n"), quality };
|
|
1888
|
-
}
|
|
1889
|
-
var GOVERNED_COLLECTIONS = /* @__PURE__ */ new Set([
|
|
1890
|
-
"glossary",
|
|
1891
|
-
"business-rules",
|
|
1892
|
-
"principles",
|
|
1893
|
-
"standards",
|
|
1894
|
-
"strategy",
|
|
1895
|
-
"features"
|
|
1896
|
-
]);
|
|
1897
|
-
var AUTO_LINK_CONFIDENCE_THRESHOLD = 35;
|
|
1898
|
-
var MAX_AUTO_LINKS = 5;
|
|
1899
|
-
var MAX_SUGGESTIONS = 5;
|
|
1900
|
-
function registerSmartCaptureTools(server2) {
|
|
1901
|
-
server2.registerTool(
|
|
1902
|
-
"smart-capture",
|
|
1903
|
-
{
|
|
1904
|
-
title: "Smart Capture",
|
|
1905
|
-
description: "One-call knowledge capture: creates an entry, auto-links related entries, and returns a quality scorecard. Replaces the multi-step workflow of create-entry + suggest-links + relate-entries. Provide a collection, name, and description \u2014 everything else is inferred or auto-filled.\n\nSupported collections with smart profiles: tensions, business-rules, glossary, decisions.\nAll other collections use sensible defaults (same as quick-capture + auto-linking).\n\nAlways creates as 'draft' for governed collections. Embodies 'Capture Now, Curate Later' (PRI-81cbdq).",
|
|
1906
|
-
inputSchema: {
|
|
1907
|
-
collection: z5.string().describe("Collection slug, e.g. 'tensions', 'business-rules', 'glossary', 'decisions'"),
|
|
1908
|
-
name: z5.string().describe("Display name \u2014 be specific (e.g. 'Convex adjacency list won't scale for graph traversal')"),
|
|
1909
|
-
description: z5.string().describe("Full context \u2014 what's happening, why it matters, what you observed"),
|
|
1910
|
-
context: z5.string().optional().describe("Optional additional context (e.g. 'Observed during gather-context calls taking 700ms+')"),
|
|
1911
|
-
entryId: z5.string().optional().describe("Optional custom entry ID (e.g. 'TEN-my-id'). Auto-generated if omitted.")
|
|
1912
|
-
},
|
|
1913
|
-
annotations: { destructiveHint: false }
|
|
1914
|
-
},
|
|
1915
|
-
async ({ collection, name, description, context, entryId }) => {
|
|
1916
|
-
const profile = PROFILES.get(collection) ?? FALLBACK_PROFILE;
|
|
1917
|
-
const col = await mcpQuery("kb.getCollection", { slug: collection });
|
|
1918
|
-
if (!col) {
|
|
1919
|
-
return {
|
|
1920
|
-
content: [{ type: "text", text: `Collection \`${collection}\` not found. Use \`list-collections\` to see available collections.` }]
|
|
1921
|
-
};
|
|
1922
|
-
}
|
|
1923
|
-
const data = {};
|
|
1924
|
-
const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
|
|
1925
|
-
for (const field of col.fields ?? []) {
|
|
1926
|
-
const key = field.key;
|
|
1927
|
-
if (key === profile.descriptionField) {
|
|
1928
|
-
data[key] = description;
|
|
1929
|
-
} else if (field.type === "array" || field.type === "multi-select") {
|
|
1930
|
-
data[key] = [];
|
|
1931
|
-
} else {
|
|
1932
|
-
data[key] = "";
|
|
1933
|
-
}
|
|
1934
|
-
}
|
|
1935
|
-
for (const def of profile.defaults) {
|
|
1936
|
-
if (def.value === "today") {
|
|
1937
|
-
data[def.key] = today;
|
|
1938
|
-
} else if (def.value !== "infer") {
|
|
1939
|
-
data[def.key] = def.value;
|
|
1940
|
-
}
|
|
1941
|
-
}
|
|
1942
|
-
if (profile.inferField) {
|
|
1943
|
-
const inferred = profile.inferField({
|
|
1944
|
-
collection,
|
|
1945
|
-
name,
|
|
1946
|
-
description,
|
|
1947
|
-
context,
|
|
1948
|
-
data,
|
|
1949
|
-
entryId: "",
|
|
1950
|
-
linksCreated: [],
|
|
1951
|
-
linksSuggested: [],
|
|
1952
|
-
collectionFields: col.fields ?? []
|
|
1953
|
-
});
|
|
1954
|
-
for (const [key, val] of Object.entries(inferred)) {
|
|
1955
|
-
if (val !== void 0 && val !== "") {
|
|
1956
|
-
data[key] = val;
|
|
1957
|
-
}
|
|
1958
|
-
}
|
|
1959
|
-
}
|
|
1960
|
-
if (!data[profile.descriptionField] && !data.description && !data.canonical) {
|
|
1961
|
-
data[profile.descriptionField || "description"] = description;
|
|
1962
|
-
}
|
|
1963
|
-
const status = GOVERNED_COLLECTIONS.has(collection) ? "draft" : "draft";
|
|
1964
|
-
const finalEntryId = entryId ?? generateEntryId(profile.idPrefix);
|
|
1965
|
-
let internalId;
|
|
1966
|
-
try {
|
|
1967
|
-
internalId = await mcpMutation("kb.createEntry", {
|
|
1968
|
-
collectionSlug: collection,
|
|
1969
|
-
entryId: finalEntryId || void 0,
|
|
1970
|
-
name,
|
|
1971
|
-
status,
|
|
1972
|
-
data,
|
|
1973
|
-
createdBy: "smart-capture"
|
|
1974
|
-
});
|
|
1975
|
-
} catch (error) {
|
|
1976
|
-
const msg = error instanceof Error ? error.message : String(error);
|
|
1977
|
-
if (msg.includes("Duplicate") || msg.includes("already exists")) {
|
|
1978
|
-
return {
|
|
1979
|
-
content: [{
|
|
1980
|
-
type: "text",
|
|
1981
|
-
text: `# Cannot Capture \u2014 Duplicate Detected
|
|
1982
|
-
|
|
1983
|
-
${msg}
|
|
1984
|
-
|
|
1985
|
-
Use \`get-entry\` to inspect the existing entry, or \`update-entry\` to modify it.`
|
|
1986
|
-
}]
|
|
1987
|
-
};
|
|
1988
|
-
}
|
|
1989
|
-
throw error;
|
|
1990
|
-
}
|
|
1991
|
-
const linksCreated = [];
|
|
1992
|
-
const linksSuggested = [];
|
|
1993
|
-
const searchQuery = extractSearchTerms(name, description);
|
|
1994
|
-
if (searchQuery) {
|
|
1995
|
-
const [searchResults, allCollections] = await Promise.all([
|
|
1996
|
-
mcpQuery("kb.searchEntries", { query: searchQuery }),
|
|
1997
|
-
mcpQuery("kb.listCollections")
|
|
1998
|
-
]);
|
|
1999
|
-
const collMap = /* @__PURE__ */ new Map();
|
|
2000
|
-
for (const c of allCollections) collMap.set(c._id, c.slug);
|
|
2001
|
-
const candidates = (searchResults ?? []).filter((r) => r.entryId !== finalEntryId && r._id !== internalId).map((r) => ({
|
|
2002
|
-
...r,
|
|
2003
|
-
collSlug: collMap.get(r.collectionId) ?? "unknown",
|
|
2004
|
-
confidence: computeLinkConfidence(r, name, description, collection, collMap.get(r.collectionId) ?? "unknown")
|
|
2005
|
-
})).sort((a, b) => b.confidence - a.confidence);
|
|
2006
|
-
for (const c of candidates) {
|
|
2007
|
-
if (linksCreated.length >= MAX_AUTO_LINKS) break;
|
|
2008
|
-
if (c.confidence < AUTO_LINK_CONFIDENCE_THRESHOLD) break;
|
|
2009
|
-
if (!c.entryId || !finalEntryId) continue;
|
|
2010
|
-
const relationType = inferRelationType(collection, c.collSlug, profile);
|
|
2011
|
-
try {
|
|
2012
|
-
await mcpMutation("kb.createEntryRelation", {
|
|
2013
|
-
fromEntryId: finalEntryId,
|
|
2014
|
-
toEntryId: c.entryId,
|
|
2015
|
-
type: relationType
|
|
2016
|
-
});
|
|
2017
|
-
linksCreated.push({
|
|
2018
|
-
targetEntryId: c.entryId,
|
|
2019
|
-
targetName: c.name,
|
|
2020
|
-
targetCollection: c.collSlug,
|
|
2021
|
-
relationType
|
|
2022
|
-
});
|
|
2023
|
-
} catch {
|
|
2024
|
-
}
|
|
2025
|
-
}
|
|
2026
|
-
const linkedIds = new Set(linksCreated.map((l) => l.targetEntryId));
|
|
2027
|
-
for (const c of candidates) {
|
|
2028
|
-
if (linksSuggested.length >= MAX_SUGGESTIONS) break;
|
|
2029
|
-
if (linkedIds.has(c.entryId)) continue;
|
|
2030
|
-
if (c.confidence < 10) continue;
|
|
2031
|
-
const preview = extractPreview2(c.data, 80);
|
|
2032
|
-
const reason = c.confidence >= AUTO_LINK_CONFIDENCE_THRESHOLD ? "high relevance (already linked)" : `"${c.name.toLowerCase().split(/\s+/).filter((w) => `${name} ${description}`.toLowerCase().includes(w) && w.length > 3).slice(0, 2).join('", "')}" appears in content`;
|
|
2033
|
-
linksSuggested.push({
|
|
2034
|
-
entryId: c.entryId,
|
|
2035
|
-
name: c.name,
|
|
2036
|
-
collection: c.collSlug,
|
|
2037
|
-
reason,
|
|
2038
|
-
preview
|
|
2039
|
-
});
|
|
2040
|
-
}
|
|
2041
|
-
}
|
|
2042
|
-
const captureCtx = {
|
|
2043
|
-
collection,
|
|
2044
|
-
name,
|
|
2045
|
-
description,
|
|
2046
|
-
context,
|
|
2047
|
-
data,
|
|
2048
|
-
entryId: finalEntryId,
|
|
2049
|
-
linksCreated,
|
|
2050
|
-
linksSuggested,
|
|
2051
|
-
collectionFields: col.fields ?? []
|
|
2052
|
-
};
|
|
2053
|
-
const quality = scoreQuality(captureCtx, profile);
|
|
2054
|
-
const lines = [
|
|
2055
|
-
`# Captured: ${finalEntryId || name}`,
|
|
2056
|
-
`**${name}** added to \`${collection}\` as \`${status}\``
|
|
2057
|
-
];
|
|
2058
|
-
if (linksCreated.length > 0) {
|
|
2059
|
-
lines.push("");
|
|
2060
|
-
lines.push(`## Auto-linked (${linksCreated.length})`);
|
|
2061
|
-
for (const link of linksCreated) {
|
|
2062
|
-
lines.push(`- -> **${link.relationType}** ${link.targetEntryId}: ${link.targetName} [${link.targetCollection}]`);
|
|
2063
|
-
}
|
|
2064
|
-
}
|
|
2065
|
-
if (linksSuggested.length > 0) {
|
|
2066
|
-
lines.push("");
|
|
2067
|
-
lines.push("## Suggested links (review and use relate-entries)");
|
|
2068
|
-
for (let i = 0; i < linksSuggested.length; i++) {
|
|
2069
|
-
const s = linksSuggested[i];
|
|
2070
|
-
const preview = s.preview ? ` \u2014 ${s.preview}` : "";
|
|
2071
|
-
lines.push(`${i + 1}. **${s.entryId ?? "(no ID)"}**: ${s.name} [${s.collection}]${preview}`);
|
|
2072
|
-
}
|
|
2073
|
-
}
|
|
2074
|
-
lines.push("");
|
|
2075
|
-
lines.push(formatQualityReport(quality));
|
|
2076
|
-
const failedChecks = quality.checks.filter((c) => !c.passed);
|
|
2077
|
-
if (failedChecks.length > 0) {
|
|
2078
|
-
lines.push("");
|
|
2079
|
-
lines.push(`_To improve: \`update-entry entryId="${finalEntryId}"\` to fill missing fields._`);
|
|
2080
|
-
}
|
|
2081
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
2082
|
-
}
|
|
2083
|
-
);
|
|
2084
|
-
server2.registerTool(
|
|
2085
|
-
"quality-check",
|
|
2086
|
-
{
|
|
2087
|
-
title: "Quality Check",
|
|
2088
|
-
description: "Score an existing knowledge entry against collection-specific quality criteria. Returns a scorecard (X/10) with specific, actionable suggestions for improvement. Checks: name clarity, description completeness, relation connectedness, and collection-specific fields.\n\nUse after creating entries to assess their quality, or to audit existing entries.",
|
|
2089
|
-
inputSchema: {
|
|
2090
|
-
entryId: z5.string().describe("Entry ID to check, e.g. 'TEN-graph-db', 'GT-019', 'SOS-006'")
|
|
2091
|
-
},
|
|
2092
|
-
annotations: { readOnlyHint: true }
|
|
2093
|
-
},
|
|
2094
|
-
async ({ entryId }) => {
|
|
2095
|
-
const result = await checkEntryQuality(entryId);
|
|
2096
|
-
return { content: [{ type: "text", text: result.text }] };
|
|
2097
|
-
}
|
|
2098
|
-
);
|
|
2099
|
-
}
|
|
2100
|
-
function extractPreview2(data, maxLen) {
|
|
2101
|
-
if (!data || typeof data !== "object") return "";
|
|
2102
|
-
const raw = data.description ?? data.canonical ?? data.detail ?? data.rule ?? "";
|
|
2103
|
-
if (typeof raw !== "string" || !raw) return "";
|
|
2104
|
-
return raw.length > maxLen ? raw.substring(0, maxLen) + "..." : raw;
|
|
2105
|
-
}
|
|
2106
|
-
|
|
2107
|
-
// src/tools/architecture.ts
|
|
2108
|
-
import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
|
|
2109
|
-
import { resolve as resolve2, relative, dirname, normalize } from "path";
|
|
2110
|
-
import { z as z6 } from "zod";
|
|
2111
|
-
var COLLECTION_SLUG = "architecture";
|
|
2112
|
-
var COLLECTION_FIELDS = [
|
|
2113
|
-
{ key: "archType", label: "Architecture Type", type: "select", required: true, options: ["template", "layer", "node", "flow"], searchable: true },
|
|
2114
|
-
{ key: "templateRef", label: "Template Entry ID", type: "text", searchable: false },
|
|
2115
|
-
{ key: "layerRef", label: "Layer Entry ID", type: "text", searchable: false },
|
|
2116
|
-
{ key: "description", label: "Description", type: "text", searchable: true },
|
|
2117
|
-
{ key: "color", label: "Color", type: "text" },
|
|
2118
|
-
{ key: "icon", label: "Icon", type: "text" },
|
|
2119
|
-
{ key: "sourceNode", label: "Source Node (flows)", type: "text" },
|
|
2120
|
-
{ key: "targetNode", label: "Target Node (flows)", type: "text" },
|
|
2121
|
-
{ key: "filePaths", label: "File Paths", type: "text", searchable: true },
|
|
2122
|
-
{ key: "owner", label: "Owner (circle/role)", type: "text", searchable: true },
|
|
2123
|
-
{ key: "layerOrder", label: "Layer Order (for templates)", type: "text" },
|
|
2124
|
-
{ key: "rationale", label: "Why Here? (placement rationale)", type: "text", searchable: true },
|
|
2125
|
-
{ key: "dependsOn", label: "Allowed Dependencies (layers this can import from)", type: "text" }
|
|
2126
|
-
];
|
|
2127
|
-
async function ensureCollection() {
|
|
2128
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
2129
|
-
if (collections.some((c) => c.slug === COLLECTION_SLUG)) return;
|
|
2130
|
-
await mcpMutation("kb.createCollection", {
|
|
2131
|
-
slug: COLLECTION_SLUG,
|
|
2132
|
-
name: "Architecture",
|
|
2133
|
-
icon: "\u{1F3D7}\uFE0F",
|
|
2134
|
-
description: "System architecture map \u2014 templates, layers, nodes, and flows. Visualized in the Architecture Explorer and via MCP architecture tools.",
|
|
2135
|
-
fields: COLLECTION_FIELDS
|
|
2136
|
-
});
|
|
2137
|
-
}
|
|
2138
|
-
async function listArchEntries() {
|
|
2139
|
-
return mcpQuery("kb.listEntries", { collectionSlug: COLLECTION_SLUG });
|
|
2140
|
-
}
|
|
2141
|
-
function byTag(entries, archType) {
|
|
2142
|
-
return entries.filter((e) => e.tags?.includes(`archType:${archType}`) || e.data?.archType === archType).sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
|
|
2143
|
-
}
|
|
2144
|
-
function renderArchitectureHtml(layers, nodes, flows, templateName) {
|
|
2145
|
-
const layerHtml = layers.map((layer) => {
|
|
2146
|
-
const layerNodes = nodes.filter(
|
|
2147
|
-
(n) => n.data?.layerRef === layer.entryId
|
|
2148
|
-
);
|
|
2149
|
-
const nodeCards = layerNodes.map((n) => `
|
|
2150
|
-
<div class="node" title="${escHtml(String(n.data?.description ?? ""))}">
|
|
2151
|
-
<span class="node-icon">${escHtml(String(n.data?.icon ?? "\u25FB"))}</span>
|
|
2152
|
-
<span class="node-name">${escHtml(n.name)}</span>
|
|
2153
|
-
</div>
|
|
2154
|
-
`).join("");
|
|
2155
|
-
return `
|
|
2156
|
-
<div class="layer" style="--layer-color: ${escHtml(String(layer.data?.color ?? "#666"))}">
|
|
2157
|
-
<div class="layer-label">
|
|
2158
|
-
<span class="layer-dot"></span>
|
|
2159
|
-
<span class="layer-name">${escHtml(layer.name)}</span>
|
|
2160
|
-
<span class="layer-count">${layerNodes.length}</span>
|
|
2161
|
-
</div>
|
|
2162
|
-
<div class="layer-desc">${escHtml(String(layer.data?.description ?? ""))}</div>
|
|
2163
|
-
<div class="nodes">${nodeCards || '<span class="empty">No components</span>'}</div>
|
|
2164
|
-
</div>
|
|
2165
|
-
`;
|
|
2166
|
-
}).join("");
|
|
2167
|
-
return `<!DOCTYPE html>
|
|
2168
|
-
<html><head><meta charset="utf-8"><style>
|
|
2169
|
-
*{margin:0;padding:0;box-sizing:border-box}
|
|
2170
|
-
body{font-family:-apple-system,system-ui,sans-serif;background:#1a1a2e;color:#e0e0e0;padding:16px}
|
|
2171
|
-
h1{font-size:14px;font-weight:600;color:#a0a0c0;margin-bottom:12px;letter-spacing:.04em}
|
|
2172
|
-
.layer{border-left:3px solid var(--layer-color);padding:8px 12px;margin-bottom:8px;background:rgba(255,255,255,.03);border-radius:0 6px 6px 0}
|
|
2173
|
-
.layer-label{display:flex;align-items:center;gap:8px;margin-bottom:4px}
|
|
2174
|
-
.layer-dot{width:8px;height:8px;border-radius:50%;background:var(--layer-color)}
|
|
2175
|
-
.layer-name{font-size:12px;font-weight:600;color:#fff;letter-spacing:.03em}
|
|
2176
|
-
.layer-count{font-size:10px;color:var(--layer-color);background:rgba(255,255,255,.06);padding:1px 6px;border-radius:8px}
|
|
2177
|
-
.layer-desc{font-size:11px;color:#888;margin-bottom:6px}
|
|
2178
|
-
.nodes{display:flex;flex-wrap:wrap;gap:6px}
|
|
2179
|
-
.node{display:flex;align-items:center;gap:4px;background:rgba(255,255,255,.06);border:1px solid rgba(255,255,255,.08);border-radius:4px;padding:4px 8px;font-size:11px;cursor:default;transition:border-color .15s}
|
|
2180
|
-
.node:hover{border-color:var(--layer-color)}
|
|
2181
|
-
.node-icon{font-size:12px}
|
|
2182
|
-
.node-name{color:#ddd}
|
|
2183
|
-
.empty{font-size:11px;color:#555;font-style:italic}
|
|
2184
|
-
.flows{margin-top:12px;border-top:1px solid rgba(255,255,255,.06);padding-top:8px}
|
|
2185
|
-
.flow{font-size:11px;color:#888;padding:2px 0}
|
|
2186
|
-
.flow-arrow{color:#6366f1;margin:0 4px}
|
|
2187
|
-
</style></head><body>
|
|
2188
|
-
<h1>${escHtml(templateName)}</h1>
|
|
2189
|
-
${layerHtml}
|
|
2190
|
-
${flows.length > 0 ? `<div class="flows"><div style="font-size:10px;color:#666;margin-bottom:4px;letter-spacing:.06em">DATA FLOWS</div>${flows.map((f) => `<div class="flow">${escHtml(f.name)}<span class="flow-arrow">\u2192</span><span style="color:#aaa">${escHtml(String(f.data?.description ?? ""))}</span></div>`).join("")}</div>` : ""}
|
|
2191
|
-
</body></html>`;
|
|
2192
|
-
}
|
|
2193
|
-
function escHtml(s) {
|
|
2194
|
-
return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
|
2195
|
-
}
|
|
2196
|
-
function formatLayerText(layer, nodes) {
|
|
2197
|
-
const layerNodes = nodes.filter((n) => n.data?.layerRef === layer.entryId);
|
|
2198
|
-
const nodeList = layerNodes.map((n) => {
|
|
2199
|
-
const desc = n.data?.description ? ` \u2014 ${n.data.description}` : "";
|
|
2200
|
-
const owner = n.data?.owner ? ` (${n.data.owner})` : "";
|
|
2201
|
-
return ` - ${n.data?.icon ?? "\u25FB"} **${n.name}**${desc}${owner}`;
|
|
2202
|
-
}).join("\n");
|
|
2203
|
-
return `### ${layer.name}
|
|
2204
|
-
${layer.data?.description ?? ""}
|
|
2205
|
-
|
|
2206
|
-
${nodeList || " _No components_"}`;
|
|
2207
|
-
}
|
|
2208
|
-
var SEED_TEMPLATE = {
|
|
2209
|
-
entryId: "ARCH-tpl-product-os",
|
|
2210
|
-
name: "Product OS Default",
|
|
2211
|
-
data: {
|
|
2212
|
-
archType: "template",
|
|
2213
|
-
description: "Default 4-layer architecture: Auth \u2192 Infrastructure \u2192 Core \u2192 Features, with an outward Integration layer",
|
|
2214
|
-
layerOrder: JSON.stringify(["auth", "infrastructure", "core", "features", "integration"])
|
|
2215
|
-
}
|
|
2216
|
-
};
|
|
2217
|
-
var SEED_LAYERS = [
|
|
2218
|
-
{ entryId: "ARCH-layer-auth", name: "Auth", order: 0, data: { archType: "layer", templateRef: "ARCH-tpl-product-os", color: "#22c55e", description: "Authentication, user management, and workspace-scoped access control", icon: "\u{1F510}", dependsOn: "none", rationale: "Foundation layer. Auth depends on nothing \u2014 it is the first gate. No layer may bypass auth. All other layers depend on auth to know who the user is and which workspace they belong to." } },
|
|
2219
|
-
{ entryId: "ARCH-layer-infra", name: "Infrastructure", order: 1, data: { archType: "layer", templateRef: "ARCH-tpl-product-os", color: "#ec4899", description: "Real-time data, event tracking, and AI model infrastructure", icon: "\u2699\uFE0F", dependsOn: "Auth", rationale: "Infrastructure sits on top of Auth. It provides the database, analytics, and AI plumbing that Core and Features consume. Infra may import from Auth (needs workspace context) but never from Core or Features." } },
|
|
2220
|
-
{ entryId: "ARCH-layer-core", name: "Core", order: 2, data: { archType: "layer", templateRef: "ARCH-tpl-product-os", color: "#8b5cf6", description: "Business logic, knowledge graph, workflow engines, and MCP tooling", icon: "\u{1F9E0}", dependsOn: "Auth, Infrastructure", rationale: "Core contains business logic and engines that are UI-agnostic. It may import from Auth and Infra. Features depend on Core, but Core must never depend on Features \u2014 this is what keeps engines reusable across different UIs." } },
|
|
2221
|
-
{ entryId: "ARCH-layer-features", name: "Features", order: 3, data: { archType: "layer", templateRef: "ARCH-tpl-product-os", color: "#6366f1", description: "User-facing pages, components, and feature modules", icon: "\u2726", dependsOn: "Auth, Infrastructure, Core", rationale: "Features are the user-facing layer \u2014 SvelteKit routes, components, and page-level logic. Features may import from any lower layer but nothing above may import from Features. This is the outermost application layer." } },
|
|
2222
|
-
{ entryId: "ARCH-layer-integration", name: "Integration", order: 4, data: { archType: "layer", templateRef: "ARCH-tpl-product-os", color: "#f59e0b", description: "Outward connections to external tools, IDEs, and services", icon: "\u{1F50C}", dependsOn: "Core", rationale: "Integration is a lateral/outward layer \u2014 it connects to external systems (IDE, GitHub, Linear). It depends on Core (to expose knowledge) but sits outside the main stack. External tools call into Core via Integration, never directly into Features." } }
|
|
2223
|
-
];
|
|
2224
|
-
var SEED_NODES = [
|
|
2225
|
-
// Auth layer
|
|
2226
|
-
{ entryId: "ARCH-node-clerk", name: "Clerk", order: 0, data: { archType: "node", layerRef: "ARCH-layer-auth", color: "#22c55e", icon: "\u{1F511}", description: "Authentication provider \u2014 sign-in/sign-up pages, session management, organization-level access control. UserSync.svelte is cross-cutting layout glue (not mapped here).", filePaths: "src/routes/sign-in/, src/routes/sign-up/", owner: "Platform", rationale: "Auth layer because Clerk is the identity gate. Every request flows through auth first. No other layer provides identity." } },
|
|
2227
|
-
{ entryId: "ARCH-node-workspace", name: "Workspace Scoping", order: 1, data: { archType: "node", layerRef: "ARCH-layer-auth", color: "#22c55e", icon: "\u{1F3E2}", description: "Multi-tenancy anchor \u2014 all data is workspace-scoped via workspaceId", filePaths: "src/lib/stores/workspace.ts, convex/workspaces.ts", owner: "Platform", rationale: "Auth layer because workspace scoping is the second gate after identity. All queries require workspaceId, making this foundational." } },
|
|
2228
|
-
// Infrastructure layer
|
|
2229
|
-
{ entryId: "ARCH-node-convex", name: "Convex", order: 0, data: { archType: "node", layerRef: "ARCH-layer-infra", color: "#ec4899", icon: "\u26A1", description: "Reactive database with real-time sync, serverless functions, and type-safe API generation. Unified Collections + Entries model", filePaths: "convex/schema.ts, convex/entries.ts, convex/http.ts", owner: "Platform", rationale: "Infrastructure because Convex is raw persistence and reactivity plumbing. It stores data but has no business logic opinions. Core and Features consume it." } },
|
|
2230
|
-
{ entryId: "ARCH-node-posthog", name: "PostHog", order: 1, data: { archType: "node", layerRef: "ARCH-layer-infra", color: "#ec4899", icon: "\u{1F4CA}", description: "Product analytics \u2014 workspace-scoped events, feature flags, session replay", filePaths: "src/lib/analytics.ts, src/lib/components/PostHogWorkspaceSync.svelte", owner: "Platform", rationale: "Infrastructure because PostHog is analytics plumbing \u2014 event collection and aggregation. It has no knowledge of business domains." } },
|
|
2231
|
-
{ entryId: "ARCH-node-openrouter", name: "OpenRouter", order: 2, data: { archType: "node", layerRef: "ARCH-layer-infra", color: "#ec4899", icon: "\u{1F916}", description: "AI model routing for ChainWork artifact generation \u2014 streaming responses with format-aware prompts", filePaths: "src/routes/api/chainwork/generate/+server.ts", owner: "ChainWork", rationale: "Infrastructure because OpenRouter is an AI model gateway \u2014 it routes prompts to models. The strategy logic lives in ChainWork Engine (Core); this is just the pipe." } },
|
|
2232
|
-
// Core layer
|
|
2233
|
-
{ entryId: "ARCH-node-mcp", name: "MCP Server", order: 0, data: { archType: "node", layerRef: "ARCH-layer-core", color: "#8b5cf6", icon: "\u{1F527}", description: "20+ tools exposing the knowledge graph as AI-consumable operations \u2014 smart-capture, context assembly, verification, quality checks", filePaths: "packages/mcp-server/src/index.ts, packages/mcp-server/src/tools/", owner: "AI DX", rationale: "Core layer because the MCP server encodes business operations \u2014 smart-capture with auto-linking, quality scoring, governance rules. It depends on Infra (Convex) but never touches UI routes. Why not Infrastructure? Because it has domain opinions. Why not Features? Because it has no UI \u2014 any client (Cursor, CLI, API) can call it." } },
|
|
2234
|
-
{ entryId: "ARCH-node-knowledge-graph", name: "Knowledge Graph", order: 1, data: { archType: "node", layerRef: "ARCH-layer-core", color: "#8b5cf6", icon: "\u{1F578}\uFE0F", description: "20 collections, 170+ entries with typed cross-collection relations. Smart capture, auto-linking, quality scoring", filePaths: "convex/mcpKnowledge.ts, convex/entries.ts", owner: "Knowledge", rationale: "Core layer because the knowledge graph IS the domain model \u2014 collections, entries, relations, versioning, quality scoring. Glossary DATA, business rules DATA, tension DATA all live here. Why not Features? Because the data model exists independently of any page. The Glossary page in Features is just one way to visualize terms that Core owns. Think: Core owns the dictionary, Features owns the dictionary app." } },
|
|
2235
|
-
{ entryId: "ARCH-node-governance", name: "Governance Engine", order: 2, data: { archType: "node", layerRef: "ARCH-layer-core", color: "#8b5cf6", icon: "\u2696\uFE0F", description: "Circles, roles, consent-based decision-making, tension processing with IDM-inspired async workflows", filePaths: "convex/versioning.ts, src/lib/components/versioning/", owner: "Governance", rationale: "Core layer because governance logic (draft\u2192publish workflows, consent-based decisions, tension status rules) is business process that multiple UIs consume. Why not Features? Because the versioning system and proposal flow are reusable engines \u2014 the Governance Pages in Features are just one rendering of these rules." } },
|
|
2236
|
-
{ entryId: "ARCH-node-chainwork-engine", name: "ChainWork Engine", order: 3, data: { archType: "node", layerRef: "ARCH-layer-core", color: "#8b5cf6", icon: "\u26D3", description: "Guided strategy creation through 5-step coherence chain \u2014 AI-generated artifacts with scoring and achievements", filePaths: "src/lib/components/chainwork/config.ts, src/lib/components/chainwork/scoring.ts", owner: "ChainWork", rationale: "Core layer because the coherence chain logic, scoring algorithm, and quality gates are business rules. config.ts defines chain steps, scoring.ts computes quality \u2014 these could power a CLI or API. Why not Features? Because the ChainWork UI wizard in Features is just one skin over this engine." } },
|
|
2237
|
-
// Features layer
|
|
2238
|
-
{ entryId: "ARCH-node-command-center", name: "Command Center", order: 0, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "\u2B21", description: "Calm home screen \u2014 daily orientation, triage mode, pulse metrics, momentum tracking", filePaths: "src/routes/+page.svelte, src/lib/components/command-center/", owner: "Command Center", rationale: "Features layer because the Command Center is a SvelteKit page \u2014 PulseMetrics, NeedsAttention, DailyBriefing are UI components that assemble data from Core queries. Why not Core? Because it has no reusable business logic or engines \u2014 it is pure layout and presentation. If you deleted this page, no business rule would break." } },
|
|
2239
|
-
{ entryId: "ARCH-node-chainwork-ui", name: "ChainWork UI", order: 1, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "\u26D3", description: "Multi-step wizard for strategy artifact creation \u2014 setup, chain steps, quality gates, output", filePaths: "src/routes/chainwork/, src/lib/components/chainwork/", owner: "ChainWork", rationale: "Features layer because the ChainWork UI is the wizard interface \u2014 step navigation, form inputs, output rendering. Why not Core? Because the scoring logic and chain config ARE in Core (ChainWork Engine). This is the presentation skin over that engine. Delete this page and the engine still works via MCP." } },
|
|
2240
|
-
{ entryId: "ARCH-node-glossary", name: "Glossary", order: 2, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "Aa", description: "Canonical vocabulary management \u2014 term detail, code drift detection, inline term linking", filePaths: "src/routes/glossary/, src/lib/components/glossary/", owner: "Knowledge", rationale: "Features layer \u2014 NOT Core or Infrastructure \u2014 because this is the Glossary PAGE: the SvelteKit route for browsing, editing, and viewing terms. Why not Core? Because Core owns the glossary DATA (Knowledge Graph) and term-linking logic. The MCP server also accesses glossary terms without any page. Why not Infrastructure? Because glossary is domain-specific vocabulary, not generic plumbing. The page is one consumer of the data \u2014 Core owns the dictionary, Features owns the dictionary app." } },
|
|
2241
|
-
{ entryId: "ARCH-node-tensions", name: "Tensions", order: 3, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "\u26A1", description: "Tension capture and processing \u2014 raise, triage, resolve through governance workflow", filePaths: "src/routes/tensions/, src/lib/components/tensions/", owner: "Governance", rationale: "Features layer because this is the Tensions PAGE \u2014 the UI for raising, listing, and viewing tensions. Why not Core? Because tension data, status rules (SOS-020), and processing logic already live in Core (Governance Engine). This page is a form + list view that reads from and writes to Core. Delete it and the governance engine still processes tensions via MCP." } },
|
|
2242
|
-
{ entryId: "ARCH-node-strategy", name: "Strategy", order: 4, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "\u25A3", description: "Product strategy pages \u2014 vision, ecosystem, product areas, decision frameworks, sequencing", filePaths: "src/routes/strategy/, src/routes/bridge/, src/routes/topology/", owner: "Strategy", rationale: "Features layer because Strategy is a set of SvelteKit pages (strategy, bridge, topology) that visualize strategy entries. Why not Core? Because the strategy data (vision, principles, ecosystem layers) lives in the Knowledge Graph (Core). These pages render and allow inline editing \u2014 they consume Core downward." } },
|
|
2243
|
-
{ entryId: "ARCH-node-governance-ui", name: "Governance Pages", order: 5, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "\u25C8", description: "Roles, circles, principles, policies, decisions, proposals, business rules", filePaths: "src/routes/roles/, src/routes/circles/, src/routes/decisions/, src/routes/proposals/", owner: "Governance", rationale: "Features layer because these are governance PAGES \u2014 list views and detail views for roles, circles, decisions, proposals. Why not Core? Because the governance ENGINE (versioning, consent, IDM) IS in Core. These pages are the user-facing window into governance data. The logic doesn't live here, only the rendering." } },
|
|
2244
|
-
{ entryId: "ARCH-node-artifacts", name: "Artifacts", order: 6, data: { archType: "node", layerRef: "ARCH-layer-features", color: "#6366f1", icon: "\u{1F4C4}", description: "Strategy artifacts from ChainWork \u2014 pitches, briefs, one-pagers linked to the knowledge graph", filePaths: "src/routes/artifacts/", owner: "ChainWork", rationale: "Features layer because the Artifacts page is a list/detail view for strategy artifacts produced by ChainWork. Why not Core? Because artifact data and scoring live in Core (ChainWork Engine). This page just renders the output and links back to the knowledge graph." } },
|
|
2245
|
-
// Integration layer
|
|
2246
|
-
{ entryId: "ARCH-node-cursor", name: "Cursor IDE", order: 0, data: { archType: "node", layerRef: "ARCH-layer-integration", color: "#f59e0b", icon: "\u{1F5A5}\uFE0F", description: "AI-assisted development with MCP-powered knowledge context \u2014 smart capture, verification, context assembly in the editor", filePaths: ".cursor/mcp.json, .cursor/rules/", owner: "AI DX", rationale: "Integration layer because Cursor is an external tool that connects INTO our system via MCP. Why not Core or Features? Because Cursor itself is not our code \u2014 it's a consumer. The .cursor/ config files define how it talks to us, but Cursor lives outside our deployment boundary." } },
|
|
2247
|
-
{ entryId: "ARCH-node-github", name: "GitHub", order: 1, data: { archType: "node", layerRef: "ARCH-layer-integration", color: "#f59e0b", icon: "\u{1F419}", description: "Code repository, PR reviews with governance context, CI/CD", owner: "Platform", rationale: "Integration layer because GitHub is an external service. Why not Infrastructure? Because Infra is about plumbing we control (database, analytics). GitHub is a third-party that hooks into our Core (PR reviews checking governance rules) but is not part of our deployed application." } },
|
|
2248
|
-
{ entryId: "ARCH-node-linear", name: "Linear (planned)", order: 2, data: { archType: "node", layerRef: "ARCH-layer-integration", color: "#f59e0b", icon: "\u{1F4D0}", description: "Issue tracking, roadmap sync, tension-to-issue pipeline (planned integration)", owner: "Platform", rationale: "Integration layer because Linear is an external issue tracker. Why not Infrastructure? Because Infra is generic plumbing we run. Linear is a third-party tool we connect to. The planned pipeline bridges tensions (Core) to Linear issues \u2014 a classic outward integration pattern." } }
|
|
2249
|
-
];
|
|
2250
|
-
var SEED_FLOWS = [
|
|
2251
|
-
{ entryId: "ARCH-flow-smart-capture", name: "Smart Capture Flow", order: 0, data: { archType: "flow", sourceNode: "ARCH-node-cursor", targetNode: "ARCH-node-knowledge-graph", description: "Developer/AI calls smart-capture via MCP \u2192 entry created with auto-linking and quality score \u2192 stored in Knowledge Graph", color: "#8b5cf6" } },
|
|
2252
|
-
{ entryId: "ARCH-flow-governance", name: "Governance Flow", order: 1, data: { archType: "flow", sourceNode: "ARCH-node-tensions", targetNode: "ARCH-node-governance", description: "Tension raised \u2192 appears in Command Center \u2192 triaged \u2192 processed via IDM \u2192 decision logged", color: "#6366f1" } },
|
|
2253
|
-
{ entryId: "ARCH-flow-chainwork", name: "ChainWork Strategy Flow", order: 2, data: { archType: "flow", sourceNode: "ARCH-node-chainwork-ui", targetNode: "ARCH-node-artifacts", description: "Leader opens ChainWork \u2192 walks coherence chain \u2192 AI generates artifact \u2192 scored and published to knowledge graph", color: "#f59e0b" } },
|
|
2254
|
-
{ entryId: "ARCH-flow-knowledge-trust", name: "Knowledge Trust Flow", order: 3, data: { archType: "flow", sourceNode: "ARCH-node-mcp", targetNode: "ARCH-node-glossary", description: "MCP verify tool checks entries against codebase \u2192 file existence, schema references validated \u2192 trust scores updated", color: "#22c55e" } },
|
|
2255
|
-
{ entryId: "ARCH-flow-analytics", name: "Analytics Flow", order: 4, data: { archType: "flow", sourceNode: "ARCH-node-command-center", targetNode: "ARCH-node-posthog", description: "Feature views and actions tracked \u2192 workspace-scoped events \u2192 PostHog group analytics \u2192 Command Center metrics", color: "#ec4899" } }
|
|
2256
|
-
];
|
|
2257
|
-
function registerArchitectureTools(server2) {
|
|
2258
|
-
server2.registerTool(
|
|
2259
|
-
"show-architecture",
|
|
2260
|
-
{
|
|
2261
|
-
title: "Show Architecture",
|
|
2262
|
-
description: "Render the system architecture map \u2014 layered visualization showing where every component lives. Returns layers (Auth \u2192 Infrastructure \u2192 Core \u2192 Features \u2192 Integration) with component nodes and data flows. Optionally filter by a specific template.",
|
|
2263
|
-
inputSchema: {
|
|
2264
|
-
template: z6.string().optional().describe("Template entry ID to filter by (default: first available template)")
|
|
2265
|
-
},
|
|
2266
|
-
annotations: { readOnlyHint: true }
|
|
2267
|
-
},
|
|
2268
|
-
async ({ template }) => {
|
|
2269
|
-
await ensureCollection();
|
|
2270
|
-
const all = await listArchEntries();
|
|
2271
|
-
const templates = byTag(all, "template");
|
|
2272
|
-
const activeTemplate = template ? templates.find((t) => t.entryId === template) : templates[0];
|
|
2273
|
-
const templateName = activeTemplate?.name ?? "System Architecture";
|
|
2274
|
-
const templateId = activeTemplate?.entryId;
|
|
2275
|
-
const layers = byTag(all, "layer").filter((l) => !templateId || l.data?.templateRef === templateId);
|
|
2276
|
-
const nodes = byTag(all, "node");
|
|
2277
|
-
const flows = byTag(all, "flow");
|
|
2278
|
-
if (layers.length === 0) {
|
|
2279
|
-
return {
|
|
2280
|
-
content: [{
|
|
2281
|
-
type: "text",
|
|
2282
|
-
text: "# Architecture Explorer\n\nNo architecture data found. Use `seed-architecture` to populate the default Product OS architecture."
|
|
2283
|
-
}]
|
|
2284
|
-
};
|
|
2285
|
-
}
|
|
2286
|
-
const textLayers = layers.map((l) => formatLayerText(l, nodes)).join("\n\n");
|
|
2287
|
-
const textFlows = flows.length > 0 ? "\n\n---\n\n## Data Flows\n\n" + flows.map(
|
|
2288
|
-
(f) => `- **${f.name}**: ${f.data?.description ?? ""}`
|
|
2289
|
-
).join("\n") : "";
|
|
2290
|
-
const text = `# ${templateName}
|
|
2291
|
-
|
|
2292
|
-
${textLayers}${textFlows}`;
|
|
2293
|
-
const html = renderArchitectureHtml(layers, nodes, flows, templateName);
|
|
2294
|
-
return {
|
|
2295
|
-
content: [
|
|
2296
|
-
{ type: "text", text },
|
|
2297
|
-
{ type: "resource", resource: { uri: `ui://product-os/architecture`, mimeType: "text/html", text: html } }
|
|
2298
|
-
]
|
|
2299
|
-
};
|
|
2300
|
-
}
|
|
2301
|
-
);
|
|
2302
|
-
server2.registerTool(
|
|
2303
|
-
"explore-layer",
|
|
2304
|
-
{
|
|
2305
|
-
title: "Explore Architecture Layer",
|
|
2306
|
-
description: "Drill into a specific architecture layer to see all its component nodes with descriptions, team ownership, file paths, and linked entry counts.",
|
|
2307
|
-
inputSchema: {
|
|
2308
|
-
layer: z6.string().describe("Layer name or entry ID, e.g. 'Core' or 'ARCH-layer-core'")
|
|
2309
|
-
},
|
|
2310
|
-
annotations: { readOnlyHint: true }
|
|
2311
|
-
},
|
|
2312
|
-
async ({ layer }) => {
|
|
2313
|
-
await ensureCollection();
|
|
2314
|
-
const all = await listArchEntries();
|
|
2315
|
-
const layers = byTag(all, "layer");
|
|
2316
|
-
const target = layers.find(
|
|
2317
|
-
(l) => l.name.toLowerCase() === layer.toLowerCase() || l.entryId === layer
|
|
2318
|
-
);
|
|
2319
|
-
if (!target) {
|
|
2320
|
-
const available = layers.map((l) => `\`${l.name}\``).join(", ");
|
|
2321
|
-
return {
|
|
2322
|
-
content: [{
|
|
2323
|
-
type: "text",
|
|
2324
|
-
text: `Layer "${layer}" not found. Available layers: ${available}`
|
|
2325
|
-
}]
|
|
2326
|
-
};
|
|
2327
|
-
}
|
|
2328
|
-
const nodes = byTag(all, "node").filter((n) => n.data?.layerRef === target.entryId);
|
|
2329
|
-
const flows = byTag(all, "flow").filter(
|
|
2330
|
-
(f) => nodes.some((n) => n.entryId === f.data?.sourceNode || n.entryId === f.data?.targetNode)
|
|
2331
|
-
);
|
|
2332
|
-
const depRule = target.data?.dependsOn ? `
|
|
2333
|
-
**Dependency rule:** May import from ${target.data.dependsOn === "none" ? "nothing (foundation layer)" : target.data.dependsOn}.
|
|
2334
|
-
` : "";
|
|
2335
|
-
const layerRationale = target.data?.rationale ? `
|
|
2336
|
-
> ${target.data.rationale}
|
|
2337
|
-
` : "";
|
|
2338
|
-
const nodeDetail = nodes.map((n) => {
|
|
2339
|
-
const lines = [`#### ${n.data?.icon ?? "\u25FB"} ${n.name}`];
|
|
2340
|
-
if (n.data?.description) lines.push(String(n.data.description));
|
|
2341
|
-
if (n.data?.owner) lines.push(`**Owner:** ${n.data.owner}`);
|
|
2342
|
-
if (n.data?.filePaths) lines.push(`**Files:** \`${n.data.filePaths}\``);
|
|
2343
|
-
if (n.data?.rationale) lines.push(`
|
|
2344
|
-
**Why here?** ${n.data.rationale}`);
|
|
2345
|
-
return lines.join("\n");
|
|
2346
|
-
}).join("\n\n");
|
|
2347
|
-
const flowLines = flows.length > 0 ? "\n\n### Connected Flows\n\n" + flows.map((f) => `- ${f.name}: ${f.data?.description ?? ""}`).join("\n") : "";
|
|
2348
|
-
return {
|
|
2349
|
-
content: [{
|
|
2350
|
-
type: "text",
|
|
2351
|
-
text: `# ${target.data?.icon ?? ""} ${target.name} Layer
|
|
2352
|
-
|
|
2353
|
-
${target.data?.description ?? ""}${depRule}${layerRationale}
|
|
2354
|
-
**${nodes.length} components**
|
|
2355
|
-
|
|
2356
|
-
${nodeDetail}${flowLines}`
|
|
2357
|
-
}]
|
|
2358
|
-
};
|
|
2359
|
-
}
|
|
2360
|
-
);
|
|
2361
|
-
server2.registerTool(
|
|
2362
|
-
"show-flow",
|
|
2363
|
-
{
|
|
2364
|
-
title: "Show Architecture Flow",
|
|
2365
|
-
description: "Visualize a specific data flow path between architecture nodes \u2014 shows source, target, and description.",
|
|
2366
|
-
inputSchema: {
|
|
2367
|
-
flow: z6.string().describe("Flow name or entry ID, e.g. 'Smart Capture Flow' or 'ARCH-flow-smart-capture'")
|
|
2368
|
-
},
|
|
2369
|
-
annotations: { readOnlyHint: true }
|
|
2370
|
-
},
|
|
2371
|
-
async ({ flow }) => {
|
|
2372
|
-
await ensureCollection();
|
|
2373
|
-
const all = await listArchEntries();
|
|
2374
|
-
const flows = byTag(all, "flow");
|
|
2375
|
-
const target = flows.find(
|
|
2376
|
-
(f) => f.name.toLowerCase() === flow.toLowerCase() || f.entryId === flow
|
|
2377
|
-
);
|
|
2378
|
-
if (!target) {
|
|
2379
|
-
const available = flows.map((f) => `\`${f.name}\``).join(", ");
|
|
2380
|
-
return {
|
|
2381
|
-
content: [{
|
|
2382
|
-
type: "text",
|
|
2383
|
-
text: `Flow "${flow}" not found. Available flows: ${available}`
|
|
2384
|
-
}]
|
|
2385
|
-
};
|
|
2386
|
-
}
|
|
2387
|
-
const nodes = byTag(all, "node");
|
|
2388
|
-
const source = nodes.find((n) => n.entryId === target.data?.sourceNode);
|
|
2389
|
-
const dest = nodes.find((n) => n.entryId === target.data?.targetNode);
|
|
2390
|
-
const lines = [
|
|
2391
|
-
`# ${target.name}`,
|
|
2392
|
-
"",
|
|
2393
|
-
`**${source?.data?.icon ?? "?"} ${source?.name ?? "Unknown"}** \u2192 **${dest?.data?.icon ?? "?"} ${dest?.name ?? "Unknown"}**`,
|
|
2394
|
-
"",
|
|
2395
|
-
String(target.data?.description ?? "")
|
|
2396
|
-
];
|
|
2397
|
-
if (source) {
|
|
2398
|
-
lines.push("", `### Source: ${source.name}`, String(source.data?.description ?? ""));
|
|
2399
|
-
if (source.data?.filePaths) lines.push(`Files: \`${source.data.filePaths}\``);
|
|
2400
|
-
}
|
|
2401
|
-
if (dest) {
|
|
2402
|
-
lines.push("", `### Target: ${dest.name}`, String(dest.data?.description ?? ""));
|
|
2403
|
-
if (dest.data?.filePaths) lines.push(`Files: \`${dest.data.filePaths}\``);
|
|
2404
|
-
}
|
|
2405
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
2406
|
-
}
|
|
2407
|
-
);
|
|
2408
|
-
server2.registerTool(
|
|
2409
|
-
"seed-architecture",
|
|
2410
|
-
{
|
|
2411
|
-
title: "Seed Architecture Data",
|
|
2412
|
-
description: "Populate the architecture collection with the default Product OS architecture map. Creates the template, layers, nodes, and flows. Safe to re-run \u2014 skips existing entries.",
|
|
2413
|
-
annotations: { readOnlyHint: false }
|
|
2414
|
-
},
|
|
2415
|
-
async () => {
|
|
2416
|
-
await ensureCollection();
|
|
2417
|
-
const existing = await listArchEntries();
|
|
2418
|
-
const existingIds = new Set(existing.map((e) => e.entryId));
|
|
2419
|
-
let created = 0;
|
|
2420
|
-
let updated = 0;
|
|
2421
|
-
let unchanged = 0;
|
|
2422
|
-
const allSeeds = [
|
|
2423
|
-
{ ...SEED_TEMPLATE, order: 0, status: "active" },
|
|
2424
|
-
...SEED_LAYERS.map((l) => ({ ...l, status: "active" })),
|
|
2425
|
-
...SEED_NODES.map((n) => ({ ...n, status: "active" })),
|
|
2426
|
-
...SEED_FLOWS.map((f) => ({ ...f, status: "active" }))
|
|
2427
|
-
];
|
|
2428
|
-
for (const seed of allSeeds) {
|
|
2429
|
-
if (existingIds.has(seed.entryId)) {
|
|
2430
|
-
const existingEntry = existing.find((e) => e.entryId === seed.entryId);
|
|
2431
|
-
const existingData = existingEntry?.data ?? {};
|
|
2432
|
-
const seedData = seed.data;
|
|
2433
|
-
const hasChanges = Object.keys(seedData).some(
|
|
2434
|
-
(k) => seedData[k] !== void 0 && existingData[k] !== seedData[k]
|
|
2435
|
-
);
|
|
2436
|
-
if (hasChanges) {
|
|
2437
|
-
const mergedData = { ...existingData, ...seedData };
|
|
2438
|
-
await mcpMutation("kb.updateEntry", {
|
|
2439
|
-
entryId: seed.entryId,
|
|
2440
|
-
data: mergedData
|
|
2441
|
-
});
|
|
2442
|
-
updated++;
|
|
2443
|
-
} else {
|
|
2444
|
-
unchanged++;
|
|
2445
|
-
}
|
|
2446
|
-
continue;
|
|
2447
|
-
}
|
|
2448
|
-
await mcpMutation("kb.createEntry", {
|
|
2449
|
-
collectionSlug: COLLECTION_SLUG,
|
|
2450
|
-
entryId: seed.entryId,
|
|
2451
|
-
name: seed.name,
|
|
2452
|
-
status: seed.status,
|
|
2453
|
-
data: seed.data,
|
|
2454
|
-
order: seed.order ?? 0
|
|
2455
|
-
});
|
|
2456
|
-
created++;
|
|
2457
|
-
}
|
|
2458
|
-
return {
|
|
2459
|
-
content: [{
|
|
2460
|
-
type: "text",
|
|
2461
|
-
text: `# Architecture Seeded
|
|
2462
|
-
|
|
2463
|
-
**Created:** ${created} entries
|
|
2464
|
-
**Updated:** ${updated} (merged new fields)
|
|
2465
|
-
**Unchanged:** ${unchanged}
|
|
2466
|
-
|
|
2467
|
-
Use \`show-architecture\` to view the map.`
|
|
2468
|
-
}]
|
|
2469
|
-
};
|
|
2470
|
-
}
|
|
2471
|
-
);
|
|
2472
|
-
server2.registerTool(
|
|
2473
|
-
"check-architecture",
|
|
2474
|
-
{
|
|
2475
|
-
title: "Check Architecture Health",
|
|
2476
|
-
description: "Scan the codebase for dependency direction violations. Reads architecture layers, nodes, and their file paths from the knowledge base, then parses TypeScript/Svelte imports and checks them against the layer dependency rules (Auth \u2190 Infra \u2190 Core \u2190 Features; Integration \u2192 Core only). Returns a structured violation report.",
|
|
2477
|
-
annotations: { readOnlyHint: true }
|
|
2478
|
-
},
|
|
2479
|
-
async () => {
|
|
2480
|
-
const projectRoot = resolveProjectRoot2();
|
|
2481
|
-
if (!projectRoot) {
|
|
2482
|
-
return {
|
|
2483
|
-
content: [{
|
|
2484
|
-
type: "text",
|
|
2485
|
-
text: "# Scan Failed\n\nCannot find project root (looked for `convex/schema.ts` in cwd and parent). Set `WORKSPACE_PATH` env var to the absolute path of the Product OS project root."
|
|
2486
|
-
}]
|
|
2487
|
-
};
|
|
2488
|
-
}
|
|
2489
|
-
await ensureCollection();
|
|
2490
|
-
const all = await listArchEntries();
|
|
2491
|
-
const layers = byTag(all, "layer");
|
|
2492
|
-
const nodes = byTag(all, "node");
|
|
2493
|
-
const result = scanDependencies(projectRoot, layers, nodes);
|
|
2494
|
-
return {
|
|
2495
|
-
content: [{
|
|
2496
|
-
type: "text",
|
|
2497
|
-
text: formatScanReport(result)
|
|
2498
|
-
}]
|
|
2499
|
-
};
|
|
2500
|
-
}
|
|
2501
|
-
);
|
|
2502
|
-
}
|
|
2503
|
-
function resolveProjectRoot2() {
|
|
2504
|
-
const candidates = [
|
|
2505
|
-
process.env.WORKSPACE_PATH,
|
|
2506
|
-
process.cwd(),
|
|
2507
|
-
resolve2(process.cwd(), "..")
|
|
2508
|
-
].filter(Boolean);
|
|
2509
|
-
for (const dir of candidates) {
|
|
2510
|
-
const resolved = resolve2(dir);
|
|
2511
|
-
if (existsSync2(resolve2(resolved, "convex/schema.ts"))) return resolved;
|
|
2512
|
-
}
|
|
2513
|
-
return null;
|
|
2514
|
-
}
|
|
2515
|
-
function scanDependencies(projectRoot, layers, nodes) {
|
|
2516
|
-
const layerMap = /* @__PURE__ */ new Map();
|
|
2517
|
-
for (const l of layers) layerMap.set(l.entryId, l);
|
|
2518
|
-
const allowedDeps = buildAllowedDeps(layers);
|
|
2519
|
-
const nodePathPrefixes = buildNodePrefixes(nodes);
|
|
2520
|
-
const violations = [];
|
|
2521
|
-
const nodeResults = /* @__PURE__ */ new Map();
|
|
2522
|
-
let totalFiles = 0;
|
|
2523
|
-
let totalImports = 0;
|
|
2524
|
-
let unmapped = 0;
|
|
2525
|
-
for (const node of nodes) {
|
|
2526
|
-
const layerRef = String(node.data?.layerRef ?? "");
|
|
2527
|
-
const layer = layerMap.get(layerRef);
|
|
2528
|
-
if (!layer) continue;
|
|
2529
|
-
const filePaths = parseFilePaths(node);
|
|
2530
|
-
const nodeViolations = [];
|
|
2531
|
-
let nodeFileCount = 0;
|
|
2532
|
-
for (const fp of filePaths) {
|
|
2533
|
-
const absPath = resolve2(projectRoot, fp);
|
|
2534
|
-
const files = collectFiles(absPath);
|
|
2535
|
-
for (const file of files) {
|
|
2536
|
-
nodeFileCount++;
|
|
2537
|
-
totalFiles++;
|
|
2538
|
-
const relFile = relative(projectRoot, file);
|
|
2539
|
-
const imports = parseImports(file);
|
|
2540
|
-
for (const imp of imports) {
|
|
2541
|
-
totalImports++;
|
|
2542
|
-
const resolved = resolveImport(imp, file, projectRoot);
|
|
2543
|
-
if (!resolved) {
|
|
2544
|
-
unmapped++;
|
|
2545
|
-
continue;
|
|
2546
|
-
}
|
|
2547
|
-
const targetNode = findNodeByPath(resolved, nodePathPrefixes);
|
|
2548
|
-
if (!targetNode) {
|
|
2549
|
-
unmapped++;
|
|
2550
|
-
continue;
|
|
2551
|
-
}
|
|
2552
|
-
const targetLayerRef = String(targetNode.data?.layerRef ?? "");
|
|
2553
|
-
const targetLayer = layerMap.get(targetLayerRef);
|
|
2554
|
-
if (!targetLayer) continue;
|
|
2555
|
-
if (targetLayerRef === layerRef) continue;
|
|
2556
|
-
const allowed = allowedDeps.get(layerRef);
|
|
2557
|
-
if (allowed && !allowed.has(targetLayerRef)) {
|
|
2558
|
-
const v = {
|
|
2559
|
-
sourceNode: node.name,
|
|
2560
|
-
sourceLayer: layer.name,
|
|
2561
|
-
sourceFile: relFile,
|
|
2562
|
-
importPath: imp,
|
|
2563
|
-
targetNode: targetNode.name,
|
|
2564
|
-
targetLayer: targetLayer.name,
|
|
2565
|
-
rule: `${layer.name} cannot import from ${targetLayer.name}`
|
|
2566
|
-
};
|
|
2567
|
-
violations.push(v);
|
|
2568
|
-
nodeViolations.push(v);
|
|
2569
|
-
}
|
|
2570
|
-
}
|
|
2571
|
-
}
|
|
2572
|
-
}
|
|
2573
|
-
nodeResults.set(node.entryId, { violations: nodeViolations, filesScanned: nodeFileCount });
|
|
2574
|
-
}
|
|
2575
|
-
return { violations, filesScanned: totalFiles, importsChecked: totalImports, unmappedImports: unmapped, nodeResults };
|
|
2576
|
-
}
|
|
2577
|
-
function buildAllowedDeps(layers) {
|
|
2578
|
-
const nameToId = /* @__PURE__ */ new Map();
|
|
2579
|
-
for (const l of layers) nameToId.set(l.name.toLowerCase(), l.entryId);
|
|
2580
|
-
const allowed = /* @__PURE__ */ new Map();
|
|
2581
|
-
for (const layer of layers) {
|
|
2582
|
-
const deps = String(layer.data?.dependsOn ?? "none");
|
|
2583
|
-
const set = /* @__PURE__ */ new Set();
|
|
2584
|
-
if (deps !== "none") {
|
|
2585
|
-
for (const dep of deps.split(",").map((d) => d.trim().toLowerCase())) {
|
|
2586
|
-
const id = nameToId.get(dep);
|
|
2587
|
-
if (id) set.add(id);
|
|
2588
|
-
}
|
|
2589
|
-
}
|
|
2590
|
-
allowed.set(layer.entryId, set);
|
|
2591
|
-
}
|
|
2592
|
-
return allowed;
|
|
2593
|
-
}
|
|
2594
|
-
function buildNodePrefixes(nodes) {
|
|
2595
|
-
const entries = [];
|
|
2596
|
-
for (const node of nodes) {
|
|
2597
|
-
for (const fp of parseFilePaths(node)) {
|
|
2598
|
-
entries.push({ prefix: normalize(fp), node });
|
|
2599
|
-
}
|
|
2600
|
-
}
|
|
2601
|
-
entries.sort((a, b) => b.prefix.length - a.prefix.length);
|
|
2602
|
-
return entries;
|
|
2603
|
-
}
|
|
2604
|
-
function parseFilePaths(node) {
|
|
2605
|
-
const raw = node.data?.filePaths;
|
|
2606
|
-
if (!raw || typeof raw !== "string") return [];
|
|
2607
|
-
return raw.split(",").map((p) => p.trim()).filter(Boolean);
|
|
2608
|
-
}
|
|
2609
|
-
function collectFiles(absPath) {
|
|
2610
|
-
if (!existsSync2(absPath)) return [];
|
|
2611
|
-
const stat = statSync(absPath);
|
|
2612
|
-
if (stat.isFile()) {
|
|
2613
|
-
return isScannableFile(absPath) ? [absPath] : [];
|
|
2614
|
-
}
|
|
2615
|
-
if (!stat.isDirectory()) return [];
|
|
2616
|
-
const results = [];
|
|
2617
|
-
const walk = (dir) => {
|
|
2618
|
-
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
2619
|
-
if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
|
|
2620
|
-
const full = resolve2(dir, entry.name);
|
|
2621
|
-
if (entry.isDirectory()) walk(full);
|
|
2622
|
-
else if (isScannableFile(full)) results.push(full);
|
|
2623
|
-
}
|
|
2624
|
-
};
|
|
2625
|
-
walk(absPath);
|
|
2626
|
-
return results;
|
|
2627
|
-
}
|
|
2628
|
-
function isScannableFile(p) {
|
|
2629
|
-
return /\.(ts|js|svelte)$/.test(p) && !p.endsWith(".d.ts");
|
|
2630
|
-
}
|
|
2631
|
-
function parseImports(filePath) {
|
|
2632
|
-
try {
|
|
2633
|
-
const content = readFileSync2(filePath, "utf-8");
|
|
2634
|
-
const re = /(?:^|\n)\s*import\s+(?:[\s\S]*?\s+from\s+)?['"]([^'"]+)['"]/g;
|
|
2635
|
-
const imports = [];
|
|
2636
|
-
let match;
|
|
2637
|
-
while ((match = re.exec(content)) !== null) {
|
|
2638
|
-
imports.push(match[1]);
|
|
2639
|
-
}
|
|
2640
|
-
return imports;
|
|
2641
|
-
} catch {
|
|
2642
|
-
return [];
|
|
2643
|
-
}
|
|
2644
|
-
}
|
|
2645
|
-
var EXTENSIONS = [".ts", ".js", ".svelte", "/index.ts", "/index.js", "/index.svelte"];
|
|
2646
|
-
function tryResolveWithExtension(absPath) {
|
|
2647
|
-
if (existsSync2(absPath) && statSync(absPath).isFile()) return absPath;
|
|
2648
|
-
for (const ext of EXTENSIONS) {
|
|
2649
|
-
const withExt = absPath + ext;
|
|
2650
|
-
if (existsSync2(withExt)) return withExt;
|
|
2651
|
-
}
|
|
2652
|
-
return null;
|
|
2653
|
-
}
|
|
2654
|
-
function resolveImport(imp, fromFile, root) {
|
|
2655
|
-
let rel = null;
|
|
2656
|
-
if (imp.startsWith("$lib/")) rel = imp.replace("$lib/", "src/lib/");
|
|
2657
|
-
else if (imp.startsWith("$convex/")) rel = imp.replace("$convex/", "convex/");
|
|
2658
|
-
else if (imp.startsWith("$env/") || imp.startsWith("$app/")) return null;
|
|
2659
|
-
else if (imp.startsWith("./") || imp.startsWith("../")) {
|
|
2660
|
-
const fromDir = dirname(fromFile);
|
|
2661
|
-
const abs2 = resolve2(fromDir, imp);
|
|
2662
|
-
rel = relative(root, abs2);
|
|
2663
|
-
}
|
|
2664
|
-
if (!rel) return null;
|
|
2665
|
-
const abs = resolve2(root, rel);
|
|
2666
|
-
const actual = tryResolveWithExtension(abs);
|
|
2667
|
-
return actual ? relative(root, actual) : rel;
|
|
2668
|
-
}
|
|
2669
|
-
function findNodeByPath(filePath, prefixes) {
|
|
2670
|
-
const normalized = normalize(filePath);
|
|
2671
|
-
for (const { prefix, node } of prefixes) {
|
|
2672
|
-
if (normalized.startsWith(prefix)) return node;
|
|
2673
|
-
}
|
|
2674
|
-
return null;
|
|
2675
|
-
}
|
|
2676
|
-
function formatScanReport(result) {
|
|
2677
|
-
const lines = [];
|
|
2678
|
-
if (result.violations.length === 0) {
|
|
2679
|
-
lines.push(
|
|
2680
|
-
`# Architecture Health Check Passed`,
|
|
2681
|
-
"",
|
|
2682
|
-
`**0 violations** across ${result.filesScanned} files (${result.importsChecked} imports checked, ${result.unmappedImports} unmapped).`,
|
|
2683
|
-
"",
|
|
2684
|
-
"All imports respect the layer dependency rules."
|
|
2685
|
-
);
|
|
2686
|
-
} else {
|
|
2687
|
-
lines.push(
|
|
2688
|
-
`# Architecture Health Check \u2014 ${result.violations.length} Violation${result.violations.length === 1 ? "" : "s"}`,
|
|
2689
|
-
"",
|
|
2690
|
-
`Scanned ${result.filesScanned} files, checked ${result.importsChecked} imports, found **${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}** (${result.unmappedImports} unmapped).`,
|
|
2691
|
-
""
|
|
2692
|
-
);
|
|
2693
|
-
const byNode = /* @__PURE__ */ new Map();
|
|
2694
|
-
for (const v of result.violations) {
|
|
2695
|
-
if (!byNode.has(v.sourceNode)) byNode.set(v.sourceNode, []);
|
|
2696
|
-
byNode.get(v.sourceNode).push(v);
|
|
2697
|
-
}
|
|
2698
|
-
for (const [nodeName, vs] of byNode) {
|
|
2699
|
-
lines.push(`## ${nodeName} (${vs[0].sourceLayer})`);
|
|
2700
|
-
for (const v of vs) {
|
|
2701
|
-
lines.push(`- \`${v.sourceFile}\` imports \`${v.importPath}\` \u2192 **${v.targetNode}** (${v.targetLayer}) \u2014 ${v.rule}`);
|
|
2702
|
-
}
|
|
2703
|
-
lines.push("");
|
|
2704
|
-
}
|
|
2705
|
-
}
|
|
2706
|
-
lines.push("---", "");
|
|
2707
|
-
const nodeEntries = [...result.nodeResults.entries()];
|
|
2708
|
-
const cleanCount = nodeEntries.filter(([, r]) => r.violations.length === 0 && r.filesScanned > 0).length;
|
|
2709
|
-
const dirtyCount = nodeEntries.filter(([, r]) => r.violations.length > 0).length;
|
|
2710
|
-
const emptyCount = nodeEntries.filter(([, r]) => r.filesScanned === 0).length;
|
|
2711
|
-
lines.push(
|
|
2712
|
-
`**Summary:** ${cleanCount} clean nodes, ${dirtyCount} with violations, ${emptyCount} with no files.`
|
|
2713
|
-
);
|
|
2714
|
-
return lines.join("\n");
|
|
2715
|
-
}
|
|
2716
|
-
|
|
2717
|
-
// src/tools/workflows.ts
|
|
2718
|
-
import { z as z7 } from "zod";
|
|
2719
|
-
|
|
2720
|
-
// src/workflows/definitions.ts
|
|
2721
|
-
var RETRO_WORKFLOW = {
|
|
2722
|
-
id: "retro",
|
|
2723
|
-
name: "Retrospective",
|
|
2724
|
-
shortDescription: "Structured team retrospective \u2014 reflect, surface patterns, commit to actions. Outputs a decision entry in the Knowledge Base.",
|
|
2725
|
-
icon: "\u25CE",
|
|
2726
|
-
facilitatorPreamble: `You are now in **Facilitator Mode**. You are not a coding assistant \u2014 you are a facilitator running a structured retrospective.
|
|
2727
|
-
|
|
2728
|
-
## Your Behavior
|
|
2729
|
-
|
|
2730
|
-
1. **Guide, don't solve.** Ask questions, reflect back, synthesize. Never jump to solutions.
|
|
2731
|
-
2. **One round at a time.** Complete each round fully before moving to the next. No skipping.
|
|
2732
|
-
3. **Use structured questions** (AskQuestion tool) for choices and multi-select. Use open conversation for reflection.
|
|
2733
|
-
4. **Create a Plan** at the start showing all rounds as tasks. Update it as you progress.
|
|
2734
|
-
5. **Synthesize between rounds.** After collecting input, reflect back what you heard before moving on.
|
|
2735
|
-
6. **Never go silent.** If something fails, say what happened and what to do next.
|
|
2736
|
-
7. **Capture to KB** at the end using the Product OS smart-capture tool.
|
|
2737
|
-
8. **Match the energy.** Be warm but structured. This is a ceremony, not a checklist.
|
|
2738
|
-
|
|
2739
|
-
## Communication Style
|
|
2740
|
-
|
|
2741
|
-
- Start each round with its number, name, and a brief instruction
|
|
2742
|
-
- Use quotes and emphasis to reflect back what the participant said
|
|
2743
|
-
- End each round with a brief synthesis before transitioning
|
|
2744
|
-
- When a round is complete, mark it as done in the Plan
|
|
2745
|
-
- If the participant seems stuck, offer prompts \u2014 never pressure
|
|
2746
|
-
- If a tool call fails, explain what happened and offer an alternative path
|
|
2747
|
-
|
|
2748
|
-
## Error Recovery
|
|
2749
|
-
|
|
2750
|
-
If at any point a tool call or MCP operation fails:
|
|
2751
|
-
1. Tell the participant what you were trying to do
|
|
2752
|
-
2. Explain what went wrong (briefly, no stack traces)
|
|
2753
|
-
3. Offer a manual alternative (e.g., "I'll capture this in the conversation instead")
|
|
2754
|
-
4. Continue the workflow \u2014 never halt completely
|
|
2755
|
-
|
|
2756
|
-
## Plan Structure
|
|
2757
|
-
|
|
2758
|
-
Create a Cursor Plan with these rounds as tasks. Mark each in_progress as you enter it, completed when done.`,
|
|
2759
|
-
rounds: [
|
|
2760
|
-
{
|
|
2761
|
-
id: "set-stage",
|
|
2762
|
-
num: "01",
|
|
2763
|
-
label: "Set the Stage",
|
|
2764
|
-
type: "choice",
|
|
2765
|
-
instruction: "Before we dive in, let's frame what we're reflecting on. What's the scope of this retro?",
|
|
2766
|
-
facilitatorGuidance: "Start warm. Ask the participant to pick or describe what they're retro-ing. Confirm the scope before proceeding. If they gave context already in their initial message, use it \u2014 don't make them repeat.",
|
|
2767
|
-
questions: [
|
|
2768
|
-
{
|
|
2769
|
-
id: "scope",
|
|
2770
|
-
prompt: "What are we reflecting on? Pick one or describe your own.",
|
|
2771
|
-
options: [
|
|
2772
|
-
{ id: "last-week", label: "Last week's work" },
|
|
2773
|
-
{ id: "last-sprint", label: "Last sprint/cycle" },
|
|
2774
|
-
{ id: "specific-project", label: "A specific project or feature" },
|
|
2775
|
-
{ id: "process", label: "A process or workflow" },
|
|
2776
|
-
{ id: "custom", label: "Something else \u2014 let me describe it" }
|
|
2777
|
-
]
|
|
2778
|
-
}
|
|
2779
|
-
],
|
|
2780
|
-
outputSchema: {
|
|
2781
|
-
field: "scope",
|
|
2782
|
-
description: "What timeframe or project is being retro'd",
|
|
2783
|
-
format: "freetext"
|
|
2784
|
-
},
|
|
2785
|
-
maxDurationHint: "2 min"
|
|
2786
|
-
},
|
|
2787
|
-
{
|
|
2788
|
-
id: "what-went-well",
|
|
2789
|
-
num: "02",
|
|
2790
|
-
label: "What Went Well",
|
|
2791
|
-
type: "open",
|
|
2792
|
-
instruction: "Let's start with the good. What went well? What are you proud of? What should we do more of?",
|
|
2793
|
-
facilitatorGuidance: "Celebrate. Reflect back each win with genuine emphasis. Ask follow-ups like 'What made that work?' or 'Who else contributed to that?' Collect at least 3 items before synthesizing. Don't rush past the positive \u2014 teams skip this too fast.",
|
|
2794
|
-
outputSchema: {
|
|
2795
|
-
field: "wentWell",
|
|
2796
|
-
description: "List of things that went well",
|
|
2797
|
-
format: "list"
|
|
2798
|
-
},
|
|
2799
|
-
maxDurationHint: "5 min"
|
|
2800
|
-
},
|
|
2801
|
-
{
|
|
2802
|
-
id: "what-didnt-go-well",
|
|
2803
|
-
num: "03",
|
|
2804
|
-
label: "What Didn't Go Well",
|
|
2805
|
-
type: "open",
|
|
2806
|
-
instruction: "Now the harder part. What didn't go well? What frustrated you? Where did things break down?",
|
|
2807
|
-
facilitatorGuidance: "Create safety. Acknowledge that this is harder. Don't judge or immediately problem-solve \u2014 just listen and capture. Ask 'What was the impact of that?' and 'When did you first notice it?'. Reflect back without softening. Collect at least 3 items.",
|
|
2808
|
-
outputSchema: {
|
|
2809
|
-
field: "didntGoWell",
|
|
2810
|
-
description: "List of things that didn't go well",
|
|
2811
|
-
format: "list"
|
|
2812
|
-
},
|
|
2813
|
-
maxDurationHint: "5 min"
|
|
2814
|
-
},
|
|
2815
|
-
{
|
|
2816
|
-
id: "patterns",
|
|
2817
|
-
num: "04",
|
|
2818
|
-
label: "Patterns & Insights",
|
|
2819
|
-
type: "synthesis",
|
|
2820
|
-
instruction: "Looking at what went well and what didn't \u2014 what patterns do you see? What's the deeper insight?",
|
|
2821
|
-
facilitatorGuidance: "This is YOUR moment as facilitator. Synthesize what you've heard across rounds 2 and 3. Surface themes, connections, and contradictions. Propose 2-3 patterns and ask the participant to react. This round transforms raw observations into actionable insights. Don't let the participant skip the 'why' \u2014 push for root causes.",
|
|
2822
|
-
outputSchema: {
|
|
2823
|
-
field: "patterns",
|
|
2824
|
-
description: "Synthesized patterns and insights",
|
|
2825
|
-
format: "structured"
|
|
2826
|
-
},
|
|
2827
|
-
maxDurationHint: "5 min"
|
|
2828
|
-
},
|
|
2829
|
-
{
|
|
2830
|
-
id: "actions",
|
|
2831
|
-
num: "05",
|
|
2832
|
-
label: "Actions & Commitments",
|
|
2833
|
-
type: "commit",
|
|
2834
|
-
instruction: "Based on these patterns, what will we actually change? Be specific \u2014 who does what, by when?",
|
|
2835
|
-
facilitatorGuidance: "Push for specificity. 'Be better at X' is not an action. 'Randy will set up a 15-min weekly check-in by Friday' is. Each action needs an owner and a deadline. Aim for 2-4 concrete actions. Use AskQuestion to confirm the final list. These become the retro's output.",
|
|
2836
|
-
questions: [
|
|
2837
|
-
{
|
|
2838
|
-
id: "action-confirm",
|
|
2839
|
-
prompt: "Are these actions concrete enough to actually happen?",
|
|
2840
|
-
options: [
|
|
2841
|
-
{ id: "yes", label: "Yes \u2014 these are clear and actionable" },
|
|
2842
|
-
{ id: "refine", label: "Let me refine some of these" },
|
|
2843
|
-
{ id: "add", label: "I want to add more" }
|
|
2844
|
-
]
|
|
2845
|
-
}
|
|
2846
|
-
],
|
|
2847
|
-
outputSchema: {
|
|
2848
|
-
field: "actions",
|
|
2849
|
-
description: "Committed actions with owners and deadlines",
|
|
2850
|
-
format: "structured"
|
|
2851
|
-
},
|
|
2852
|
-
maxDurationHint: "5 min"
|
|
2853
|
-
},
|
|
2854
|
-
{
|
|
2855
|
-
id: "close",
|
|
2856
|
-
num: "06",
|
|
2857
|
-
label: "Close & Capture",
|
|
2858
|
-
type: "close",
|
|
2859
|
-
instruction: "One last thing \u2014 in one sentence, what's the single most important thing you're taking away from this retro?",
|
|
2860
|
-
facilitatorGuidance: "Keep it brief. One sentence reflection. Then summarize the entire retro: scope, key wins, key pain points, patterns identified, actions committed. Ask if they want to save this to the Knowledge Base. If yes, use smart-capture to create a decision/tension entry. Thank them for the retro.",
|
|
2861
|
-
outputSchema: {
|
|
2862
|
-
field: "takeaway",
|
|
2863
|
-
description: "Single-sentence takeaway",
|
|
2864
|
-
format: "freetext"
|
|
2865
|
-
},
|
|
2866
|
-
kbCollection: "decisions",
|
|
2867
|
-
maxDurationHint: "2 min"
|
|
2868
|
-
}
|
|
2869
|
-
],
|
|
2870
|
-
kbOutputCollection: "decisions",
|
|
2871
|
-
kbOutputTemplate: {
|
|
2872
|
-
nameTemplate: "Retro: {scope} \u2014 {date}",
|
|
2873
|
-
descriptionField: "rationale"
|
|
2874
|
-
},
|
|
2875
|
-
errorRecovery: `If anything goes wrong during the retro:
|
|
2876
|
-
|
|
2877
|
-
1. **MCP tool failure**: Skip the KB capture step. Summarize everything in the conversation instead. Suggest the participant runs \`smart-capture\` manually later.
|
|
2878
|
-
2. **AskQuestion not available**: Fall back to numbered options in plain text. "Reply with 1, 2, or 3."
|
|
2879
|
-
3. **Plan creation fails**: Continue without the Plan. The conversation IS the record.
|
|
2880
|
-
4. **Participant goes off-topic**: Gently redirect: "That's valuable \u2014 let's capture it. For now, let's stay with [current round]."
|
|
2881
|
-
5. **Participant wants to stop**: Respect it. Summarize what you have so far. Offer to save partial results to KB.
|
|
2882
|
-
|
|
2883
|
-
The retro must never fail silently. Always communicate state.`
|
|
2884
|
-
};
|
|
2885
|
-
var WORKFLOWS = /* @__PURE__ */ new Map([
|
|
2886
|
-
["retro", RETRO_WORKFLOW]
|
|
2887
|
-
]);
|
|
2888
|
-
function getWorkflow(id) {
|
|
2889
|
-
return WORKFLOWS.get(id);
|
|
2890
|
-
}
|
|
2891
|
-
function listWorkflows() {
|
|
2892
|
-
return Array.from(WORKFLOWS.values());
|
|
2893
|
-
}
|
|
2894
|
-
|
|
2895
|
-
// src/tools/workflows.ts
|
|
2896
|
-
function formatWorkflowCard(wf) {
|
|
2897
|
-
const roundList = wf.rounds.map((r) => ` ${r.num}. ${r.label} (${r.type}, ~${r.maxDurationHint ?? "?"})`).join("\n");
|
|
2898
|
-
return `## ${wf.icon} ${wf.name}
|
|
2899
|
-
**ID**: \`${wf.id}\`
|
|
2900
|
-
${wf.shortDescription}
|
|
2901
|
-
|
|
2902
|
-
**Rounds** (${wf.rounds.length}):
|
|
2903
|
-
${roundList}
|
|
2904
|
-
|
|
2905
|
-
**Output**: Creates entries in \`${wf.kbOutputCollection}\` collection.
|
|
2906
|
-
_Use the \`run-workflow\` prompt with workflow="${wf.id}" to start._`;
|
|
2907
|
-
}
|
|
2908
|
-
function registerWorkflowTools(server2) {
|
|
2909
|
-
server2.registerTool(
|
|
2910
|
-
"list-workflows",
|
|
2911
|
-
{
|
|
2912
|
-
title: "List Workflows",
|
|
2913
|
-
description: "List all available Chainwork workflows \u2014 retro, shape-a-bet, IDM, etc. Each workflow is a structured multi-round facilitation ceremony that the agent runs in Facilitator Mode. Use the `run-workflow` prompt to actually launch one.",
|
|
2914
|
-
annotations: { readOnlyHint: true }
|
|
2915
|
-
},
|
|
2916
|
-
async () => {
|
|
2917
|
-
const workflows = listWorkflows();
|
|
2918
|
-
if (workflows.length === 0) {
|
|
2919
|
-
return {
|
|
2920
|
-
content: [{
|
|
2921
|
-
type: "text",
|
|
2922
|
-
text: "No workflows registered yet. Check back after the workflow definitions are configured."
|
|
2923
|
-
}]
|
|
2924
|
-
};
|
|
2925
|
-
}
|
|
2926
|
-
const cards = workflows.map(formatWorkflowCard).join("\n\n---\n\n");
|
|
2927
|
-
return {
|
|
2928
|
-
content: [{
|
|
2929
|
-
type: "text",
|
|
2930
|
-
text: `# Available Chainwork Workflows
|
|
2931
|
-
|
|
2932
|
-
${workflows.length} workflow(s) available. Use the \`run-workflow\` prompt to launch one.
|
|
2933
|
-
|
|
2934
|
-
---
|
|
2935
|
-
|
|
2936
|
-
${cards}`
|
|
2937
|
-
}]
|
|
2938
|
-
};
|
|
2939
|
-
}
|
|
2940
|
-
);
|
|
2941
|
-
server2.registerTool(
|
|
2942
|
-
"workflow-checkpoint",
|
|
2943
|
-
{
|
|
2944
|
-
title: "Workflow Checkpoint",
|
|
2945
|
-
description: "Record the output of a workflow round. Captures the round's data to the Knowledge Base as a structured entry. Use this during Facilitator Mode after completing each round to persist progress \u2014 so if the conversation is interrupted, work is not lost.\n\nAt workflow completion, this tool can also generate the final summary entry.",
|
|
2946
|
-
inputSchema: {
|
|
2947
|
-
workflowId: z7.string().describe("Workflow ID (e.g., 'retro')"),
|
|
2948
|
-
roundId: z7.string().describe("Round ID (e.g., 'what-went-well')"),
|
|
2949
|
-
output: z7.string().describe("The round's output \u2014 synthesized by the facilitator from the conversation"),
|
|
2950
|
-
isFinal: z7.boolean().optional().describe(
|
|
2951
|
-
"If true, this is the final checkpoint and triggers the summary KB entry creation"
|
|
2952
|
-
),
|
|
2953
|
-
summaryName: z7.string().optional().describe(
|
|
2954
|
-
"Name for the final KB entry (required when isFinal=true)"
|
|
2955
|
-
),
|
|
2956
|
-
summaryDescription: z7.string().optional().describe(
|
|
2957
|
-
"Full description/rationale for the final KB entry (required when isFinal=true)"
|
|
2958
|
-
)
|
|
2959
|
-
},
|
|
2960
|
-
annotations: { destructiveHint: false }
|
|
2961
|
-
},
|
|
2962
|
-
async ({ workflowId, roundId, output, isFinal, summaryName, summaryDescription }) => {
|
|
2963
|
-
const wf = getWorkflow(workflowId);
|
|
2964
|
-
if (!wf) {
|
|
2965
|
-
return {
|
|
2966
|
-
content: [{
|
|
2967
|
-
type: "text",
|
|
2968
|
-
text: `Workflow "${workflowId}" not found. Available: ${listWorkflows().map((w) => w.id).join(", ")}.
|
|
2969
|
-
|
|
2970
|
-
This checkpoint was NOT saved. Continue the conversation \u2014 the facilitator has the context.`
|
|
2971
|
-
}]
|
|
2972
|
-
};
|
|
2973
|
-
}
|
|
2974
|
-
const round = wf.rounds.find((r) => r.id === roundId);
|
|
2975
|
-
if (!round) {
|
|
2976
|
-
return {
|
|
2977
|
-
content: [{
|
|
2978
|
-
type: "text",
|
|
2979
|
-
text: `Round "${roundId}" not found in workflow "${workflowId}". Available rounds: ${wf.rounds.map((r) => r.id).join(", ")}.
|
|
2980
|
-
|
|
2981
|
-
This checkpoint was NOT saved. The conversation context is preserved \u2014 continue facilitating.`
|
|
2982
|
-
}]
|
|
2983
|
-
};
|
|
2984
|
-
}
|
|
2985
|
-
const lines = [
|
|
2986
|
-
`## Checkpoint: Round ${round.num} \u2014 ${round.label}`,
|
|
2987
|
-
`Workflow: ${wf.name} (\`${wf.id}\`)`,
|
|
2988
|
-
""
|
|
2989
|
-
];
|
|
2990
|
-
if (isFinal && summaryName && summaryDescription) {
|
|
2991
|
-
try {
|
|
2992
|
-
const entryId = await mcpMutation("kb.createEntry", {
|
|
2993
|
-
collectionSlug: wf.kbOutputCollection,
|
|
2994
|
-
name: summaryName,
|
|
2995
|
-
status: "draft",
|
|
2996
|
-
data: {
|
|
2997
|
-
[wf.kbOutputTemplate.descriptionField]: summaryDescription,
|
|
2998
|
-
workflowType: wf.id,
|
|
2999
|
-
completedRound: roundId,
|
|
3000
|
-
date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
|
|
3001
|
-
},
|
|
3002
|
-
createdBy: `workflow:${wf.id}`
|
|
3003
|
-
});
|
|
3004
|
-
lines.push(
|
|
3005
|
-
`**KB Entry Created**: \`${entryId}\``,
|
|
3006
|
-
`Collection: \`${wf.kbOutputCollection}\``,
|
|
3007
|
-
`Name: ${summaryName}`,
|
|
3008
|
-
"",
|
|
3009
|
-
`The retro is now captured in the Knowledge Base. `,
|
|
3010
|
-
`Use \`suggest-links\` on this entry to connect it to related knowledge.`
|
|
3011
|
-
);
|
|
3012
|
-
} catch (err) {
|
|
3013
|
-
const msg = err instanceof Error ? err.message : String(err);
|
|
3014
|
-
lines.push(
|
|
3015
|
-
`**KB capture failed**: ${msg}`,
|
|
3016
|
-
"",
|
|
3017
|
-
`The retro output is preserved in this conversation. `,
|
|
3018
|
-
`You can manually create the entry later using \`smart-capture\` with:`,
|
|
3019
|
-
`- Collection: \`${wf.kbOutputCollection}\``,
|
|
3020
|
-
`- Name: ${summaryName}`,
|
|
3021
|
-
`- Description: (copy from the conversation summary above)`
|
|
3022
|
-
);
|
|
3023
|
-
}
|
|
3024
|
-
} else {
|
|
3025
|
-
lines.push(
|
|
3026
|
-
`Round ${round.num} output recorded.`,
|
|
3027
|
-
`Output: ${output.substring(0, 200)}${output.length > 200 ? "..." : ""}`
|
|
3028
|
-
);
|
|
3029
|
-
const currentIdx = wf.rounds.findIndex((r) => r.id === roundId);
|
|
3030
|
-
if (currentIdx < wf.rounds.length - 1) {
|
|
3031
|
-
const next = wf.rounds[currentIdx + 1];
|
|
3032
|
-
lines.push(
|
|
3033
|
-
"",
|
|
3034
|
-
`**Next**: Round ${next.num} \u2014 ${next.label}`,
|
|
3035
|
-
`_${next.instruction}_`
|
|
3036
|
-
);
|
|
3037
|
-
} else {
|
|
3038
|
-
lines.push(
|
|
3039
|
-
"",
|
|
3040
|
-
`**All rounds complete.** Call this tool again with \`isFinal: true\` to create the KB entry.`
|
|
3041
|
-
);
|
|
3042
|
-
}
|
|
3043
|
-
}
|
|
3044
|
-
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
3045
|
-
}
|
|
3046
|
-
);
|
|
3047
|
-
}
|
|
3048
|
-
|
|
3049
|
-
// src/tools/gitchain.ts
|
|
3050
|
-
import { z as z8 } from "zod";
|
|
3051
|
-
function linkSummary(links) {
|
|
3052
|
-
return Object.entries(links).map(([id, content]) => {
|
|
3053
|
-
const filled = typeof content === "string" && content.length > 0;
|
|
3054
|
-
const preview = filled ? content.substring(0, 80) + (content.length > 80 ? "..." : "") : "(empty)";
|
|
3055
|
-
return ` - **${id}**: ${preview}`;
|
|
3056
|
-
}).join("\n");
|
|
3057
|
-
}
|
|
3058
|
-
function registerGitChainTools(server2) {
|
|
3059
|
-
server2.registerTool(
|
|
3060
|
-
"chain-create",
|
|
3061
|
-
{
|
|
3062
|
-
title: "Create Chain",
|
|
3063
|
-
description: "Create a new strategic chain in the knowledge base. Chains are versioned knowledge artifacts that follow a chain type definition (e.g. Strategy Coherence: Problem \u2192 Insight \u2192 Choice \u2192 Action \u2192 Outcome). Returns the chain's entry ID for subsequent operations.",
|
|
3064
|
-
inputSchema: {
|
|
3065
|
-
title: z8.string().describe("Title for the chain, e.g. 'Q1 Growth Strategy'"),
|
|
3066
|
-
chainTypeId: z8.string().default("strategy-coherence").describe(
|
|
3067
|
-
"Chain type ID. Use 'strategy-coherence' for 5-link strategy chains (Problem \u2192 Insight \u2192 Choice \u2192 Action \u2192 Outcome) or 'idm-proposal' for IDM governance chains (Tension \u2192 Proposal \u2192 Objections \u2192 Integration \u2192 Decision)"
|
|
3068
|
-
),
|
|
3069
|
-
description: z8.string().optional().describe("Optional description of what this chain is about"),
|
|
3070
|
-
author: z8.string().optional().describe("Who is creating this chain (clerkUserId or person name). Defaults to 'mcp'.")
|
|
3071
|
-
}
|
|
3072
|
-
},
|
|
3073
|
-
async ({ title, chainTypeId, description, author }) => {
|
|
3074
|
-
const result = await mcpMutation(
|
|
3075
|
-
"gitchain.createChain",
|
|
3076
|
-
{ title, chainTypeId, description, author }
|
|
3077
|
-
);
|
|
3078
|
-
return {
|
|
3079
|
-
content: [
|
|
3080
|
-
{
|
|
3081
|
-
type: "text",
|
|
3082
|
-
text: `# Chain Created
|
|
3083
|
-
|
|
3084
|
-
- **Entry ID:** \`${result.entryId}\`
|
|
3085
|
-
- **Title:** ${title}
|
|
3086
|
-
- **Type:** ${chainTypeId}
|
|
3087
|
-
- **Status:** draft
|
|
3088
|
-
|
|
3089
|
-
Use \`chain-edit\` with chainEntryId=\`${result.entryId}\` to start filling in links.`
|
|
3090
|
-
}
|
|
3091
|
-
]
|
|
3092
|
-
};
|
|
3093
|
-
}
|
|
3094
|
-
);
|
|
3095
|
-
server2.registerTool(
|
|
3096
|
-
"chain-get",
|
|
3097
|
-
{
|
|
3098
|
-
title: "Get Chain",
|
|
3099
|
-
description: "Retrieve a chain by its entry ID. Returns the full chain content, coherence scores, link fill status, and version info. Use chain-list first to discover chain entry IDs.",
|
|
3100
|
-
inputSchema: {
|
|
3101
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'")
|
|
3102
|
-
},
|
|
3103
|
-
annotations: { readOnlyHint: true }
|
|
3104
|
-
},
|
|
3105
|
-
async ({ chainEntryId }) => {
|
|
3106
|
-
const chain = await mcpQuery("gitchain.getChain", { chainEntryId });
|
|
3107
|
-
if (!chain) {
|
|
3108
|
-
return {
|
|
3109
|
-
content: [
|
|
3110
|
-
{
|
|
3111
|
-
type: "text",
|
|
3112
|
-
text: `Chain "${chainEntryId}" not found.`
|
|
3113
|
-
}
|
|
3114
|
-
]
|
|
3115
|
-
};
|
|
3116
|
-
}
|
|
3117
|
-
const scoreSection = chain.scores ? `
|
|
3118
|
-
## Coherence: ${chain.coherenceScore}%
|
|
3119
|
-
|
|
3120
|
-
` + chain.scores.sections.map((s) => `- **${s.key}**: ${s.power}/100 (${"\u2605".repeat(Math.min(s.stars ?? 0, 5))}${"\u2606".repeat(Math.max(0, 5 - (s.stars ?? 0)))})`).join("\n") : "";
|
|
3121
|
-
const text = `# ${chain.name}
|
|
3122
|
-
|
|
3123
|
-
- **Entry ID:** \`${chain.entryId}\`
|
|
3124
|
-
- **Type:** ${chain.chainTypeName}
|
|
3125
|
-
- **Status:** ${chain.status}
|
|
3126
|
-
- **Links filled:** ${chain.filledCount}/${chain.totalCount}
|
|
3127
|
-
- **Version:** ${chain.currentVersion}
|
|
3128
|
-
- **Created by:** ${chain.createdBy ?? "unknown"}
|
|
3129
|
-
- **History events:** ${chain.historyCount}
|
|
3130
|
-
` + scoreSection + `
|
|
3131
|
-
|
|
3132
|
-
## Links
|
|
3133
|
-
|
|
3134
|
-
` + linkSummary(chain.links);
|
|
3135
|
-
return { content: [{ type: "text", text }] };
|
|
3136
|
-
}
|
|
3137
|
-
);
|
|
3138
|
-
server2.registerTool(
|
|
3139
|
-
"chain-edit",
|
|
3140
|
-
{
|
|
3141
|
-
title: "Edit Chain Link",
|
|
3142
|
-
description: "Edit a specific link in a chain. Each chain has named links (e.g. for strategy-coherence: problem, insight, choice, action, outcome). The link content is replaced entirely \u2014 pass the full new text.",
|
|
3143
|
-
inputSchema: {
|
|
3144
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'"),
|
|
3145
|
-
linkId: z8.string().describe(
|
|
3146
|
-
"Which link to edit. For strategy-coherence: problem, insight, choice, action, outcome. For idm-proposal: tension, proposal, objections, integration, decision."
|
|
3147
|
-
),
|
|
3148
|
-
content: z8.string().describe("The full new content for this link"),
|
|
3149
|
-
author: z8.string().optional().describe("Who is making this edit. Defaults to 'mcp'.")
|
|
3150
|
-
}
|
|
3151
|
-
},
|
|
3152
|
-
async ({ chainEntryId, linkId, content, author }) => {
|
|
3153
|
-
const result = await mcpMutation("gitchain.editLink", { chainEntryId, linkId, content, author });
|
|
3154
|
-
return {
|
|
3155
|
-
content: [
|
|
3156
|
-
{
|
|
3157
|
-
type: "text",
|
|
3158
|
-
text: `# Link Updated
|
|
3159
|
-
|
|
3160
|
-
- **Chain:** \`${result.entryId}\`
|
|
3161
|
-
- **Link:** ${result.linkId}
|
|
3162
|
-
- **Chain status:** ${result.status}
|
|
3163
|
-
- **Content length:** ${content.length} chars
|
|
3164
|
-
|
|
3165
|
-
Use \`chain-get\` to see the full chain with updated scores.`
|
|
3166
|
-
}
|
|
3167
|
-
]
|
|
3168
|
-
};
|
|
3169
|
-
}
|
|
3170
|
-
);
|
|
3171
|
-
server2.registerTool(
|
|
3172
|
-
"chain-list",
|
|
3173
|
-
{
|
|
3174
|
-
title: "List Chains",
|
|
3175
|
-
description: "List all chains in the workspace, optionally filtered by chain type or status. Returns entry IDs, titles, link fill progress, and coherence scores.",
|
|
3176
|
-
inputSchema: {
|
|
3177
|
-
chainTypeId: z8.string().optional().describe("Filter by chain type: 'strategy-coherence' or 'idm-proposal'"),
|
|
3178
|
-
status: z8.string().optional().describe("Filter by status: 'draft' or 'active'")
|
|
3179
|
-
},
|
|
3180
|
-
annotations: { readOnlyHint: true }
|
|
3181
|
-
},
|
|
3182
|
-
async ({ chainTypeId, status }) => {
|
|
3183
|
-
const chains = await mcpQuery("gitchain.listChains", {
|
|
3184
|
-
chainTypeId,
|
|
3185
|
-
status
|
|
3186
|
-
});
|
|
3187
|
-
if (chains.length === 0) {
|
|
3188
|
-
return {
|
|
3189
|
-
content: [
|
|
3190
|
-
{
|
|
3191
|
-
type: "text",
|
|
3192
|
-
text: "No chains found. Use `chain-create` to create one."
|
|
3193
|
-
}
|
|
3194
|
-
]
|
|
3195
|
-
};
|
|
3196
|
-
}
|
|
3197
|
-
const formatted = chains.map(
|
|
3198
|
-
(c) => `- **\`${c.entryId}\`** ${c.name} \u2014 ${c.chainTypeId} \xB7 ${c.filledCount}/${c.totalCount} links \xB7 coherence: ${c.coherenceScore}% \xB7 status: ${c.status}`
|
|
3199
|
-
).join("\n");
|
|
3200
|
-
return {
|
|
3201
|
-
content: [
|
|
3202
|
-
{
|
|
3203
|
-
type: "text",
|
|
3204
|
-
text: `# Chains (${chains.length})
|
|
3205
|
-
|
|
3206
|
-
${formatted}`
|
|
3207
|
-
}
|
|
3208
|
-
]
|
|
3209
|
-
};
|
|
3210
|
-
}
|
|
3211
|
-
);
|
|
3212
|
-
server2.registerTool(
|
|
3213
|
-
"chain-history",
|
|
3214
|
-
{
|
|
3215
|
-
title: "Chain History",
|
|
3216
|
-
description: "View the edit history of a chain \u2014 all creation, update, and version events. Shows who changed what and when.",
|
|
3217
|
-
inputSchema: {
|
|
3218
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'")
|
|
3219
|
-
},
|
|
3220
|
-
annotations: { readOnlyHint: true }
|
|
3221
|
-
},
|
|
3222
|
-
async ({ chainEntryId }) => {
|
|
3223
|
-
const history = await mcpQuery("gitchain.getHistory", {
|
|
3224
|
-
chainEntryId
|
|
3225
|
-
});
|
|
3226
|
-
if (history.length === 0) {
|
|
3227
|
-
return {
|
|
3228
|
-
content: [
|
|
3229
|
-
{
|
|
3230
|
-
type: "text",
|
|
3231
|
-
text: `No history found for chain "${chainEntryId}".`
|
|
3232
|
-
}
|
|
3233
|
-
]
|
|
3234
|
-
};
|
|
3235
|
-
}
|
|
3236
|
-
const formatted = history.sort((a, b) => b.timestamp - a.timestamp).map((h) => {
|
|
3237
|
-
const date = new Date(h.timestamp).toISOString().replace("T", " ").substring(0, 19);
|
|
3238
|
-
return `- **${date}** [${h.event}] by ${h.changedBy ?? "unknown"} \u2014 ${h.note ?? ""}`;
|
|
3239
|
-
}).join("\n");
|
|
3240
|
-
return {
|
|
3241
|
-
content: [
|
|
3242
|
-
{
|
|
3243
|
-
type: "text",
|
|
3244
|
-
text: `# History for ${chainEntryId} (${history.length} events)
|
|
3245
|
-
|
|
3246
|
-
${formatted}`
|
|
3247
|
-
}
|
|
3248
|
-
]
|
|
3249
|
-
};
|
|
3250
|
-
}
|
|
3251
|
-
);
|
|
3252
|
-
server2.registerTool(
|
|
3253
|
-
"chain-commit",
|
|
3254
|
-
{
|
|
3255
|
-
title: "Commit Chain",
|
|
3256
|
-
description: "Create a version snapshot (commit) of the current chain state. Records all link content, computes coherence score, and tracks which links changed. Commit messages should follow: type(link): description. Types: edit, refine, rewrite, integrate, revert.",
|
|
3257
|
-
inputSchema: {
|
|
3258
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'"),
|
|
3259
|
-
commitMessage: z8.string().describe(
|
|
3260
|
-
"Commit message following convention: type(link): description. Example: 'edit(outcome): Add Q1 revenue target'"
|
|
3261
|
-
),
|
|
3262
|
-
author: z8.string().optional().describe("Who is committing. Defaults to 'mcp'.")
|
|
3263
|
-
}
|
|
3264
|
-
},
|
|
3265
|
-
async ({ chainEntryId, commitMessage, author }) => {
|
|
3266
|
-
const result = await mcpMutation("gitchain.commitChain", { chainEntryId, commitMessage, author });
|
|
3267
|
-
const warning = result.commitLintWarning ? `
|
|
3268
|
-
|
|
3269
|
-
> **Lint warning:** ${result.commitLintWarning}` : "";
|
|
3270
|
-
return {
|
|
3271
|
-
content: [
|
|
3272
|
-
{
|
|
3273
|
-
type: "text",
|
|
3274
|
-
text: `# Committed v${result.version}
|
|
3275
|
-
|
|
3276
|
-
- **Chain:** \`${result.entryId}\`
|
|
3277
|
-
- **Version:** ${result.version}
|
|
3278
|
-
- **Message:** ${commitMessage}
|
|
3279
|
-
- **Coherence:** ${result.coherenceScore}%
|
|
3280
|
-
- **Links modified:** ${result.linksModified.length > 0 ? result.linksModified.join(", ") : "none"}
|
|
3281
|
-
` + warning
|
|
3282
|
-
}
|
|
3283
|
-
]
|
|
3284
|
-
};
|
|
3285
|
-
}
|
|
3286
|
-
);
|
|
3287
|
-
server2.registerTool(
|
|
3288
|
-
"chain-commits",
|
|
3289
|
-
{
|
|
3290
|
-
title: "List Chain Commits",
|
|
3291
|
-
description: "List all version snapshots (commits) for a chain, newest first. Shows version number, commit message, author, which links were modified, and status.",
|
|
3292
|
-
inputSchema: {
|
|
3293
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'")
|
|
3294
|
-
},
|
|
3295
|
-
annotations: { readOnlyHint: true }
|
|
3296
|
-
},
|
|
3297
|
-
async ({ chainEntryId }) => {
|
|
3298
|
-
const commits = await mcpQuery("gitchain.listCommits", {
|
|
3299
|
-
chainEntryId
|
|
3300
|
-
});
|
|
3301
|
-
if (commits.length === 0) {
|
|
3302
|
-
return {
|
|
3303
|
-
content: [
|
|
3304
|
-
{
|
|
3305
|
-
type: "text",
|
|
3306
|
-
text: `No commits found for chain "${chainEntryId}". Use \`chain-commit\` to create the first snapshot.`
|
|
3307
|
-
}
|
|
3308
|
-
]
|
|
3309
|
-
};
|
|
3310
|
-
}
|
|
3311
|
-
const formatted = commits.map((c) => {
|
|
3312
|
-
const date = new Date(c.createdAt).toISOString().replace("T", " ").substring(0, 19);
|
|
3313
|
-
const msg = c.commitMessage ?? c.changeNote ?? "(no message)";
|
|
3314
|
-
const links = c.linksModified && c.linksModified.length > 0 ? ` [${c.linksModified.join(", ")}]` : "";
|
|
3315
|
-
return `- **v${c.version}** ${date} by ${c.author} \u2014 ${msg}${links} (${c.versionStatus})`;
|
|
3316
|
-
}).join("\n");
|
|
3317
|
-
return {
|
|
3318
|
-
content: [
|
|
3319
|
-
{
|
|
3320
|
-
type: "text",
|
|
3321
|
-
text: `# Commits for ${chainEntryId} (${commits.length})
|
|
3322
|
-
|
|
3323
|
-
${formatted}`
|
|
3324
|
-
}
|
|
3325
|
-
]
|
|
3326
|
-
};
|
|
3327
|
-
}
|
|
3328
|
-
);
|
|
3329
|
-
server2.registerTool(
|
|
3330
|
-
"chain-diff",
|
|
3331
|
-
{
|
|
3332
|
-
title: "Diff Chain Versions",
|
|
3333
|
-
description: "Compare two versions of a chain. Shows which links changed, word-level diffs for modified links, and the coherence score delta. Use chain-commits first to see available version numbers.",
|
|
3334
|
-
inputSchema: {
|
|
3335
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'"),
|
|
3336
|
-
versionA: z8.number().describe("The earlier version number"),
|
|
3337
|
-
versionB: z8.number().describe("The later version number")
|
|
3338
|
-
},
|
|
3339
|
-
annotations: { readOnlyHint: true }
|
|
3340
|
-
},
|
|
3341
|
-
async ({ chainEntryId, versionA, versionB }) => {
|
|
3342
|
-
const diff = await mcpMutation("gitchain.diffVersions", {
|
|
3343
|
-
chainEntryId,
|
|
3344
|
-
versionA,
|
|
3345
|
-
versionB
|
|
3346
|
-
});
|
|
3347
|
-
let text = `# Diff: v${versionA} \u2192 v${versionB}
|
|
3348
|
-
|
|
3349
|
-
- **Chain:** \`${diff.chainEntryId}\`
|
|
3350
|
-
- **Coherence:** ${diff.coherenceBefore}% \u2192 ${diff.coherenceAfter}% (${diff.coherenceDelta >= 0 ? "+" : ""}${diff.coherenceDelta})
|
|
3351
|
-
- **Links changed:** ${diff.linksChanged.length > 0 ? diff.linksChanged.join(", ") : "none"}
|
|
3352
|
-
`;
|
|
3353
|
-
for (const ld of diff.linkDiffs) {
|
|
3354
|
-
if (ld.status === "unchanged") continue;
|
|
3355
|
-
text += `
|
|
3356
|
-
## ${ld.linkId} (${ld.status})
|
|
3357
|
-
|
|
3358
|
-
`;
|
|
3359
|
-
const wordDiff = diff.wordDiffs[ld.linkId];
|
|
3360
|
-
if (wordDiff && wordDiff.length > 0) {
|
|
3361
|
-
for (const w of wordDiff) {
|
|
3362
|
-
if (w.type === "delete") {
|
|
3363
|
-
text += `~~${w.value.substring(0, 200)}~~`;
|
|
3364
|
-
} else if (w.type === "insert") {
|
|
3365
|
-
text += `**${w.value.substring(0, 200)}**`;
|
|
3366
|
-
} else {
|
|
3367
|
-
text += w.value.substring(0, 200);
|
|
3368
|
-
}
|
|
3369
|
-
}
|
|
3370
|
-
text += "\n";
|
|
3371
|
-
}
|
|
3372
|
-
}
|
|
3373
|
-
return { content: [{ type: "text", text }] };
|
|
3374
|
-
}
|
|
3375
|
-
);
|
|
3376
|
-
server2.registerTool(
|
|
3377
|
-
"chain-gate",
|
|
3378
|
-
{
|
|
3379
|
-
title: "Chain Coherence Gate",
|
|
3380
|
-
description: "Run the coherence gate on a chain. Checks: coherence score >= 70%, all links filled, commit message follows convention. Returns pass/fail with detailed check results. This is the same gate that blocks publishing.",
|
|
3381
|
-
inputSchema: {
|
|
3382
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'"),
|
|
3383
|
-
commitMessage: z8.string().optional().describe("Optional commit message to lint")
|
|
3384
|
-
},
|
|
3385
|
-
annotations: { readOnlyHint: true }
|
|
3386
|
-
},
|
|
3387
|
-
async ({ chainEntryId, commitMessage }) => {
|
|
3388
|
-
const gate = await mcpQuery("gitchain.runGate", {
|
|
3389
|
-
chainEntryId,
|
|
3390
|
-
commitMessage
|
|
3391
|
-
});
|
|
3392
|
-
const checkLines = gate.checks.map(
|
|
3393
|
-
(c) => `- ${c.pass ? "PASS" : "FAIL"} **${c.name}**: ${c.detail}`
|
|
3394
|
-
).join("\n");
|
|
3395
|
-
const icon = gate.pass ? "PASS" : "BLOCKED";
|
|
3396
|
-
return {
|
|
3397
|
-
content: [
|
|
3398
|
-
{
|
|
3399
|
-
type: "text",
|
|
3400
|
-
text: `# Gate: ${icon}
|
|
3401
|
-
|
|
3402
|
-
- **Score:** ${gate.score}%
|
|
3403
|
-
- **Threshold:** ${gate.threshold}%
|
|
3404
|
-
|
|
3405
|
-
## Checks
|
|
3406
|
-
|
|
3407
|
-
${checkLines}`
|
|
3408
|
-
}
|
|
3409
|
-
]
|
|
3410
|
-
};
|
|
3411
|
-
}
|
|
3412
|
-
);
|
|
3413
|
-
server2.registerTool(
|
|
3414
|
-
"chain-branch",
|
|
3415
|
-
{
|
|
3416
|
-
title: "Create or List Chain Branches",
|
|
3417
|
-
description: "Create a new branch for isolated editing, or list all branches on a chain. Branches fork from the current published version of main. Use chain-merge to merge a branch back.",
|
|
3418
|
-
inputSchema: {
|
|
3419
|
-
chainEntryId: z8.string().describe("The chain's entry ID, e.g. 'CH-A1B2C3'"),
|
|
3420
|
-
action: z8.enum(["create", "list"]).describe("'create' to make a new branch, 'list' to see all branches"),
|
|
3421
|
-
name: z8.string().optional().describe("Branch name for 'create' action. Auto-generated if not provided."),
|
|
3422
|
-
author: z8.string().optional().describe("Who is creating the branch. Defaults to 'mcp'.")
|
|
3423
|
-
}
|
|
3424
|
-
},
|
|
3425
|
-
async ({ chainEntryId, action, name, author }) => {
|
|
3426
|
-
if (action === "create") {
|
|
3427
|
-
const result = await mcpMutation("gitchain.createBranch", { chainEntryId, name, author });
|
|
3428
|
-
return {
|
|
3429
|
-
content: [
|
|
3430
|
-
{
|
|
3431
|
-
type: "text",
|
|
3432
|
-
text: `# Branch Created
|
|
3433
|
-
|
|
3434
|
-
- **Name:** ${result.name}
|
|
3435
|
-
- **Based on:** v${result.baseVersion}
|
|
3436
|
-
- **Chain:** \`${chainEntryId}\`
|
|
3437
|
-
|
|
3438
|
-
Edit links and commit on this branch, then use \`chain-merge\` to land changes.`
|
|
3439
|
-
}
|
|
3440
|
-
]
|
|
3441
|
-
};
|
|
3442
|
-
}
|
|
3443
|
-
const branches = await mcpMutation("gitchain.listBranches", {
|
|
3444
|
-
chainEntryId
|
|
3445
|
-
});
|
|
3446
|
-
if (branches.length === 0) {
|
|
3447
|
-
return {
|
|
3448
|
-
content: [
|
|
3449
|
-
{
|
|
3450
|
-
type: "text",
|
|
3451
|
-
text: `No branches found for chain "${chainEntryId}".`
|
|
3452
|
-
}
|
|
3453
|
-
]
|
|
3454
|
-
};
|
|
3455
|
-
}
|
|
3456
|
-
const formatted = branches.map(
|
|
3457
|
-
(b) => `- **${b.name}** (${b.status}) \u2014 based on v${b.baseVersion}, by ${b.createdBy}`
|
|
3458
|
-
).join("\n");
|
|
3459
|
-
return {
|
|
3460
|
-
content: [
|
|
3461
|
-
{
|
|
3462
|
-
type: "text",
|
|
3463
|
-
text: `# Branches for ${chainEntryId} (${branches.length})
|
|
3464
|
-
|
|
3465
|
-
${formatted}`
|
|
3466
|
-
}
|
|
3467
|
-
]
|
|
3468
|
-
};
|
|
3469
|
-
}
|
|
3470
|
-
);
|
|
3471
|
-
server2.registerTool(
|
|
3472
|
-
"chain-conflicts",
|
|
3473
|
-
{
|
|
3474
|
-
title: "Check Branch Conflicts",
|
|
3475
|
-
description: "Check if a branch has conflicts with other active branches. Conflicts occur when two branches modify the same chain link. Always check before merging.",
|
|
3476
|
-
inputSchema: {
|
|
3477
|
-
chainEntryId: z8.string().describe("The chain's entry ID"),
|
|
3478
|
-
branchName: z8.string().describe("The branch name to check for conflicts")
|
|
3479
|
-
},
|
|
3480
|
-
annotations: { readOnlyHint: true }
|
|
3481
|
-
},
|
|
3482
|
-
async ({ chainEntryId, branchName }) => {
|
|
3483
|
-
const result = await mcpMutation("gitchain.checkConflicts", {
|
|
3484
|
-
chainEntryId,
|
|
3485
|
-
branchName
|
|
3486
|
-
});
|
|
3487
|
-
if (!result.hasConflicts) {
|
|
3488
|
-
return {
|
|
3489
|
-
content: [
|
|
3490
|
-
{
|
|
3491
|
-
type: "text",
|
|
3492
|
-
text: `# No Conflicts
|
|
3493
|
-
|
|
3494
|
-
Branch "${branchName}" on \`${chainEntryId}\` has no conflicts with other active branches. Safe to merge.`
|
|
3495
|
-
}
|
|
3496
|
-
]
|
|
3497
|
-
};
|
|
3498
|
-
}
|
|
3499
|
-
const conflictLines = result.conflicts.map(
|
|
3500
|
-
(c) => `- **${c.linkId}** \u2014 modified by: ${c.branches.map((b) => `${b.branchName} (${b.author})`).join(", ")}`
|
|
3501
|
-
).join("\n");
|
|
3502
|
-
return {
|
|
3503
|
-
content: [
|
|
3504
|
-
{
|
|
3505
|
-
type: "text",
|
|
3506
|
-
text: `# Conflicts Detected
|
|
3507
|
-
|
|
3508
|
-
Branch "${branchName}" conflicts with other branches on these links:
|
|
3509
|
-
|
|
3510
|
-
` + conflictLines + `
|
|
3511
|
-
|
|
3512
|
-
Resolve conflicts before merging. One branch must update its link content to avoid overwriting.`
|
|
3513
|
-
}
|
|
3514
|
-
]
|
|
3515
|
-
};
|
|
3516
|
-
}
|
|
3517
|
-
);
|
|
3518
|
-
server2.registerTool(
|
|
3519
|
-
"chain-merge",
|
|
3520
|
-
{
|
|
3521
|
-
title: "Merge Branch",
|
|
3522
|
-
description: "Merge a branch back into main. Runs the coherence gate before merging. The branch is closed after merge. Check for conflicts with chain-conflicts first.",
|
|
3523
|
-
inputSchema: {
|
|
3524
|
-
chainEntryId: z8.string().describe("The chain's entry ID"),
|
|
3525
|
-
branchName: z8.string().describe("The branch to merge"),
|
|
3526
|
-
strategy: z8.enum(["merge_commit", "squash"]).optional().describe("Merge strategy: 'merge_commit' (default) preserves history, 'squash' collapses into one version"),
|
|
3527
|
-
author: z8.string().optional().describe("Who is merging. Defaults to 'mcp'.")
|
|
3528
|
-
}
|
|
3529
|
-
},
|
|
3530
|
-
async ({ chainEntryId, branchName, strategy, author }) => {
|
|
3531
|
-
const result = await mcpMutation("gitchain.mergeBranch", {
|
|
3532
|
-
chainEntryId,
|
|
3533
|
-
branchName,
|
|
3534
|
-
strategy,
|
|
3535
|
-
author
|
|
3536
|
-
});
|
|
3537
|
-
return {
|
|
3538
|
-
content: [
|
|
3539
|
-
{
|
|
3540
|
-
type: "text",
|
|
3541
|
-
text: `# Branch Merged
|
|
3542
|
-
|
|
3543
|
-
- **Chain:** \`${result.entryId}\`
|
|
3544
|
-
- **Branch:** ${result.branchName} (now closed)
|
|
3545
|
-
- **Version:** v${result.version}
|
|
3546
|
-
- **Strategy:** ${result.strategy}
|
|
3547
|
-
|
|
3548
|
-
Main is now at v${result.version}. The branch has been closed.`
|
|
3549
|
-
}
|
|
3550
|
-
]
|
|
3551
|
-
};
|
|
3552
|
-
}
|
|
3553
|
-
);
|
|
3554
|
-
server2.registerTool(
|
|
3555
|
-
"chain-comment",
|
|
3556
|
-
{
|
|
3557
|
-
title: "Comment on Chain Version",
|
|
3558
|
-
description: "Add a threaded comment on a specific chain version, optionally targeting a specific link. Comments support threading via parentId. Use chain-comments to see existing comments.",
|
|
3559
|
-
inputSchema: {
|
|
3560
|
-
chainEntryId: z8.string().describe("The chain's entry ID"),
|
|
3561
|
-
action: z8.enum(["add", "resolve", "list"]).describe("'add' a comment, 'resolve' a comment, or 'list' all comments"),
|
|
3562
|
-
versionNumber: z8.number().optional().describe("Version number to comment on (required for 'add')"),
|
|
3563
|
-
linkId: z8.string().optional().describe("Which link this comment targets (optional)"),
|
|
3564
|
-
body: z8.string().optional().describe("Comment text (required for 'add')"),
|
|
3565
|
-
commentId: z8.string().optional().describe("Comment ID to resolve (required for 'resolve')"),
|
|
3566
|
-
author: z8.string().optional().describe("Who is commenting. Defaults to 'mcp'.")
|
|
3567
|
-
}
|
|
3568
|
-
},
|
|
3569
|
-
async ({ chainEntryId, action, versionNumber, linkId, body, commentId, author }) => {
|
|
3570
|
-
if (action === "add") {
|
|
3571
|
-
if (!versionNumber) throw new Error("versionNumber is required for 'add'");
|
|
3572
|
-
if (!body) throw new Error("body is required for 'add'");
|
|
3573
|
-
const result = await mcpMutation("gitchain.addComment", {
|
|
3574
|
-
chainEntryId,
|
|
3575
|
-
versionNumber,
|
|
3576
|
-
linkId,
|
|
3577
|
-
body,
|
|
3578
|
-
author
|
|
3579
|
-
});
|
|
3580
|
-
return {
|
|
3581
|
-
content: [
|
|
3582
|
-
{
|
|
3583
|
-
type: "text",
|
|
3584
|
-
text: `# Comment Added
|
|
3585
|
-
|
|
3586
|
-
- **Chain:** \`${result.chainEntryId}\`
|
|
3587
|
-
- **Version:** v${result.versionNumber}
|
|
3588
|
-
` + (result.linkId ? `- **Link:** ${result.linkId}
|
|
3589
|
-
` : "") + `- **Body:** ${body?.substring(0, 200)}`
|
|
3590
|
-
}
|
|
3591
|
-
]
|
|
3592
|
-
};
|
|
3593
|
-
}
|
|
3594
|
-
if (action === "resolve") {
|
|
3595
|
-
if (!commentId) throw new Error("commentId is required for 'resolve'");
|
|
3596
|
-
await mcpMutation("gitchain.resolveComment", { commentId });
|
|
3597
|
-
return {
|
|
3598
|
-
content: [
|
|
3599
|
-
{
|
|
3600
|
-
type: "text",
|
|
3601
|
-
text: `Comment resolved.`
|
|
3602
|
-
}
|
|
3603
|
-
]
|
|
3604
|
-
};
|
|
3605
|
-
}
|
|
3606
|
-
const comments = await mcpMutation("gitchain.listComments", {
|
|
3607
|
-
chainEntryId,
|
|
3608
|
-
versionNumber
|
|
3609
|
-
});
|
|
3610
|
-
if (comments.length === 0) {
|
|
3611
|
-
return {
|
|
3612
|
-
content: [
|
|
3613
|
-
{
|
|
3614
|
-
type: "text",
|
|
3615
|
-
text: `No comments found for chain "${chainEntryId}"${versionNumber ? ` v${versionNumber}` : ""}.`
|
|
3616
|
-
}
|
|
3617
|
-
]
|
|
3618
|
-
};
|
|
3619
|
-
}
|
|
3620
|
-
const formatted = comments.map((c) => {
|
|
3621
|
-
const date = new Date(c.createdAt).toISOString().replace("T", " ").substring(0, 19);
|
|
3622
|
-
const resolved = c.resolved ? " (RESOLVED)" : "";
|
|
3623
|
-
const link = c.linkId ? ` [${c.linkId}]` : "";
|
|
3624
|
-
return `- **v${c.version}${link}** ${date} by ${c.author}${resolved}: ${c.body.substring(0, 150)}`;
|
|
3625
|
-
}).join("\n");
|
|
3626
|
-
const unresolvedCount = comments.filter((c) => !c.resolved).length;
|
|
3627
|
-
return {
|
|
3628
|
-
content: [
|
|
3629
|
-
{
|
|
3630
|
-
type: "text",
|
|
3631
|
-
text: `# Comments for ${chainEntryId} (${comments.length}, ${unresolvedCount} unresolved)
|
|
3632
|
-
|
|
3633
|
-
${formatted}`
|
|
3634
|
-
}
|
|
3635
|
-
]
|
|
3636
|
-
};
|
|
3637
|
-
}
|
|
3638
|
-
);
|
|
3639
|
-
server2.registerTool(
|
|
3640
|
-
"chain-revert",
|
|
3641
|
-
{
|
|
3642
|
-
title: "Revert Chain",
|
|
3643
|
-
description: "Safely revert a chain to a previous version. Creates a NEW version that restores the content of the target version \u2014 history is preserved, nothing is destroyed. Use chain-commits to see available versions.",
|
|
3644
|
-
inputSchema: {
|
|
3645
|
-
chainEntryId: z8.string().describe("The chain's entry ID"),
|
|
3646
|
-
toVersion: z8.number().describe("The version number to revert to"),
|
|
3647
|
-
author: z8.string().optional().describe("Who is reverting. Defaults to 'mcp'.")
|
|
3648
|
-
}
|
|
3649
|
-
},
|
|
3650
|
-
async ({ chainEntryId, toVersion, author }) => {
|
|
3651
|
-
const result = await mcpMutation("gitchain.revertChain", { chainEntryId, toVersion, author });
|
|
3652
|
-
return {
|
|
3653
|
-
content: [
|
|
3654
|
-
{
|
|
3655
|
-
type: "text",
|
|
3656
|
-
text: `# Reverted
|
|
3657
|
-
|
|
3658
|
-
- **Chain:** \`${result.entryId}\`
|
|
3659
|
-
- **Reverted to:** v${result.revertedTo}
|
|
3660
|
-
- **New version:** v${result.newVersion}
|
|
3661
|
-
- **Links affected:** ${result.linksModified.length > 0 ? result.linksModified.join(", ") : "none"}
|
|
3662
|
-
|
|
3663
|
-
History is preserved \u2014 this created a new version, not a destructive reset.`
|
|
3664
|
-
}
|
|
3665
|
-
]
|
|
3666
|
-
};
|
|
3667
|
-
}
|
|
3668
|
-
);
|
|
3669
|
-
}
|
|
3670
|
-
|
|
3671
|
-
// src/resources/index.ts
|
|
3672
|
-
import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
3673
|
-
function formatEntryMarkdown(entry) {
|
|
3674
|
-
const id = entry.entryId ? `${entry.entryId}: ` : "";
|
|
3675
|
-
const lines = [`## ${id}${entry.name} [${entry.status}]`];
|
|
3676
|
-
if (entry.data && typeof entry.data === "object") {
|
|
3677
|
-
for (const [key, val] of Object.entries(entry.data)) {
|
|
3678
|
-
if (val && key !== "rawData") {
|
|
3679
|
-
lines.push(`**${key}**: ${typeof val === "string" ? val : JSON.stringify(val)}`);
|
|
3680
|
-
}
|
|
3681
|
-
}
|
|
3682
|
-
}
|
|
3683
|
-
return lines.join("\n");
|
|
3684
|
-
}
|
|
3685
|
-
function buildOrientationMarkdown(collections, trackingEvents, standards, businessRules) {
|
|
3686
|
-
const sections = ["# Product Brain \u2014 Orientation"];
|
|
3687
|
-
sections.push(
|
|
3688
|
-
"## Architecture\n```\nCursor (stdio) \u2192 MCP Server (mcp-server/src/index.ts)\n \u2192 POST /api/mcp with Bearer token\n \u2192 Convex HTTP Action (convex/http.ts)\n \u2192 internalQuery / internalMutation (convex/mcpKnowledge.ts)\n \u2192 Convex DB (workspace-scoped)\n```\nSecurity: API key auth on every request, workspace-scoped data, internal functions blocked from external clients.\nKey files: `packages/mcp-server/src/client.ts` (HTTP client + audit), `convex/schema.ts` (schema)."
|
|
3689
|
-
);
|
|
3690
|
-
if (collections) {
|
|
3691
|
-
const collList = collections.map((c) => {
|
|
3692
|
-
const prefix = c.icon ? `${c.icon} ` : "";
|
|
3693
|
-
return `- ${prefix}**${c.name}** (\`${c.slug}\`) \u2014 ${c.description || "no description"}`;
|
|
3694
|
-
}).join("\n");
|
|
3695
|
-
sections.push(
|
|
3696
|
-
`## Data Model (${collections.length} collections)
|
|
3697
|
-
Unified entries model: collections define field schemas, entries hold data in a flexible \`data\` field.
|
|
3698
|
-
Tags for filtering (e.g. \`severity:high\`), relations via \`entryRelations\`, history via \`entryHistory\`, labels via \`labels\` + \`entryLabels\`.
|
|
3699
|
-
|
|
3700
|
-
` + collList + "\n\nUse `list-collections` for field schemas, `get-entry` for full records."
|
|
3701
|
-
);
|
|
3702
|
-
} else {
|
|
3703
|
-
sections.push(
|
|
3704
|
-
"## Data Model\nCould not load collections \u2014 use `list-collections` to browse manually."
|
|
3705
|
-
);
|
|
3706
|
-
}
|
|
3707
|
-
const rulesCount = businessRules ? `${businessRules.length} entries` : "not loaded \u2014 collection may not exist yet";
|
|
3708
|
-
sections.push(
|
|
3709
|
-
`## Business Rules
|
|
3710
|
-
Collection: \`business-rules\` (${rulesCount}).
|
|
3711
|
-
Find rules: \`kb-search\` for text search, \`list-entries collection=business-rules\` to browse.
|
|
3712
|
-
Check compliance: use the \`review-against-rules\` prompt (pass a domain).
|
|
3713
|
-
Draft a new rule: use the \`draft-rule-from-context\` prompt.`
|
|
3714
|
-
);
|
|
3715
|
-
const eventsCount = trackingEvents ? `${trackingEvents.length} events` : "not loaded \u2014 collection may not exist yet";
|
|
3716
|
-
const conventionNote = standards ? "Naming convention: `object_action` in snake_case with past-tense verbs (from standards collection)." : "Naming convention: `object_action` in snake_case with past-tense verbs.";
|
|
3717
|
-
sections.push(
|
|
3718
|
-
`## Analytics & Tracking
|
|
3719
|
-
Event catalog: \`tracking-events\` collection (${eventsCount}).
|
|
3720
|
-
${conventionNote}
|
|
3721
|
-
Implementation: \`src/lib/analytics.ts\`. Workspace-scoped events MUST use \`withWorkspaceGroup()\`.
|
|
3722
|
-
Browse: \`list-entries collection=tracking-events\`. Full setup: \`docs/posthog-setup.md\`.`
|
|
3723
|
-
);
|
|
3724
|
-
sections.push(
|
|
3725
|
-
"## Knowledge Graph\nEntries are connected via typed relations (`entryRelations` table). Relations are bidirectional and collection-agnostic \u2014 any entry can link to any other entry.\n\n**Recommended relation types** (extensible \u2014 any string accepted):\n- `governs` \u2014 a rule constrains behavior of a feature\n- `defines_term_for` \u2014 a glossary term is canonical vocabulary for a feature/area\n- `belongs_to` \u2014 a feature belongs to a product area or parent concept\n- `informs` \u2014 a decision or insight informs a feature\n- `surfaces_tension_in` \u2014 a tension exists within a feature area\n- `related_to`, `depends_on`, `replaces`, `conflicts_with`, `references`, `confused_with`\n\nEach relation type is defined as a glossary entry (prefix `GT-REL-*`) to prevent terminology drift.\n\n**Tools:**\n- `gather-context` \u2014 get the full context around any entry (multi-hop graph traversal)\n- `suggest-links` \u2014 discover potential connections for an entry\n- `relate-entries` \u2014 create a typed link between two entries\n- `find-related` \u2014 list direct relations for an entry\n\n**Convention:** When creating or updating entries in governed collections, always use `suggest-links` to discover and create relevant relations."
|
|
3726
|
-
);
|
|
3727
|
-
sections.push(
|
|
3728
|
-
"## Creating Knowledge\nUse `smart-capture` as the primary tool for creating new entries. It handles the full workflow in one call:\n1. Creates the entry with collection-aware defaults (auto-fills dates, infers domains, sets priority)\n2. Auto-links related entries from across the knowledge base (up to 5 confident matches)\n3. Returns a quality scorecard (X/10) with actionable improvement suggestions\n\n**Smart profiles** exist for: `tensions`, `business-rules`, `glossary`, `decisions`.\nAll other collections use sensible defaults.\n\nExample: `smart-capture collection='tensions' name='...' description='...'`\n\nUse `quality-check` to score existing entries retroactively.\nUse `create-entry` only when you need full control over every field.\nUse `quick-capture` for minimal ceremony without auto-linking."
|
|
3729
|
-
);
|
|
3730
|
-
sections.push(
|
|
3731
|
-
"## Where to Go Next\n- **Create entry** \u2192 `smart-capture` tool (auto-links + quality score in one call)\n- **Full context** \u2192 `gather-context` tool (start here when working on a feature)\n- **Discover links** \u2192 `suggest-links` tool\n- **Quality audit** \u2192 `quality-check` tool\n- **Terminology** \u2192 `name-check` prompt or `productbrain://terminology` resource\n- **Schema details** \u2192 `productbrain://collections` resource or `list-collections` tool\n- **Labels** \u2192 `productbrain://labels` resource or `list-labels` tool\n- **Any collection** \u2192 `productbrain://{slug}/entries` resource\n- **Log a decision** \u2192 `draft-decision-record` prompt\n- **Architecture map** \u2192 `show-architecture` tool (layered system visualization)\n- **Explore a layer** \u2192 `explore-layer` tool (drill into Auth, Core, Features, etc.)\n- **Health check** \u2192 `health` tool\n- **Debug MCP calls** \u2192 `mcp-audit` tool"
|
|
3732
|
-
);
|
|
3733
|
-
return sections.join("\n\n---\n\n");
|
|
3734
|
-
}
|
|
3735
|
-
function registerResources(server2) {
|
|
3736
|
-
server2.resource(
|
|
3737
|
-
"kb-orientation",
|
|
3738
|
-
"productbrain://orientation",
|
|
3739
|
-
async (uri) => {
|
|
3740
|
-
const [collectionsResult, eventsResult, standardsResult, rulesResult] = await Promise.allSettled([
|
|
3741
|
-
mcpQuery("kb.listCollections"),
|
|
3742
|
-
mcpQuery("kb.listEntries", { collectionSlug: "tracking-events" }),
|
|
3743
|
-
mcpQuery("kb.listEntries", { collectionSlug: "standards" }),
|
|
3744
|
-
mcpQuery("kb.listEntries", { collectionSlug: "business-rules" })
|
|
3745
|
-
]);
|
|
3746
|
-
const collections = collectionsResult.status === "fulfilled" ? collectionsResult.value : null;
|
|
3747
|
-
const trackingEvents = eventsResult.status === "fulfilled" ? eventsResult.value : null;
|
|
3748
|
-
const standards = standardsResult.status === "fulfilled" ? standardsResult.value : null;
|
|
3749
|
-
const businessRules = rulesResult.status === "fulfilled" ? rulesResult.value : null;
|
|
3750
|
-
return {
|
|
3751
|
-
contents: [{
|
|
3752
|
-
uri: uri.href,
|
|
3753
|
-
text: buildOrientationMarkdown(collections, trackingEvents, standards, businessRules),
|
|
3754
|
-
mimeType: "text/markdown"
|
|
3755
|
-
}]
|
|
3756
|
-
};
|
|
3757
|
-
}
|
|
3758
|
-
);
|
|
3759
|
-
server2.resource(
|
|
3760
|
-
"kb-terminology",
|
|
3761
|
-
"productbrain://terminology",
|
|
3762
|
-
async (uri) => {
|
|
3763
|
-
const [glossaryResult, standardsResult] = await Promise.allSettled([
|
|
3764
|
-
mcpQuery("kb.listEntries", { collectionSlug: "glossary" }),
|
|
3765
|
-
mcpQuery("kb.listEntries", { collectionSlug: "standards" })
|
|
3766
|
-
]);
|
|
3767
|
-
const lines = ["# Product Brain \u2014 Terminology"];
|
|
3768
|
-
if (glossaryResult.status === "fulfilled") {
|
|
3769
|
-
if (glossaryResult.value.length > 0) {
|
|
3770
|
-
const terms = glossaryResult.value.map((t) => `- **${t.name}** (${t.entryId ?? "\u2014"}) [${t.status}]: ${t.data?.canonical ?? t.data?.description ?? ""}`).join("\n");
|
|
3771
|
-
lines.push(`## Glossary (${glossaryResult.value.length} terms)
|
|
3772
|
-
|
|
3773
|
-
${terms}`);
|
|
3774
|
-
} else {
|
|
3775
|
-
lines.push("## Glossary\n\nNo glossary terms yet. Use `create-entry` with collection `glossary` to add terms.");
|
|
3776
|
-
}
|
|
3777
|
-
} else {
|
|
3778
|
-
lines.push("## Glossary\n\nCould not load glossary \u2014 use `list-entries collection=glossary` to browse manually.");
|
|
3779
|
-
}
|
|
3780
|
-
if (standardsResult.status === "fulfilled") {
|
|
3781
|
-
if (standardsResult.value.length > 0) {
|
|
3782
|
-
const stds = standardsResult.value.map((s) => `- **${s.name}** (${s.entryId ?? "\u2014"}) [${s.status}]: ${s.data?.description ?? ""}`).join("\n");
|
|
3783
|
-
lines.push(`## Standards (${standardsResult.value.length} entries)
|
|
3784
|
-
|
|
3785
|
-
${stds}`);
|
|
3786
|
-
} else {
|
|
3787
|
-
lines.push("## Standards\n\nNo standards yet. Use `create-entry` with collection `standards` to add standards.");
|
|
3788
|
-
}
|
|
3789
|
-
} else {
|
|
3790
|
-
lines.push("## Standards\n\nCould not load standards \u2014 use `list-entries collection=standards` to browse manually.");
|
|
3791
|
-
}
|
|
3792
|
-
return {
|
|
3793
|
-
contents: [{ uri: uri.href, text: lines.join("\n\n---\n\n"), mimeType: "text/markdown" }]
|
|
3794
|
-
};
|
|
3795
|
-
}
|
|
3796
|
-
);
|
|
3797
|
-
server2.resource(
|
|
3798
|
-
"kb-collections",
|
|
3799
|
-
"productbrain://collections",
|
|
3800
|
-
async (uri) => {
|
|
3801
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
3802
|
-
if (collections.length === 0) {
|
|
3803
|
-
return { contents: [{ uri: uri.href, text: "No collections in this workspace.", mimeType: "text/markdown" }] };
|
|
3804
|
-
}
|
|
3805
|
-
const formatted = collections.map((c) => {
|
|
3806
|
-
const fieldList = c.fields.map((f) => ` - \`${f.key}\` (${f.type}${f.required ? ", required" : ""}${f.searchable ? ", searchable" : ""})`).join("\n");
|
|
3807
|
-
return `## ${c.icon ?? ""} ${c.name} (\`${c.slug}\`)
|
|
3808
|
-
${c.description || ""}
|
|
3809
|
-
|
|
3810
|
-
**Fields:**
|
|
3811
|
-
${fieldList}`;
|
|
3812
|
-
}).join("\n\n---\n\n");
|
|
3813
|
-
return {
|
|
3814
|
-
contents: [{ uri: uri.href, text: `# Knowledge Collections (${collections.length})
|
|
3815
|
-
|
|
3816
|
-
${formatted}`, mimeType: "text/markdown" }]
|
|
3817
|
-
};
|
|
3818
|
-
}
|
|
3819
|
-
);
|
|
3820
|
-
server2.resource(
|
|
3821
|
-
"kb-collection-entries",
|
|
3822
|
-
new ResourceTemplate("productbrain://{slug}/entries", {
|
|
3823
|
-
list: async () => {
|
|
3824
|
-
const collections = await mcpQuery("kb.listCollections");
|
|
3825
|
-
return {
|
|
3826
|
-
resources: collections.map((c) => ({
|
|
3827
|
-
uri: `productbrain://${c.slug}/entries`,
|
|
3828
|
-
name: `${c.icon ?? ""} ${c.name}`.trim()
|
|
3829
|
-
}))
|
|
3830
|
-
};
|
|
3831
|
-
}
|
|
3832
|
-
}),
|
|
3833
|
-
async (uri, { slug }) => {
|
|
3834
|
-
const entries = await mcpQuery("kb.listEntries", { collectionSlug: slug });
|
|
3835
|
-
const formatted = entries.map(formatEntryMarkdown).join("\n\n---\n\n");
|
|
3836
|
-
return {
|
|
3837
|
-
contents: [{
|
|
3838
|
-
uri: uri.href,
|
|
3839
|
-
text: formatted || "No entries in this collection.",
|
|
3840
|
-
mimeType: "text/markdown"
|
|
3841
|
-
}]
|
|
3842
|
-
};
|
|
3843
|
-
}
|
|
3844
|
-
);
|
|
3845
|
-
server2.resource(
|
|
3846
|
-
"kb-labels",
|
|
3847
|
-
"productbrain://labels",
|
|
3848
|
-
async (uri) => {
|
|
3849
|
-
const labels = await mcpQuery("kb.listLabels");
|
|
3850
|
-
if (labels.length === 0) {
|
|
3851
|
-
return { contents: [{ uri: uri.href, text: "No labels in this workspace.", mimeType: "text/markdown" }] };
|
|
3852
|
-
}
|
|
3853
|
-
const groups = labels.filter((l) => l.isGroup);
|
|
3854
|
-
const ungrouped = labels.filter((l) => !l.isGroup && !l.parentId);
|
|
3855
|
-
const children = (parentId) => labels.filter((l) => l.parentId === parentId);
|
|
3856
|
-
const lines = [];
|
|
3857
|
-
for (const group of groups) {
|
|
3858
|
-
lines.push(`## ${group.name}`);
|
|
3859
|
-
for (const child of children(group._id)) {
|
|
3860
|
-
lines.push(`- \`${child.slug}\` ${child.name}${child.color ? ` (${child.color})` : ""}`);
|
|
3861
|
-
}
|
|
3862
|
-
}
|
|
3863
|
-
if (ungrouped.length > 0) {
|
|
3864
|
-
lines.push("## Ungrouped");
|
|
3865
|
-
for (const l of ungrouped) {
|
|
3866
|
-
lines.push(`- \`${l.slug}\` ${l.name}${l.color ? ` (${l.color})` : ""}`);
|
|
3867
|
-
}
|
|
3868
|
-
}
|
|
3869
|
-
return {
|
|
3870
|
-
contents: [{ uri: uri.href, text: `# Workspace Labels (${labels.length})
|
|
3871
|
-
|
|
3872
|
-
${lines.join("\n")}`, mimeType: "text/markdown" }]
|
|
3873
|
-
};
|
|
3874
|
-
}
|
|
3875
|
-
);
|
|
3876
|
-
}
|
|
3877
|
-
|
|
3878
|
-
// src/prompts/index.ts
|
|
3879
|
-
import { z as z9 } from "zod";
|
|
3880
|
-
function registerPrompts(server2) {
|
|
3881
|
-
server2.prompt(
|
|
3882
|
-
"review-against-rules",
|
|
3883
|
-
"Review code or a design decision against all business rules for a given domain. Fetches the rules and asks you to do a structured compliance review.",
|
|
3884
|
-
{ domain: z9.string().describe("Business rule domain (e.g. 'Identity & Access', 'Governance & Decision-Making')") },
|
|
3885
|
-
async ({ domain }) => {
|
|
3886
|
-
const entries = await mcpQuery("kb.listEntries", { collectionSlug: "business-rules" });
|
|
3887
|
-
const rules = entries.filter((e) => e.data?.domain === domain);
|
|
3888
|
-
if (rules.length === 0) {
|
|
3889
|
-
return {
|
|
3890
|
-
messages: [
|
|
3891
|
-
{
|
|
3892
|
-
role: "user",
|
|
3893
|
-
content: {
|
|
3894
|
-
type: "text",
|
|
3895
|
-
text: `No business rules found for domain "${domain}". Use the list-entries tool with collection "business-rules" to see available domains.`
|
|
3896
|
-
}
|
|
3897
|
-
}
|
|
3898
|
-
]
|
|
3899
|
-
};
|
|
3900
|
-
}
|
|
3901
|
-
const rulesText = rules.map(
|
|
3902
|
-
(r) => `### ${r.entryId ?? ""}: ${r.name}
|
|
3903
|
-
Status: ${r.status} | Severity: ${r.data?.severity ?? "unknown"}
|
|
3904
|
-
Description: ${r.data?.description ?? ""}
|
|
3905
|
-
Data Impact: ${r.data?.dataImpact ?? ""}
|
|
3906
|
-
Platforms: ${(r.data?.platforms ?? []).join(", ")}
|
|
3907
|
-
` + (r.data?.conflictWith ? `CONFLICT: ${r.data.conflictWith.rule} \u2014 ${r.data.conflictWith.nature}
|
|
3908
|
-
` : "")
|
|
3909
|
-
).join("\n---\n\n");
|
|
3910
|
-
return {
|
|
3911
|
-
messages: [
|
|
3912
|
-
{
|
|
3913
|
-
role: "user",
|
|
3914
|
-
content: {
|
|
3915
|
-
type: "text",
|
|
3916
|
-
text: `Review the current code or design against the following business rules for the "${domain}" domain.
|
|
3917
|
-
|
|
3918
|
-
For each rule, assess:
|
|
3919
|
-
1. Is the current implementation compliant?
|
|
3920
|
-
2. Are there potential violations or edge cases?
|
|
3921
|
-
3. What specific changes would be needed for compliance?
|
|
3922
|
-
|
|
3923
|
-
Business Rules:
|
|
3924
|
-
|
|
3925
|
-
${rulesText}
|
|
3926
|
-
|
|
3927
|
-
Provide a structured review with a compliance status for each rule (COMPLIANT / AT RISK / VIOLATION / NOT APPLICABLE).`
|
|
3928
|
-
}
|
|
3929
|
-
}
|
|
3930
|
-
]
|
|
3931
|
-
};
|
|
3932
|
-
}
|
|
3933
|
-
);
|
|
3934
|
-
server2.prompt(
|
|
3935
|
-
"name-check",
|
|
3936
|
-
"Check variable names, field names, or API names against the glossary for terminology alignment. Flags drift from canonical terms.",
|
|
3937
|
-
{ names: z9.string().describe("Comma-separated list of names to check (e.g. 'vendor_id, compliance_level, formulator_type')") },
|
|
3938
|
-
async ({ names }) => {
|
|
3939
|
-
const terms = await mcpQuery("kb.listEntries", { collectionSlug: "glossary" });
|
|
3940
|
-
const glossaryContext = terms.map(
|
|
3941
|
-
(t) => `${t.name} (${t.entryId ?? ""}) [${t.status}]: ${t.data?.canonical ?? ""}` + (t.data?.confusedWith?.length > 0 ? ` \u2014 Often confused with: ${t.data.confusedWith.join(", ")}` : "") + (t.data?.codeMapping?.length > 0 ? `
|
|
3942
|
-
Code mappings: ${t.data.codeMapping.map((m) => `${m.platform}:${m.field}`).join(", ")}` : "")
|
|
3943
|
-
).join("\n");
|
|
3944
|
-
return {
|
|
3945
|
-
messages: [
|
|
3946
|
-
{
|
|
3947
|
-
role: "user",
|
|
3948
|
-
content: {
|
|
3949
|
-
type: "text",
|
|
3950
|
-
text: `Check the following names against the glossary for terminology alignment:
|
|
3951
|
-
|
|
3952
|
-
Names to check: ${names}
|
|
3953
|
-
|
|
3954
|
-
Glossary (canonical terms):
|
|
3955
|
-
${glossaryContext}
|
|
3956
|
-
|
|
3957
|
-
For each name:
|
|
3958
|
-
1. Does it match a canonical term? If so, which one?
|
|
3959
|
-
2. Is there terminology drift? (e.g. using "vendor" instead of "supplier", "compliance" instead of "conformance")
|
|
3960
|
-
3. Suggest the canonical alternative if drift is detected.
|
|
3961
|
-
4. Flag any names that don't have a corresponding glossary term (might need one).
|
|
3962
|
-
|
|
3963
|
-
Format as a table: Name | Status | Canonical Form | Action Needed`
|
|
3964
|
-
}
|
|
3965
|
-
}
|
|
3966
|
-
]
|
|
3967
|
-
};
|
|
3968
|
-
}
|
|
3969
|
-
);
|
|
3970
|
-
server2.prompt(
|
|
3971
|
-
"draft-decision-record",
|
|
3972
|
-
"Draft a structured decision record from a description of what was decided. Includes context from recent decisions and relevant rules.",
|
|
3973
|
-
{ context: z9.string().describe("Description of the decision (e.g. 'We decided to use MRSL v3.1 as the conformance baseline because...')") },
|
|
3974
|
-
async ({ context }) => {
|
|
3975
|
-
const recentDecisions = await mcpQuery("kb.listEntries", { collectionSlug: "decisions" });
|
|
3976
|
-
const sorted = [...recentDecisions].sort((a, b) => (b.data?.date ?? "") > (a.data?.date ?? "") ? 1 : -1).slice(0, 5);
|
|
3977
|
-
const recentContext = sorted.length > 0 ? sorted.map((d) => `- [${d.status}] ${d.name} (${d.data?.date ?? "no date"})`).join("\n") : "No previous decisions recorded.";
|
|
3978
|
-
return {
|
|
3979
|
-
messages: [
|
|
3980
|
-
{
|
|
3981
|
-
role: "user",
|
|
3982
|
-
content: {
|
|
3983
|
-
type: "text",
|
|
3984
|
-
text: `Draft a structured decision record from the following context:
|
|
3985
|
-
|
|
3986
|
-
"${context}"
|
|
3987
|
-
|
|
3988
|
-
Recent decisions for reference:
|
|
3989
|
-
${recentContext}
|
|
3990
|
-
|
|
3991
|
-
Structure the decision record with:
|
|
3992
|
-
1. **Title**: Concise decision statement
|
|
3993
|
-
2. **Decided by**: Who made or approved this decision
|
|
3994
|
-
3. **Date**: When it was decided
|
|
3995
|
-
4. **Status**: decided / proposed / revisited
|
|
3996
|
-
5. **Rationale**: Why this decision was made, including trade-offs considered
|
|
3997
|
-
6. **Alternatives considered**: What else was on the table
|
|
3998
|
-
7. **Related rules or tensions**: Any business rules or tensions this connects to
|
|
3999
|
-
|
|
4000
|
-
After drafting, I can log it using the create-entry tool with collection "decisions".`
|
|
4001
|
-
}
|
|
4002
|
-
}
|
|
4003
|
-
]
|
|
4004
|
-
};
|
|
4005
|
-
}
|
|
4006
|
-
);
|
|
4007
|
-
server2.prompt(
|
|
4008
|
-
"draft-rule-from-context",
|
|
4009
|
-
"Draft a new business rule from an observation or discovery made while coding. Fetches existing rules for the domain to ensure consistency.",
|
|
4010
|
-
{
|
|
4011
|
-
observation: z9.string().describe("What you observed or discovered (e.g. 'Suppliers can have multiple org types in Gateway')"),
|
|
4012
|
-
domain: z9.string().describe("Which domain this rule belongs to (e.g. 'Governance & Decision-Making')")
|
|
4013
|
-
},
|
|
4014
|
-
async ({ observation, domain }) => {
|
|
4015
|
-
const allRules = await mcpQuery("kb.listEntries", { collectionSlug: "business-rules" });
|
|
4016
|
-
const existingRules = allRules.filter((r) => r.data?.domain === domain);
|
|
4017
|
-
const existingContext = existingRules.length > 0 ? existingRules.map((r) => `${r.entryId ?? ""}: ${r.name} [${r.status}] \u2014 ${r.data?.description ?? ""}`).join("\n") : "No existing rules for this domain.";
|
|
4018
|
-
const highestRuleNum = allRules.map((r) => parseInt((r.entryId ?? "").replace(/^[A-Z]+-/, ""), 10)).filter((n) => !isNaN(n)).sort((a, b) => b - a)[0] || 0;
|
|
4019
|
-
const nextRuleId = `SOS-${String(highestRuleNum + 1).padStart(3, "0")}`;
|
|
4020
|
-
return {
|
|
4021
|
-
messages: [
|
|
4022
|
-
{
|
|
4023
|
-
role: "user",
|
|
4024
|
-
content: {
|
|
4025
|
-
type: "text",
|
|
4026
|
-
text: `Draft a business rule based on this observation:
|
|
4027
|
-
|
|
4028
|
-
"${observation}"
|
|
4029
|
-
|
|
4030
|
-
Domain: ${domain}
|
|
4031
|
-
Suggested rule ID: ${nextRuleId}
|
|
4032
|
-
|
|
4033
|
-
Existing rules in this domain:
|
|
4034
|
-
${existingContext}
|
|
4035
|
-
|
|
4036
|
-
Draft the rule with these fields:
|
|
4037
|
-
1. **entryId**: ${nextRuleId}
|
|
4038
|
-
2. **name**: Concise rule title
|
|
4039
|
-
3. **data.description**: What the rule states
|
|
4040
|
-
4. **data.rationale**: Why this rule matters
|
|
4041
|
-
5. **data.dataImpact**: How this affects data models, APIs, or storage
|
|
4042
|
-
6. **data.severity**: high / medium / low
|
|
4043
|
-
7. **data.platforms**: Which platforms are affected
|
|
4044
|
-
8. **data.relatedRules**: Any related existing rules
|
|
4045
|
-
|
|
4046
|
-
Make sure the rule is consistent with existing rules and doesn't contradict them. After drafting, I can create it using the create-entry tool with collection "business-rules".`
|
|
4047
|
-
}
|
|
4048
|
-
}
|
|
4049
|
-
]
|
|
4050
|
-
};
|
|
4051
|
-
}
|
|
4052
|
-
);
|
|
4053
|
-
server2.prompt(
|
|
4054
|
-
"run-workflow",
|
|
4055
|
-
"Launch a Chainwork workflow (retro, shape, IDM) in Facilitator Mode. Returns the full workflow definition, facilitation instructions, and round structure. The agent enters Facilitator Mode and guides the participant through each round.",
|
|
4056
|
-
{
|
|
4057
|
-
workflow: z9.string().describe(
|
|
4058
|
-
"Workflow ID to run. Available: " + listWorkflows().map((w) => `'${w.id}' (${w.name})`).join(", ")
|
|
4059
|
-
),
|
|
4060
|
-
context: z9.string().optional().describe(
|
|
4061
|
-
"Optional context from the participant (e.g., 'retro on last sprint', 'shape the Chainwork API bet')"
|
|
4062
|
-
)
|
|
4063
|
-
},
|
|
4064
|
-
async ({ workflow: workflowId, context }) => {
|
|
4065
|
-
const wf = getWorkflow(workflowId);
|
|
4066
|
-
if (!wf) {
|
|
4067
|
-
const available = listWorkflows().map((w) => `- **${w.id}**: ${w.name} \u2014 ${w.shortDescription}`).join("\n");
|
|
4068
|
-
return {
|
|
4069
|
-
messages: [
|
|
4070
|
-
{
|
|
4071
|
-
role: "user",
|
|
4072
|
-
content: {
|
|
4073
|
-
type: "text",
|
|
4074
|
-
text: `Workflow "${workflowId}" not found.
|
|
4075
|
-
|
|
4076
|
-
Available workflows:
|
|
4077
|
-
${available}
|
|
4078
|
-
|
|
4079
|
-
Use one of these IDs to run a workflow.`
|
|
4080
|
-
}
|
|
4081
|
-
}
|
|
4082
|
-
]
|
|
4083
|
-
};
|
|
4084
|
-
}
|
|
4085
|
-
let kbContext = "";
|
|
4086
|
-
try {
|
|
4087
|
-
const recentDecisions = await mcpQuery("kb.listEntries", {
|
|
4088
|
-
collectionSlug: wf.kbOutputCollection
|
|
4089
|
-
});
|
|
4090
|
-
const sorted = [...recentDecisions].sort((a, b) => (b.data?.date ?? "") > (a.data?.date ?? "") ? 1 : -1).slice(0, 5);
|
|
4091
|
-
if (sorted.length > 0) {
|
|
4092
|
-
kbContext = `
|
|
4093
|
-
## Recent ${wf.kbOutputCollection} entries (for context)
|
|
4094
|
-
` + sorted.map((d) => `- ${d.entryId ?? ""}: ${d.name} [${d.status}]`).join("\n");
|
|
4095
|
-
}
|
|
4096
|
-
} catch {
|
|
4097
|
-
kbContext = "\n_Could not load KB context \u2014 proceed without it._";
|
|
4098
|
-
}
|
|
4099
|
-
const roundsPlan = wf.rounds.map(
|
|
4100
|
-
(r) => `### Round ${r.num}: ${r.label}
|
|
4101
|
-
**Type**: ${r.type} | **Duration**: ~${r.maxDurationHint ?? "5 min"}
|
|
4102
|
-
**Instruction**: ${r.instruction}
|
|
4103
|
-
**Facilitator guidance**: ${r.facilitatorGuidance}
|
|
4104
|
-
` + (r.questions ? r.questions.map(
|
|
4105
|
-
(q) => `**Question**: ${q.prompt}
|
|
4106
|
-
` + (q.options ? q.options.map((o) => ` - ${o.id}: ${o.label}`).join("\n") : " _(open response)_")
|
|
4107
|
-
).join("\n") : "") + `
|
|
4108
|
-
**Output**: Capture to \`${r.outputSchema.field}\` (${r.outputSchema.format})`
|
|
4109
|
-
).join("\n\n---\n\n");
|
|
4110
|
-
const contextLine = context ? `
|
|
4111
|
-
The participant provided this context: "${context}"
|
|
4112
|
-
Use it \u2014 don't make them repeat themselves.
|
|
4113
|
-
` : "";
|
|
4114
|
-
return {
|
|
4115
|
-
messages: [
|
|
4116
|
-
{
|
|
4117
|
-
role: "user",
|
|
4118
|
-
content: {
|
|
4119
|
-
type: "text",
|
|
4120
|
-
text: `# ${wf.icon} ${wf.name} Workflow \u2014 Facilitator Mode
|
|
4121
|
-
|
|
4122
|
-
${wf.shortDescription}
|
|
4123
|
-
` + contextLine + `
|
|
4124
|
-
---
|
|
4125
|
-
|
|
4126
|
-
## Facilitator Instructions
|
|
4127
|
-
|
|
4128
|
-
${wf.facilitatorPreamble}
|
|
4129
|
-
|
|
4130
|
-
---
|
|
4131
|
-
|
|
4132
|
-
## Rounds
|
|
4133
|
-
|
|
4134
|
-
${roundsPlan}
|
|
4135
|
-
|
|
4136
|
-
---
|
|
4137
|
-
|
|
4138
|
-
## Error Recovery
|
|
4139
|
-
|
|
4140
|
-
${wf.errorRecovery}
|
|
4141
|
-
|
|
4142
|
-
---
|
|
4143
|
-
|
|
4144
|
-
## KB Output
|
|
4145
|
-
|
|
4146
|
-
When complete, use \`smart-capture\` to create a \`${wf.kbOutputCollection}\` entry.
|
|
4147
|
-
Name template: ${wf.kbOutputTemplate.nameTemplate}
|
|
4148
|
-
Description field: ${wf.kbOutputTemplate.descriptionField}
|
|
4149
|
-
` + kbContext + `
|
|
4150
|
-
|
|
4151
|
-
---
|
|
4152
|
-
|
|
4153
|
-
**BEGIN THE WORKFLOW NOW.** Start with Round 01. Create a Plan first.`
|
|
4154
|
-
}
|
|
4155
|
-
}
|
|
4156
|
-
]
|
|
4157
|
-
};
|
|
4158
|
-
}
|
|
4159
|
-
);
|
|
4160
|
-
}
|
|
4161
|
-
|
|
4162
|
-
// src/index.ts
|
|
23
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
4163
24
|
if (!process.env.CONVEX_SITE_URL && !process.env.PRODUCTBRAIN_API_KEY) {
|
|
4164
25
|
try {
|
|
4165
|
-
const envPath =
|
|
4166
|
-
for (const line of
|
|
26
|
+
const envPath = resolve(process.cwd(), ".env.mcp");
|
|
27
|
+
for (const line of readFileSync(envPath, "utf-8").split("\n")) {
|
|
4167
28
|
const trimmed = line.trim();
|
|
4168
29
|
if (!trimmed || trimmed.startsWith("#")) continue;
|
|
4169
30
|
const eqIdx = trimmed.indexOf("=");
|
|
@@ -4173,75 +34,38 @@ if (!process.env.CONVEX_SITE_URL && !process.env.PRODUCTBRAIN_API_KEY) {
|
|
|
4173
34
|
} catch {
|
|
4174
35
|
}
|
|
4175
36
|
}
|
|
4176
|
-
|
|
4177
|
-
var SERVER_VERSION = "1.0.0";
|
|
37
|
+
bootstrap();
|
|
4178
38
|
initAnalytics();
|
|
4179
|
-
var
|
|
4180
|
-
try {
|
|
4181
|
-
workspaceId = await getWorkspaceId();
|
|
4182
|
-
} catch (err) {
|
|
4183
|
-
const hint = !process.env.PRODUCTBRAIN_API_KEY && !process.env.CONVEX_SITE_URL ? "\n[MCP] Hint: Set PRODUCTBRAIN_API_KEY in your MCP config env block, or run `npx productbrain setup`." : "";
|
|
4184
|
-
process.stderr.write(`[MCP] Startup failed: ${err.message}${hint}
|
|
4185
|
-
`);
|
|
4186
|
-
process.exit(1);
|
|
4187
|
-
}
|
|
4188
|
-
trackSessionStarted(
|
|
4189
|
-
process.env.WORKSPACE_SLUG ?? "unknown",
|
|
4190
|
-
workspaceId,
|
|
4191
|
-
SERVER_VERSION
|
|
4192
|
-
);
|
|
4193
|
-
var server = new McpServer2(
|
|
4194
|
-
{
|
|
4195
|
-
name: "Product Brain",
|
|
4196
|
-
version: SERVER_VERSION
|
|
4197
|
-
},
|
|
4198
|
-
{
|
|
4199
|
-
capabilities: { logging: {} },
|
|
4200
|
-
instructions: [
|
|
4201
|
-
"Product Brain \u2014 the single source of truth for product knowledge.",
|
|
4202
|
-
"Terminology, standards, and core data all live here \u2014 no need to check external docs.",
|
|
4203
|
-
"",
|
|
4204
|
-
"Terminology & naming: For 'what is X?' or naming questions, fetch `productbrain://terminology`",
|
|
4205
|
-
"or use the `name-check` prompt to validate names against the glossary.",
|
|
4206
|
-
"",
|
|
4207
|
-
"Workflow:",
|
|
4208
|
-
" 1. Verify: call `health` to confirm connectivity.",
|
|
4209
|
-
" 2. Terminology: fetch `productbrain://terminology` or use `name-check` prompt for naming questions.",
|
|
4210
|
-
" 3. Discover: use `kb-search` to find entries by text, or `list-entries` to browse a collection.",
|
|
4211
|
-
" 4. Drill in: use `get-entry` for full details \u2014 data, labels, relations, history.",
|
|
4212
|
-
" 5. Capture: use `smart-capture` to create entries \u2014 it auto-links related entries and",
|
|
4213
|
-
" returns a quality scorecard in one call. Use `create-entry` only when you need",
|
|
4214
|
-
" full control over every field.",
|
|
4215
|
-
" 6. Connect: use `suggest-links` then `relate-entries` to build the graph.",
|
|
4216
|
-
" 7. Quality: use `quality-check` to assess entry completeness.",
|
|
4217
|
-
" 8. Debug: use `mcp-audit` to see what backend calls happened this session.",
|
|
4218
|
-
"",
|
|
4219
|
-
"Always prefer `smart-capture` over `create-entry` or `quick-capture` for new entries.",
|
|
4220
|
-
"Always prefer kb-search or list-entries before get-entry \u2014 discover, then drill in.",
|
|
4221
|
-
"",
|
|
4222
|
-
"Orientation:",
|
|
4223
|
-
" When you need to understand the system \u2014 architecture, data model, rules,",
|
|
4224
|
-
" or analytics \u2014 fetch the `productbrain://orientation` resource first.",
|
|
4225
|
-
" It gives you the map. Then use the appropriate tool to drill in."
|
|
4226
|
-
].join("\n")
|
|
4227
|
-
}
|
|
4228
|
-
);
|
|
4229
|
-
registerKnowledgeTools(server);
|
|
4230
|
-
registerLabelTools(server);
|
|
4231
|
-
registerHealthTools(server);
|
|
4232
|
-
registerVerifyTools(server);
|
|
4233
|
-
registerSmartCaptureTools(server);
|
|
4234
|
-
registerArchitectureTools(server);
|
|
4235
|
-
registerWorkflowTools(server);
|
|
4236
|
-
registerGitChainTools(server);
|
|
4237
|
-
registerResources(server);
|
|
4238
|
-
registerPrompts(server);
|
|
39
|
+
var server = createProductBrainServer();
|
|
4239
40
|
var transport = new StdioServerTransport();
|
|
4240
41
|
await server.connect(transport);
|
|
42
|
+
getWorkspaceId().then(async (wsId) => {
|
|
43
|
+
trackSessionStarted(wsId, SERVER_VERSION);
|
|
44
|
+
try {
|
|
45
|
+
await startAgentSession();
|
|
46
|
+
process.stderr.write("[MCP] Agent session started automatically.\n");
|
|
47
|
+
} catch (err) {
|
|
48
|
+
process.stderr.write(`[MCP] Auto session start failed: ${err.message}. Call agent-start manually.
|
|
49
|
+
`);
|
|
50
|
+
await recoverSessionState();
|
|
51
|
+
}
|
|
52
|
+
}).catch(() => {
|
|
53
|
+
process.stderr.write("[MCP] Workspace resolution deferred \u2014 will retry on first tool call.\n");
|
|
54
|
+
});
|
|
4241
55
|
async function gracefulShutdown() {
|
|
56
|
+
if (getAgentSessionId()) {
|
|
57
|
+
await orphanAgentSession();
|
|
58
|
+
}
|
|
4242
59
|
await shutdownAnalytics();
|
|
4243
60
|
process.exit(0);
|
|
4244
61
|
}
|
|
4245
62
|
process.on("SIGINT", gracefulShutdown);
|
|
4246
63
|
process.on("SIGTERM", gracefulShutdown);
|
|
64
|
+
process.stdin.on("end", async () => {
|
|
65
|
+
if (getAgentSessionId()) {
|
|
66
|
+
await orphanAgentSession();
|
|
67
|
+
}
|
|
68
|
+
await shutdownAnalytics();
|
|
69
|
+
process.exit(0);
|
|
70
|
+
});
|
|
4247
71
|
//# sourceMappingURL=index.js.map
|