@workit-dev/mcp 0.0.1 → 1.0.0

package/package.json

@@ -1,10 +1,53 @@
 {
   "name": "@workit-dev/mcp",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @workit-dev/mcp",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Workit shared MCP transport for the eight task and policy operation families",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "agentic-coding",
+    "ai-agents",
+    "mcp",
+    "model-context-protocol",
+    "server",
+    "workflow"
+  ],
+  "homepage": "https://github.com/BrainerVirus/workit#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrainerVirus/workit.git",
+    "directory": "packages/workit-mcp"
+  },
+  "bin": {
+    "workit-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "scripts/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*.ts": "./src/*.ts",
+    "./src/*": "./src/*.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "@workit-dev/core": "^1.0.0",
+    "zod": "4.6.5"
+  },
+  "engines": {
+    "node": ">=24"
+  }
 }

package/scripts/build.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+import { mkdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const target = process.argv[2] ? path.resolve(process.argv[2]) : packageDir;
+const dist = path.join(target, "dist");
+rmSync(dist, { recursive: true, force: true });
+mkdirSync(dist, { recursive: true });
+
+const build = spawnSync(
+  process.execPath,
+  [
+    "build",
+    path.join(packageDir, "src/index.ts"),
+    "--outfile",
+    path.join(dist, "index.js"),
+    "--target",
+    "node",
+    "--format",
+    "esm",
+    "--banner",
+    "#!/usr/bin/env node",
+  ],
+  { encoding: "utf8" },
+);
+if (build.status !== 0) {
+  process.stderr.write(build.stderr || build.stdout || "MCP build failed\n");
+  process.exit(1);
+}
+console.log(`mcp: built dist/index.js (${target})`);

package/src/index.ts

@@ -0,0 +1,29 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { assertMcpHost, runStdioServer, sanitizeTransportText } from "./server";
+
+export {
+  assertMcpHost,
+  createMcpServer,
+  McpCapabilityUnavailableError,
+  runStdioServer,
+  sanitizeTransportText,
+  type McpHost,
+  type NativeContextProvider,
+} from "./server";
+
+const main = async (): Promise<void> => {
+  const args = process.argv.slice(2);
+  const hostIndex = args.indexOf("--host");
+  const host = hostIndex >= 0 ? args[hostIndex + 1] : undefined;
+  try {
+    assertMcpHost(host);
+    await runStdioServer(host);
+  } catch (error) {
+    process.stderr.write(`${sanitizeTransportText(error)}\n`);
+    process.exitCode = 2;
+  }
+};
+
+const entryPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (entryPath === path.resolve(fileURLToPath(import.meta.url))) await main();

package/src/server.ts

@@ -0,0 +1,421 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+  type CallToolResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { fileURLToPath } from "node:url";
+import {
+  OPERATION_FAMILIES,
+  WorkitCore,
+  TaskStore,
+  flatOperationJsonSchema,
+  operationDescription,
+  parseAdvertisedOperation,
+  type OperationContext,
+} from "@workit-dev/core/src/core";
+import { changedSourcesSinceLoad, markSourcesLoaded } from "@workit-dev/core/src/core/boundary";
+import type { Host, Result } from "@workit-dev/core/src/core/task-contract";
+import { briefInspectResult } from "@workit-dev/core/src/core/task-evaluation";
+import { escalateToolFailure, type FailureMemo } from "@workit-dev/core/src/hooks/repeat-failure";
+import { redactSecrets } from "@workit-dev/core/src/core/logger";
+import { readExternalContext } from "@workit-dev/core/src/core/context-read";
+
+export type McpHost = Extract<Host, "cursor" | "codex_cli" | "codex_desktop">;
+export type NativeContextProvider = { current(): Promise<OperationContext> };
+
+export class McpCapabilityUnavailableError extends Error {
+  readonly capability: string;
+
+  constructor(capability: string) {
+    super(`${capability} unavailable`);
+    this.name = "McpCapabilityUnavailableError";
+    this.capability = capability;
+  }
+}
+
+class McpResourceInputError extends Error {}
+
+const MCP_HOSTS = new Set<McpHost>(["cursor", "codex_cli", "codex_desktop"]);
+const CONTEXT_KINDS = [
+  "git",
+  "pr",
+  "youtrack",
+  "github_issue",
+  "gitlab_issue",
+  "changelog",
+  "release",
+  "affected",
+] as const;
+type ContextKind = (typeof CONTEXT_KINDS)[number];
+const CONTEXT_SELECTORS = ["range", "issueId"] as const;
+const safeCapability = (value: string, allowed: readonly string[]): string =>
+  allowed.includes(value) ? value : "context";
+const TOOL_CAPABILITIES = [...CONTEXT_KINDS, "workspace", "native_caller_identity"];
+const VERSION = (() => {
+  try {
+    const packageJson = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    ) as { version?: unknown };
+    return typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const rootVariants = (workspaceRoot?: string): string[] => {
+  if (!workspaceRoot) return [];
+  const roots = new Set<string>();
+  for (const candidate of [workspaceRoot, path.resolve(workspaceRoot)]) {
+    if (path.isAbsolute(candidate) && candidate !== path.parse(candidate).root)
+      roots.add(candidate);
+  }
+  try {
+    const canonical = realpathSync(workspaceRoot);
+    if (canonical !== path.parse(canonical).root) roots.add(canonical);
+  } catch {
+    // The core will return a structured failure for an unavailable root.
+  }
+  return [...roots].toSorted((left, right) => right.length - left.length);
+};
+
+export const sanitizeTransportText = (value: unknown, workspaceRoot?: string): string => {
+  const message = value instanceof Error ? value.message : String(value);
+  const withoutStack = message.split(/\r?\n/, 1)[0].replace(/\s+(?:at|stack:)\s.*$/i, "");
+  const withoutRoot = rootVariants(workspaceRoot).reduce(
+    (current, root) => current.split(root).join("[WORKSPACE_ROOT]"),
+    withoutStack,
+  );
+  return redactSecrets(withoutRoot).slice(0, 500);
+};
+
+const reportError = (tool: string, error: unknown, workspaceRoot?: string): void => {
+  try {
+    process.stderr.write(
+      `${JSON.stringify({ level: "error", message: "MCP tool failed", tool, error: sanitizeTransportText(error, workspaceRoot) })}\n`,
+    );
+  } catch {
+    // Diagnostics must never break the protocol response.
+  }
+};
+
+export function assertMcpHost(host: unknown): asserts host is McpHost {
+  if (typeof host !== "string" || !MCP_HOSTS.has(host as McpHost)) {
+    throw new Error("MCP host must be cursor, codex_cli, or codex_desktop");
+  }
+}
+
+const READ_ONLY_ACTIONS = new Set(["list", "inspect", "preview", "explain", "export"]);
+const requiresCallerIdentity = (input: unknown): boolean =>
+  typeof input !== "object" ||
+  input === null ||
+  !READ_ONLY_ACTIONS.has(String((input as { action?: unknown }).action));
+
+/** Attested callers (host sessions that can mutate) see every action;
+ * unattested MCP callers see only read-only actions, and families with no
+ * read-only action are not advertised as callable tools at all. Schemas are
+ * flat (depth 1): no provider needs a nesting projection. */
+export const advertisedToolSchemas = (
+  attested: boolean,
+): { name: string; description: string; inputSchema: Record<string, unknown> }[] =>
+  OPERATION_FAMILIES.flatMap((family) => {
+    const schema = flatOperationJsonSchema(family, { readOnly: !attested });
+    if (!schema) return [];
+    return [
+      {
+        name: `workit_${family}`,
+        description: attested
+          ? operationDescription(family)
+          : `${operationDescription(family)} Unattested MCP callers can only run read-only actions; mutating operations require an attested host session.`,
+        inputSchema: schema,
+      },
+    ];
+  });
+
+const sanitizeFailure = (result: Result<unknown>, workspaceRoot?: string): Result<unknown> => {
+  if (result.ok) return result;
+  const sanitize = (value: unknown): unknown => {
+    if (typeof value === "string") return sanitizeTransportText(value, workspaceRoot);
+    if (Array.isArray(value)) return value.map(sanitize);
+    if (value !== null && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitize(item)]));
+    }
+    return value;
+  };
+  return sanitize(result) as Result<unknown>;
+};
+
+const resultForClient = (
+  result: Result<unknown>,
+  workspaceRoot?: string,
+  escalate: (safe: Result<unknown>) => Result<unknown> = (safe) => safe,
+): CallToolResult => {
+  // Escalate after sanitizing: the transport keeps one line of an error.
+  const safe = escalate(sanitizeFailure(result, workspaceRoot));
+  return {
+    content: [{ type: "text", text: JSON.stringify(safe) }],
+    structuredContent: safe,
+    ...(safe.ok ? {} : { isError: true }),
+  };
+};
+
+const thrownResult = (tool: string, error: unknown, workspaceRoot?: string): CallToolResult => {
+  reportError(tool, error, workspaceRoot);
+  if (error instanceof McpCapabilityUnavailableError) {
+    const capability = safeCapability(error.capability, TOOL_CAPABILITIES);
+    return resultForClient(
+      {
+        ok: false,
+        schemaVersion: 1,
+        code: "capability_unavailable",
+        error: `${capability} unavailable`,
+        details: { capability },
+      },
+      workspaceRoot,
+    );
+  }
+  const result = {
+    ok: false as const,
+    schemaVersion: 1 as const,
+    code: "storage_error" as const,
+    error: "MCP operation failed",
+    details: {},
+  };
+  return resultForClient(result, workspaceRoot);
+};
+
+export function createMcpServer(host: McpHost, contextProvider: NativeContextProvider): Server {
+  assertMcpHost(host);
+  // Long-lived MCP servers load core once; warn once (never block) when the
+  // checkout sources move underneath, mirroring the OpenCode plugin guard.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const sourceMarker = markSourcesLoaded(
+    [
+      path.join(here, "server.ts"),
+      path.join(here, "..", "..", "workit-core", "src", "core", "task-contract.ts"),
+      path.join(here, "..", "..", "workit-core", "src", "core", "task-engine.ts"),
+    ].filter((file) => existsSync(file)),
+  );
+  let staleWarned = false;
+  // Per process: one MCP server serves one host session.
+  const failures: FailureMemo = new Map();
+  const server = new Server(
+    { name: "workit", version: VERSION },
+    { capabilities: { tools: {}, resources: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    let attested = false;
+    try {
+      const context = await contextProvider.current();
+      attested = context.callerAttested === true;
+    } catch {
+      attested = false;
+    }
+    return { tools: advertisedToolSchemas(attested) };
+  });
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: CONTEXT_KINDS.map((kind) => ({
+      uri: `workit://context/${kind}`,
+      name: `Workit ${kind} context`,
+      description: "Read-only context derived from the host-owned workspace.",
+      mimeType: "application/json",
+    })),
+  }));
+
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: [
+      {
+        uriTemplate: "workit://context/{kind}{?range,issueId}",
+        name: "Workit context",
+        description: "Read-only context; workspace and caller come from the host session.",
+        mimeType: "application/json",
+      },
+    ],
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    let workspaceRoot: string | undefined;
+    try {
+      const context = await contextProvider.current();
+      workspaceRoot = context.root;
+      if (context.caller.host !== host)
+        throw new Error("native context host does not match MCP host");
+      const parsed = new URL(request.params.uri);
+      if (parsed.protocol !== "workit:" || parsed.hostname !== "context")
+        throw new McpResourceInputError("unsupported Workit context URI");
+      const kind = parsed.pathname.replace(/^\//, "") as ContextKind;
+      if (!CONTEXT_KINDS.includes(kind))
+        throw new McpResourceInputError("unsupported Workit context kind");
+      for (const key of parsed.searchParams.keys())
+        if (!CONTEXT_SELECTORS.includes(key as (typeof CONTEXT_SELECTORS)[number]))
+          throw new McpResourceInputError("unsupported Workit context selector");
+      const result = await readExternalContext(context.root, {
+        kind,
+        ...(parsed.searchParams.get("range") ? { range: parsed.searchParams.get("range")! } : {}),
+        ...(parsed.searchParams.get("issueId")
+          ? { issueId: parsed.searchParams.get("issueId")! }
+          : {}),
+      });
+      if (!result.ok) throw new McpCapabilityUnavailableError(result.details.capability ?? kind);
+      return {
+        contents: [
+          {
+            uri: request.params.uri,
+            mimeType: "application/json",
+            text: JSON.stringify(result.data),
+          },
+        ],
+      };
+    } catch (error) {
+      reportError("context.read", error, workspaceRoot);
+      const capability =
+        error instanceof McpCapabilityUnavailableError
+          ? safeCapability(error.capability, CONTEXT_KINDS)
+          : "context";
+      const safe =
+        error instanceof McpCapabilityUnavailableError
+          ? {
+              ok: false,
+              schemaVersion: 1,
+              code: "capability_unavailable",
+              error: `${capability} unavailable`,
+              details: { capability },
+            }
+          : error instanceof McpResourceInputError
+            ? {
+                ok: false,
+                schemaVersion: 1,
+                code: "invalid_input",
+                error: "invalid context resource request",
+                details: {},
+              }
+            : {
+                ok: false,
+                schemaVersion: 1,
+                code: "storage_error",
+                error: "MCP operation failed",
+                details: {},
+              };
+      return {
+        contents: [
+          { uri: request.params.uri, mimeType: "application/json", text: JSON.stringify(safe) },
+        ],
+      };
+    }
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (!staleWarned && changedSourcesSinceLoad(sourceMarker).length > 0) {
+      staleWarned = true;
+      try {
+        process.stderr.write(
+          `${JSON.stringify({ level: "warn", message: "workit sources changed after MCP load; restart the server for latest behavior" })}\n`,
+        );
+      } catch {
+        // Diagnostics must never break the protocol response.
+      }
+    }
+    const toolName = request.params.name;
+    let workspaceRoot: string | undefined;
+    try {
+      const family = OPERATION_FAMILIES.find((candidate) => toolName === `workit_${candidate}`);
+      if (!family) {
+        return resultForClient({
+          ok: false,
+          schemaVersion: 1,
+          code: "invalid_input",
+          error: sanitizeTransportText(`Unknown Workit tool: ${toolName}`),
+          details: { fields: [{ path: "name", reason: "unknown operation family" }] },
+        });
+      }
+
+      const context = await contextProvider.current();
+      workspaceRoot = context.root;
+      if (context.caller.host !== host) {
+        return resultForClient(
+          {
+            ok: false,
+            schemaVersion: 1,
+            code: "invalid_input",
+            error: "native context host does not match MCP host",
+            details: { operation: family },
+          },
+          workspaceRoot,
+        );
+      }
+      const escalate = (safe: Result<unknown>) =>
+        escalateToolFailure(
+          failures,
+          context.caller.actor || "mcp",
+          toolName,
+          request.params.arguments,
+          safe,
+        );
+      const parsed = parseAdvertisedOperation(family, request.params.arguments, host);
+      if (!parsed.ok) return resultForClient(parsed, workspaceRoot, escalate);
+      if (context.callerAttested !== true && requiresCallerIdentity(parsed.data))
+        return resultForClient(
+          {
+            ok: false,
+            schemaVersion: 1,
+            code: "capability_unavailable",
+            error:
+              "native caller identity is unavailable; run the workit CLI for mutations: node_modules/.bin/workit <family> <action> --json",
+            details: { capability: "native_caller_identity", operation: family },
+          },
+          workspaceRoot,
+        );
+
+      const core = new WorkitCore(new TaskStore(context.root), context);
+      const run = core[family] as unknown as (input: unknown) => Result<unknown>;
+      const result = run.call(core, parsed.data);
+      return resultForClient(
+        family === "task" && context.callerAttested !== true
+          ? briefInspectResult(parsed.data, result)
+          : result,
+        workspaceRoot,
+        escalate,
+      );
+    } catch (error) {
+      return thrownResult(toolName, error, workspaceRoot);
+    }
+  });
+
+  return server;
+}
+
+const defaultContextProvider = (host: McpHost): NativeContextProvider => {
+  const root = process.env.WORKIT_WORKSPACE_ROOT ?? process.cwd();
+  // Not WORKIT_SESSION_ID: every agent shell inherits that one, so a server
+  // started from a shell would claim an attested caller. Only a host launcher
+  // that attests the caller sets this.
+  const actor = process.env.WORKIT_MCP_CALLER_SESSION ?? "";
+  return {
+    current: async () => ({
+      root,
+      caller: { host, actor },
+      callerAttested: actor !== "",
+      capabilities: [],
+      constraints: [],
+      now: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    }),
+  };
+};
+
+export async function runStdioServer(
+  host: McpHost,
+  contextProvider: NativeContextProvider = defaultContextProvider(host),
+): Promise<Server> {
+  assertMcpHost(host);
+  const server = createMcpServer(host, contextProvider);
+  await server.connect(new StdioServerTransport());
+  return server;
+}