overseer-mcp 0.1.1

package/dist/tools/getPlan.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { withRepoRoot } from "../config.js";
+import { buildGetPlanUserPayload, GET_PLAN_FULL_SYSTEM_PROMPT, GET_PLAN_LITE_SYSTEM_PROMPT } from "../prompts.js";
+import { readFiles } from "../repo/files.js";
+import { gitStatus, gitTrackedFileList, gitTrackedFiles } from "../repo/git.js";
+import { extractTerms, outlineFile, selectRelevantFiles } from "../repo/retrieve.js";
+import { errorResult, LITE_PLAN_MAX_TOKENS, PLAN_MAX_TOKENS, TEMPERATURE, textResult } from "./shared.js";
+export const getPlanInputSchema = {
+    task: z.string().min(1).describe("The user's request, verbatim."),
+    notes: z
+        .string()
+        .optional()
+        .describe("Optional: the executor's own summary or hypothesis of what/where the change is."),
+    file_summaries: z
+        .string()
+        .optional()
+        .describe("Executor-provided summaries of relevant files. When provided, the server skips reading files from disk and forwards these summaries directly to the expert. Use this to save tokens and let the executor control what context the expert sees."),
+    focus_paths: z.array(z.string()).optional().describe("Optional seed files the executor suspects are relevant."),
+    repo_root: z.string().optional().describe("Absolute path to the project root. Overrides the server default."),
+    mode: z.enum(["lite", "full"]).optional().default("full").describe("Use full for a complete contract, lite for a shorter orientation."),
+};
+export async function handleGetPlan(input, config) {
+    try {
+        const mode = input.mode ?? "full";
+        const effective = input.repo_root ? withRepoRoot(config, input.repo_root) : config;
+        const [status, repoMap] = await Promise.all([
+            gitStatus(effective.repoRoot),
+            gitTrackedFiles(effective.repoRoot, 400),
+        ]);
+        let snapshots = [];
+        let outlines = [];
+        let autoSelected = [];
+        if (input.file_summaries) {
+            // Summary mode: executor provides its own file analysis.
+            // Server skips disk reads and forwards summaries directly.
+        }
+        else {
+            // Disk-read mode: server selects and reads files from disk.
+            const focus = (input.focus_paths ?? []).slice(0, effective.maxFiles);
+            const tracked = await gitTrackedFileList(effective.repoRoot, 2000);
+            const terms = extractTerms(`${input.task} ${input.notes ?? ""}`);
+            const remaining = effective.maxFiles - focus.length;
+            const relevant = remaining > 0
+                ? await selectRelevantFiles(effective.repoRoot, tracked, terms, new Set(focus), remaining)
+                : [];
+            const candidates = [...focus, ...relevant];
+            const fullCount = effective.planFullFiles ?? 0;
+            const fullPaths = candidates.slice(0, fullCount);
+            const outlinePaths = candidates.slice(fullCount);
+            const [fullSnapshots, outlineSources] = await Promise.all([
+                readFiles(effective.repoRoot, fullPaths, effective.maxFileBytes),
+                readFiles(effective.repoRoot, outlinePaths, effective.maxFileBytes),
+            ]);
+            snapshots = fullSnapshots;
+            outlines = outlineSources.map((file) => ({
+                path: file.path,
+                outline: file.error ? `(could not read: ${file.error})` : outlineFile(file.content ?? ""),
+            }));
+            autoSelected = fullPaths.filter((p) => relevant.includes(p));
+        }
+        const user = buildGetPlanUserPayload({
+            task: input.task,
+            notes: input.notes,
+            gitStatus: status,
+            repoMap,
+            snapshots,
+            autoSelected,
+            outlines,
+            fileSummaries: input.file_summaries,
+        });
+        const text = await effective.provider.complete({
+            system: mode === "lite" ? GET_PLAN_LITE_SYSTEM_PROMPT : GET_PLAN_FULL_SYSTEM_PROMPT,
+            user,
+            maxTokens: mode === "lite" ? LITE_PLAN_MAX_TOKENS : PLAN_MAX_TOKENS,
+            temperature: TEMPERATURE,
+        });
+        return textResult(text);
+    }
+    catch (err) {
+        return errorResult("get_plan", err);
+    }
+}

package/dist/tools/requestReview.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { withRepoRoot } from "../config.js";
+import { buildRequestReviewUserPayload, renderTestResult, REQUEST_REVIEW_SYSTEM_PROMPT } from "../prompts.js";
+import { gitDiff, gitDiffStaged } from "../repo/git.js";
+import { runTests } from "../repo/tests.js";
+import { errorResult, REVIEW_MAX_TOKENS, TEMPERATURE, textResult, truncateBytes } from "./shared.js";
+export const requestReviewInputSchema = {
+    task: z.string().optional().describe("Original task for reference."),
+    diff_summary: z.string().optional().describe("Executor-provided summary of changes made. When provided, the server skips running git diff."),
+    test_output_summary: z.string().optional().describe("Executor-provided summary of test/validation results. When provided, the server skips running the test command."),
+    repo_root: z.string().optional().describe("Absolute path to the project root. Overrides the server default."),
+    run_tests: z.boolean().optional().default(true).describe("Run OVERSEER_TEST_COMMAND when configured. Ignored when test_output_summary is provided."),
+};
+async function getTestOutput(input, config) {
+    if (input.run_tests === false) {
+        return "(not run: run_tests was false)";
+    }
+    if (!config.testCommand) {
+        return "(not run: OVERSEER_TEST_COMMAND is not set)";
+    }
+    return renderTestResult(await runTests(config.repoRoot, config.testCommand, config.testTimeoutMs));
+}
+export async function handleRequestReview(input, config) {
+    try {
+        const effective = input.repo_root ? withRepoRoot(config, input.repo_root) : config;
+        const diff = input.diff_summary ? "" : await gitDiff(effective.repoRoot);
+        const stagedDiff = input.diff_summary ? "" : await gitDiffStaged(effective.repoRoot);
+        const testOutput = input.test_output_summary ? "" : await getTestOutput(input, effective);
+        const user = buildRequestReviewUserPayload({
+            task: input.task,
+            gitDiff: diff ? truncateBytes(diff, effective.maxDiffBytes) : "",
+            gitDiffStaged: stagedDiff ? truncateBytes(stagedDiff, effective.maxDiffBytes) : "",
+            testOutput,
+            diffSummary: input.diff_summary,
+            testOutputSummary: input.test_output_summary,
+        });
+        const text = await effective.provider.complete({
+            system: REQUEST_REVIEW_SYSTEM_PROMPT,
+            user,
+            maxTokens: REVIEW_MAX_TOKENS,
+            temperature: TEMPERATURE,
+        });
+        return textResult(text);
+    }
+    catch (err) {
+        return errorResult("request_review", err);
+    }
+}

package/dist/tools/shared.js

@@ -0,0 +1,35 @@
+import { readFiles } from "../repo/files.js";
+export const CONSULT_MAX_TOKENS = 1500;
+export const PLAN_MAX_TOKENS = 2500;
+export const LITE_PLAN_MAX_TOKENS = 1500;
+export const REVIEW_MAX_TOKENS = 2500;
+export const TEMPERATURE = 0.2;
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function errorResult(toolName, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: "text", text: `${toolName} failed: ${message}` }],
+        isError: true,
+    };
+}
+export async function readCappedFiles(config, paths) {
+    const filePaths = paths ?? [];
+    const selected = filePaths.slice(0, config.maxFiles);
+    const snapshots = await readFiles(config.repoRoot, selected, config.maxFileBytes);
+    if (filePaths.length > selected.length) {
+        snapshots.push({
+            path: "(omitted files)",
+            error: `${filePaths.length - selected.length} file(s) omitted by OVERSEER_MAX_FILES=${config.maxFiles}`,
+        });
+    }
+    return snapshots;
+}
+export function truncateBytes(text, maxBytes) {
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes <= maxBytes)
+        return text;
+    const head = Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+    return `${head}\n... (truncated at ${maxBytes} bytes; content is ${bytes} bytes)`;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "overseer-mcp",
+  "version": "0.1.1",
+  "description": "An MCP server that lets a cheaper executor agent consult a more capable expert model at the three moments it tends to derail: planning, mid-implementation decisions, and final review. The expert reads ground truth (git + disk), never the executor's summary.",
+  "type": "module",
+  "bin": {
+    "overseer-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example",
+    "configure-overseer.bat"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agents",
+    "multi-agent",
+    "llm",
+    "orchestration",
+    "code-review"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.4"
+  }
+}