@shrkcrft/mcp-server 0.1.0-alpha.2

package/dist/tools/agent-brief-chunks.tool.js

@@ -0,0 +1,326 @@
+import { createHash } from 'node:crypto';
+import { buildAgentBrief, BriefMode } from '@shrkcrft/inspector';
+const VALID_MODES = new Set(Object.values(BriefMode));
+const CACHE = new Map();
+const TTL_MS = 60 * 60 * 1000; // one hour
+const SERVER_STARTED_AT = Date.now();
+function gcCache() {
+    const now = Date.now();
+    for (const [k, v] of CACHE) {
+        if (v.expiresAt < now)
+            CACHE.delete(k);
+    }
+}
+function canonicalInput(input) {
+    return JSON.stringify({
+        task: input['task'] ?? '',
+        mode: input['mode'] ?? '',
+        files: [...(input['files'] ?? [])].sort(),
+        bundleId: input['bundleId'] ?? '',
+        sessionId: input['sessionId'] ?? '',
+        maxTokens: input['maxTokens'] ?? null,
+        sectionBudgets: input['sectionBudgets'] ?? {},
+    });
+}
+function computeBriefId(input) {
+    return createHash('sha256').update(canonicalInput(input)).digest('hex').slice(0, 16);
+}
+function inputForBrief(input) {
+    const task = typeof input.task === 'string' ? input.task : undefined;
+    const modeRaw = typeof input.mode === 'string' ? input.mode : undefined;
+    const mode = modeRaw && VALID_MODES.has(modeRaw) ? modeRaw : undefined;
+    const files = Array.isArray(input.files) ? input.files : [];
+    const bundleId = typeof input.bundleId === 'string' ? input.bundleId : undefined;
+    const sessionId = typeof input.sessionId === 'string' ? input.sessionId : undefined;
+    const maxTokens = typeof input.maxTokens === 'number' ? input.maxTokens : undefined;
+    const sectionBudgets = typeof input.sectionBudgets === 'object' && input.sectionBudgets !== null
+        ? input.sectionBudgets
+        : undefined;
+    return {
+        ...(task ? { task } : {}),
+        ...(mode ? { mode } : {}),
+        files,
+        ...(bundleId ? { bundleId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        ...(maxTokens ? { maxTokens } : {}),
+        ...(sectionBudgets ? { sectionBudgets } : {}),
+        chunked: true,
+    };
+}
+export const startAgentBriefChunksTool = {
+    name: 'start_agent_brief_chunks',
+    description: 'Build a chunked agent brief and cache it server-side. Returns a deterministic briefId + index. Use `get_agent_brief_chunk` / `get_agent_brief_chunk_index` to retrieve chunks individually. Optional `previousSectionHashes` lets the caller request a section-level delta even when no in-memory cache exists. Read-only — no filesystem writes.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string' },
+            mode: { type: 'string' },
+            files: { type: 'array', items: { type: 'string' } },
+            bundleId: { type: 'string' },
+            sessionId: { type: 'string' },
+            maxTokens: { type: 'number' },
+            sectionBudgets: { type: 'object' },
+            previousSectionHashes: { type: 'object' },
+        },
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        gcCache();
+        const briefId = computeBriefId(input);
+        const inputHash = createHash('sha256')
+            .update(canonicalInput(input))
+            .digest('hex');
+        let cached = CACHE.get(briefId);
+        let reused = false;
+        let previousBriefId = null;
+        let deltaSummary = null;
+        let priorSectionHashes = null;
+        // Caller can pass previousSectionHashes directly so the delta works
+        // across server restarts / cold caches.
+        const explicitPrior = input.previousSectionHashes;
+        if (explicitPrior && typeof explicitPrior === 'object') {
+            const candidate = {};
+            for (const [k, v] of Object.entries(explicitPrior)) {
+                if (typeof v === 'string')
+                    candidate[k] = v;
+            }
+            if (Object.keys(candidate).length > 0) {
+                priorSectionHashes = candidate;
+            }
+        }
+        if (cached) {
+            reused = true;
+        }
+        else {
+            // Look for the most recent cached brief with the same `task` so we can
+            // report which sections actually changed.
+            const taskRaw = input['task'];
+            const task = typeof taskRaw === 'string' ? taskRaw : '';
+            if (task && !priorSectionHashes) {
+                let best = null;
+                for (const candidate of CACHE.values()) {
+                    if (candidate.task !== task)
+                        continue;
+                    if (!best || candidate.expiresAt > best.expiresAt)
+                        best = candidate;
+                }
+                if (best) {
+                    previousBriefId = best.briefId;
+                    priorSectionHashes = best.sectionHashes;
+                }
+            }
+            const brief = await buildAgentBrief(ctx.inspection, inputForBrief(input));
+            const sectionHashes = {};
+            for (const c of brief.chunks ?? []) {
+                sectionHashes[c.sectionId] = createHash('sha256').update(c.body).digest('hex');
+            }
+            cached = {
+                briefId,
+                brief,
+                expiresAt: Date.now() + TTL_MS,
+                inputHash,
+                sectionHashes,
+                task,
+            };
+            CACHE.set(briefId, cached);
+            if (priorSectionHashes) {
+                let same = 0;
+                let changed = 0;
+                let added = 0;
+                const seen = new Set();
+                for (const [id, h] of Object.entries(sectionHashes)) {
+                    seen.add(id);
+                    const prev = priorSectionHashes[id];
+                    if (prev === undefined)
+                        added += 1;
+                    else if (prev === h)
+                        same += 1;
+                    else
+                        changed += 1;
+                }
+                let removed = 0;
+                for (const id of Object.keys(priorSectionHashes))
+                    if (!seen.has(id))
+                        removed += 1;
+                deltaSummary = { reused: same, changed, unchanged: same, new: added, removed };
+            }
+        }
+        const chunks = cached.brief.chunks ?? [];
+        return {
+            data: {
+                briefId,
+                mode: cached.brief.mode,
+                task: cached.brief.task,
+                totalChunks: chunks.length,
+                totalTokenEstimate: cached.brief.totalTokenEstimate,
+                cacheTtlMs: TTL_MS,
+                expiresAt: new Date(cached.expiresAt).toISOString(),
+                deterministicInputHash: inputHash,
+                canRecreate: true,
+                reused,
+                previousBriefId,
+                delta: deltaSummary,
+                sectionHashes: cached.sectionHashes,
+                serverStartedAt: new Date(SERVER_STARTED_AT).toISOString(),
+                index: chunks.map((c, i) => ({
+                    order: i,
+                    file: c.file,
+                    sectionId: c.sectionId,
+                    title: c.title,
+                    tokenEstimate: c.tokenEstimate,
+                })),
+            },
+        };
+    },
+};
+export const getAgentBriefChunkIndexTool = {
+    name: 'get_agent_brief_chunk_index',
+    description: 'Return the chunk index for a brief previously started via `start_agent_brief_chunks`. Read-only.',
+    inputSchema: {
+        type: 'object',
+        required: ['briefId'],
+        properties: { briefId: { type: 'string' } },
+    },
+    handler(input) {
+        gcCache();
+        const briefId = String(input['briefId'] ?? '');
+        const cached = CACHE.get(briefId);
+        if (!cached) {
+            return {
+                isError: true,
+                text: `No cached brief for id "${briefId}". Cache may have evicted or the server restarted. Re-run start_agent_brief_chunks with the same input — briefIds are deterministic.`,
+                data: {
+                    error: {
+                        code: 'cache-miss',
+                        message: `No cached brief for id "${briefId}". Cache may have evicted or the server restarted.`,
+                        briefId,
+                        canRecreate: true,
+                        recommendedCall: {
+                            tool: 'start_agent_brief_chunks',
+                            note: 'Call start_agent_brief_chunks with the original inputs. The briefId is deterministic so re-creating with the same input recovers the same id.',
+                        },
+                        serverStartedAt: new Date(SERVER_STARTED_AT).toISOString(),
+                    },
+                },
+                error: {
+                    code: 'cache-miss',
+                    message: `No cached brief for id "${briefId}". Cache may have evicted or the server restarted.`,
+                    details: {
+                        briefId,
+                        canRecreate: true,
+                        recommendedCall: {
+                            tool: 'start_agent_brief_chunks',
+                            note: 'Call start_agent_brief_chunks with the original inputs. The briefId is deterministic so re-creating with the same input recovers the same id.',
+                        },
+                        serverStartedAt: new Date(SERVER_STARTED_AT).toISOString(),
+                    },
+                },
+            };
+        }
+        const chunks = cached.brief.chunks ?? [];
+        return {
+            data: {
+                briefId,
+                mode: cached.brief.mode,
+                task: cached.brief.task,
+                totalChunks: chunks.length,
+                totalTokenEstimate: cached.brief.totalTokenEstimate,
+                expiresAt: new Date(cached.expiresAt).toISOString(),
+                deterministicInputHash: cached.inputHash,
+                canRecreate: true,
+                index: chunks.map((c, i) => ({
+                    order: i,
+                    file: c.file,
+                    sectionId: c.sectionId,
+                    title: c.title,
+                    tokenEstimate: c.tokenEstimate,
+                })),
+            },
+        };
+    },
+};
+export const getAgentBriefChunkTool = {
+    name: 'get_agent_brief_chunk',
+    description: 'Retrieve one chunk of a previously-started brief by id and either `order` or `sectionId`. Read-only.',
+    inputSchema: {
+        type: 'object',
+        required: ['briefId'],
+        properties: {
+            briefId: { type: 'string' },
+            order: { type: 'number' },
+            sectionId: { type: 'string' },
+        },
+    },
+    handler(input) {
+        gcCache();
+        const briefId = String(input['briefId'] ?? '');
+        const cached = CACHE.get(briefId);
+        if (!cached) {
+            return {
+                isError: true,
+                text: `No cached brief for id "${briefId}". Cache may have evicted or the server restarted. Re-run start_agent_brief_chunks with the same input — briefIds are deterministic.`,
+                data: {
+                    error: {
+                        code: 'cache-miss',
+                        message: `No cached brief for id "${briefId}". Cache may have evicted or the server restarted.`,
+                        briefId,
+                        canRecreate: true,
+                        recommendedCall: {
+                            tool: 'start_agent_brief_chunks',
+                            note: 'Call start_agent_brief_chunks with the original inputs. The briefId is deterministic so re-creating with the same input recovers the same id.',
+                        },
+                        serverStartedAt: new Date(SERVER_STARTED_AT).toISOString(),
+                    },
+                },
+                error: {
+                    code: 'cache-miss',
+                    message: `No cached brief for id "${briefId}". Cache may have evicted or the server restarted.`,
+                    details: {
+                        briefId,
+                        canRecreate: true,
+                        recommendedCall: {
+                            tool: 'start_agent_brief_chunks',
+                            note: 'Call start_agent_brief_chunks with the original inputs. The briefId is deterministic so re-creating with the same input recovers the same id.',
+                        },
+                        serverStartedAt: new Date(SERVER_STARTED_AT).toISOString(),
+                    },
+                },
+            };
+        }
+        const chunks = cached.brief.chunks ?? [];
+        const order = typeof input['order'] === 'number' ? input['order'] : undefined;
+        const sectionId = typeof input['sectionId'] === 'string' ? input['sectionId'] : undefined;
+        let chunk = chunks[0];
+        if (typeof order === 'number') {
+            chunk = chunks[order];
+        }
+        else if (sectionId) {
+            chunk = chunks.find((c) => c.sectionId === sectionId);
+        }
+        if (!chunk) {
+            return {
+                isError: true,
+                text: `No chunk for order=${order ?? '?'} sectionId=${sectionId ?? '?'}.`,
+                error: {
+                    code: 'not-found',
+                    message: `No chunk for order=${order ?? '?'} sectionId=${sectionId ?? '?'}.`,
+                    details: { briefId, totalChunks: chunks.length },
+                },
+            };
+        }
+        return {
+            data: {
+                briefId,
+                file: chunk.file,
+                sectionId: chunk.sectionId,
+                title: chunk.title,
+                body: chunk.body,
+                tokenEstimate: chunk.tokenEstimate,
+                expiresAt: new Date(cached.expiresAt).toISOString(),
+            },
+        };
+    },
+};
+export function _resetAgentBriefChunkCache() {
+    CACHE.clear();
+}

package/dist/tools/agent-brief.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const createAgentBriefTool: IToolDefinition;
+//# sourceMappingURL=agent-brief.tool.d.ts.map

package/dist/tools/agent-brief.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-brief.tool.d.ts","sourceRoot":"","sources":["../../src/tools/agent-brief.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC"}

package/dist/tools/agent-brief.tool.js

@@ -0,0 +1,44 @@
+import { buildAgentBrief, BriefMode } from '@shrkcrft/inspector';
+const VALID_MODES = new Set(Object.values(BriefMode));
+export const createAgentBriefTool = {
+    name: 'create_agent_brief',
+    description: 'Render a single-document Markdown / JSON brief for an AI agent before it starts work. Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string' },
+            mode: { type: 'string' },
+            files: { type: 'array', items: { type: 'string' } },
+            bundleId: { type: 'string' },
+            sessionId: { type: 'string' },
+            maxTokens: { type: 'number' },
+            chunked: { type: 'boolean' },
+            sectionBudgets: { type: 'object' },
+        },
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const task = typeof input['task'] === 'string' ? input['task'] : undefined;
+        const modeRaw = typeof input['mode'] === 'string' ? input['mode'] : undefined;
+        const mode = modeRaw && VALID_MODES.has(modeRaw) ? modeRaw : undefined;
+        const files = Array.isArray(input['files']) ? input['files'] : [];
+        const bundleId = typeof input['bundleId'] === 'string' ? input['bundleId'] : undefined;
+        const sessionId = typeof input['sessionId'] === 'string' ? input['sessionId'] : undefined;
+        const maxTokens = typeof input['maxTokens'] === 'number' ? input['maxTokens'] : undefined;
+        const chunked = input['chunked'] === true;
+        const sectionBudgets = typeof input['sectionBudgets'] === 'object' && input['sectionBudgets'] !== null
+            ? input['sectionBudgets']
+            : undefined;
+        const brief = await buildAgentBrief(ctx.inspection, {
+            ...(task ? { task } : {}),
+            ...(mode ? { mode } : {}),
+            files,
+            ...(bundleId ? { bundleId } : {}),
+            ...(sessionId ? { sessionId } : {}),
+            ...(maxTokens ? { maxTokens } : {}),
+            ...(chunked ? { chunked: true } : {}),
+            ...(sectionBudgets ? { sectionBudgets } : {}),
+        });
+        return { data: brief };
+    },
+};

package/dist/tools/all-tools.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const ALL_TOOLS: readonly IToolDefinition[];
+//# sourceMappingURL=all-tools.d.ts.map

package/dist/tools/all-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAmTpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EA6P9C,CAAC"}