@engineeros/connector 0.8.1 → 0.8.3

package/README.md

@@ -49,6 +49,8 @@ Credentials are stored per workspace under `~/.engineeros/connectors` with owner
 
 Keep the connector online to receive Goals assigned from EngineerOS. Each Goal runs in an isolated worktree below `~/.engineeros/runs`. Cancellation stops Codex. The connector returns changed paths, a bounded diff, and the exact repository ZIP; a human still performs independent attestation.
 
+During the writable implementation phase, Codex receives an authenticated EngineerOS MCP server automatically. It can list, read, create, update, reclassify, and soft-delete project artifacts through the same repository boundary used by Copilot. The backend accepts those calls only while the assigned Goal is running. Read-only project prompts and the independent verification phase do not receive mutation tools.
+
 Requirements: Node.js 22 or newer, Git, and an authenticated Codex CLI (`codex login`).
 
 ## Execution profiles

package/bin/engineeros-connector.mjs

@@ -24,8 +24,26 @@ import {
   startConnectionWatchdog,
 } from "../src/connection.mjs";
 import { advertisedCapabilities } from "../src/capabilities.mjs";
+import { parseConnectorArgs } from "../src/cli-args.mjs";
+import { runMcpServer } from "../src/mcp-server.mjs";
+import packageJson from "../package.json" with { type: "json" };
 
-const { command, positional, flags } = parseArgs(process.argv.slice(2));
+const { command, positional, flags } = parseConnectorArgs(process.argv.slice(2));
+
+if (command === "mcp") {
+  const config = await loadConfig(flags.workspace || process.cwd());
+  if (!config) fail("This workspace is not paired with EngineerOS.");
+  const runId = flags["run-id"] || positional[0];
+  if (!runId) fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
+  await runMcpServer({
+    config,
+    runId,
+    version: packageJson.version,
+    input: process.stdin,
+    output: process.stdout,
+  });
+  process.exit(0);
+}
 
 if (command === "status") {
   const config = await loadConfig(flags.workspace || process.cwd());
@@ -79,7 +97,7 @@ if (command === "pair") {
     token: config.token,
   };
 } else {
-  fail("Use `engineeros-connector pair`, `start`, or `status`.");
+  fail("Use `engineeros-connector pair`, `start`, `status`, or `mcp`.");
 }
 
 let codingAgent;
@@ -566,19 +584,6 @@ async function execute(assignment) {
   }
 }
 
-function parseArgs(args) {
-  const command = args.shift();
-  const positional = [];
-  const flags = {};
-  while (args.length) {
-    const value = args.shift();
-    if (!value.startsWith("--")) positional.push(value);
-    else if (value === "--onboard") flags.onboard = true;
-    else flags[value.slice(2)] = args.shift();
-  }
-  return { command, positional, flags };
-}
-
 function parseAgentArgs(value) {
   if (!value) return [];
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",
@@ -16,7 +16,7 @@
   "scripts": {
     "start": "node ./bin/engineeros-connector.mjs",
     "test": "node --test --test-concurrency=1",
-    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/capabilities.mjs && node --check ./src/connection.mjs && node --check ./src/runner.mjs"
+    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/capabilities.mjs && node --check ./src/cli-args.mjs && node --check ./src/connection.mjs && node --check ./src/mcp-server.mjs && node --check ./src/runner.mjs"
   },
   "engines": {
     "node": ">=22"

package/src/cli-args.mjs

@@ -0,0 +1,18 @@
+const BOOLEAN_FLAGS = new Set(["onboard", "skip-git-repo-check"]);
+
+export function parseConnectorArgs(argv) {
+  const args = [...argv];
+  const command = args.shift();
+  const positional = [];
+  const flags = {};
+  while (args.length) {
+    const value = args.shift();
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const name = value.slice(2);
+    flags[name] = BOOLEAN_FLAGS.has(name) ? true : args.shift();
+  }
+  return { command, positional, flags };
+}

package/src/config.mjs

@@ -45,6 +45,13 @@ export function assessmentResultUrl(websocketUrl, connectorId, assessmentId) {
   return url.toString();
 }
 
+export function artifactToolUrl(websocketUrl, connectorId) {
+  const url = new URL(websocketUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.pathname = `/api/v1/agent-connectors/${connectorId}/artifact-tools`;
+  return url.toString();
+}
+
 export async function loadConfig(workspace = process.cwd()) {
   try {
     return JSON.parse(await readFile(configPath(workspace), "utf8"));

package/src/mcp-server.mjs

@@ -0,0 +1,241 @@
+import readline from "node:readline";
+
+import { artifactToolUrl } from "./config.mjs";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+const ARTIFACT_TYPES = [
+  "vision",
+  "problem",
+  "capability",
+  "epic",
+  "feature",
+  "story",
+  "architecture",
+  "service",
+  "api",
+  "data_model",
+  "event",
+  "task",
+  "release",
+  "risk",
+  "pattern",
+  "technology",
+  "agent",
+  "workflow",
+  "review",
+  "comment",
+];
+
+const artifactTypeSchema = { type: "string", enum: ARTIFACT_TYPES };
+const artifactIdSchema = {
+  type: "string",
+  format: "uuid",
+  description: "The saved EngineerOS artifact ID.",
+};
+
+export const artifactTools = [
+  {
+    name: "engineeros_list_artifacts",
+    description: "List saved artifacts in the current EngineerOS project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_type: artifactTypeSchema,
+        status: { type: "string", enum: ["draft", "active", "archived"] },
+        page: { type: "integer", minimum: 1 },
+        page_size: { type: "integer", minimum: 1, maximum: 50 },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false },
+  },
+  {
+    name: "engineeros_get_artifact",
+    description: "Load one saved artifact from the current EngineerOS project.",
+    inputSchema: {
+      type: "object",
+      properties: { artifact_id: artifactIdSchema },
+      required: ["artifact_id"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false },
+  },
+  {
+    name: "engineeros_create_artifact",
+    description:
+      "Create a saved EngineerOS artifact during the currently approved writable Goal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_type: artifactTypeSchema,
+        name: { type: "string", minLength: 1, maxLength: 500 },
+        content: {
+          type: "string",
+          minLength: 1,
+          description: "Complete artifact content as structured Markdown.",
+        },
+        metadata_info: { type: "object" },
+      },
+      required: ["artifact_type", "name", "content"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+  },
+  {
+    name: "engineeros_update_artifact",
+    description:
+      "Update a saved EngineerOS artifact during the currently approved writable Goal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: artifactIdSchema,
+        artifact_type: artifactTypeSchema,
+        name: { type: "string", minLength: 1, maxLength: 500 },
+        content: {
+          type: "string",
+          minLength: 1,
+          description: "Complete replacement content as structured Markdown.",
+        },
+        metadata_info: { type: "object" },
+      },
+      required: ["artifact_id"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+  },
+  {
+    name: "engineeros_reclassify_artifact",
+    description:
+      "Move a saved artifact to another EngineerOS classification during the currently approved writable Goal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: artifactIdSchema,
+        target_artifact_type: artifactTypeSchema,
+      },
+      required: ["artifact_id", "target_artifact_type"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+  },
+  {
+    name: "engineeros_delete_artifact",
+    description:
+      "Soft-delete a saved EngineerOS artifact during the currently approved writable Goal.",
+    inputSchema: {
+      type: "object",
+      properties: { artifact_id: artifactIdSchema },
+      required: ["artifact_id"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true },
+  },
+];
+
+const toolNames = new Map(
+  artifactTools.map((tool) => [tool.name, tool.name.replace("engineeros_", "")]),
+);
+
+export async function handleMcpRequest(message, context) {
+  if (message.method === "notifications/initialized") return null;
+  if (message.method === "initialize") {
+    return success(message.id, {
+      protocolVersion: message.params?.protocolVersion || PROTOCOL_VERSION,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: "engineeros-connector", version: context.version },
+    });
+  }
+  if (message.method === "ping") return success(message.id, {});
+  if (message.method === "tools/list") {
+    return success(message.id, { tools: artifactTools });
+  }
+  if (message.method === "tools/call") {
+    const tool = toolNames.get(message.params?.name);
+    if (!tool) return failure(message.id, -32602, "Unknown EngineerOS artifact tool.");
+    try {
+      const response = await callArtifactTool(context, tool, message.params?.arguments || {});
+      return success(message.id, {
+        content: [{ type: "text", text: renderArtifactToolResult(response) }],
+        isError: false,
+      });
+    } catch (error) {
+      return success(message.id, {
+        content: [
+          {
+            type: "text",
+            text: `# EngineerOS artifact tool failed\n\n${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      });
+    }
+  }
+  return failure(message.id, -32601, `Unsupported MCP method: ${message.method}`);
+}
+
+export async function runMcpServer({ config, runId, version, input, output, fetchImpl = fetch }) {
+  const context = { config, runId, version, fetchImpl };
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let response;
+    try {
+      response = await handleMcpRequest(JSON.parse(line), context);
+    } catch (error) {
+      response = failure(null, -32700, error instanceof Error ? error.message : String(error));
+    }
+    if (response) output.write(`${JSON.stringify(response)}\n`);
+  }
+}
+
+async function callArtifactTool(context, tool, arguments_) {
+  const response = await context.fetchImpl(
+    artifactToolUrl(context.config.server_url, context.config.connector_id),
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${context.config.token}`,
+      },
+      body: JSON.stringify({ run_id: context.runId, tool, arguments: arguments_ }),
+    },
+  );
+  if (!response.ok) {
+    const detail = await response.text();
+    throw new Error(`EngineerOS rejected ${tool} (${response.status}): ${detail}`);
+  }
+  return response.json();
+}
+
+function renderArtifactToolResult(result) {
+  const lines = ["# EngineerOS artifact tool result", "", result.message || "Completed."];
+  if (result.artifact) lines.push("", ...artifactMarkdown(result.artifact));
+  if (Array.isArray(result.artifacts)) {
+    lines.push("", `## Artifacts (${result.total ?? result.artifacts.length})`, "");
+    for (const artifact of result.artifacts) {
+      lines.push(`- **${artifact.name}** — \`${artifact.artifact_type}\` — \`${artifact.id}\``);
+    }
+  }
+  return lines.join("\n");
+}
+
+function artifactMarkdown(artifact) {
+  return [
+    `## ${artifact.name}`,
+    "",
+    `- ID: \`${artifact.id}\``,
+    `- Type: \`${artifact.artifact_type}\``,
+    `- Status: \`${artifact.status}\``,
+    "",
+    artifact.content || "",
+  ];
+}
+
+function success(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function failure(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}

package/src/runner.mjs

@@ -102,6 +102,8 @@ export async function executeAssignment(assignment, config, callbacks) {
     config,
     callbacks,
     execution.profile,
+    undefined,
+    { runId: assignment.run_id },
   );
   callbacks.onProcess?.(controller.child);
   await controller.completed;
@@ -756,6 +758,7 @@ function launchCodexProcess(
   profile = {},
   previousSessionId,
   skipGitRepoCheck = false,
+  mcpServer,
 ) {
   const command =
     process.env.CODEX_BIN ||
@@ -766,6 +769,7 @@ function launchCodexProcess(
     profile,
     previousSessionId,
     skipGitRepoCheck,
+    mcpServer,
   });
   const child = spawn(command, args, {
     cwd: workspace,
@@ -832,6 +836,7 @@ export function codexExecutionArgs({
   profile = {},
   previousSessionId,
   skipGitRepoCheck = false,
+  mcpServer,
 }) {
   const optionArgs = ["--json"];
   if (skipGitRepoCheck) optionArgs.push("--skip-git-repo-check");
@@ -842,6 +847,21 @@ export function codexExecutionArgs({
       `model_reasoning_effort=${JSON.stringify(profile.reasoning_effort)}`,
     );
   }
+  if (mcpServer) {
+    optionArgs.push(
+      "--config",
+      `mcp_servers.engineeros.command=${JSON.stringify(process.execPath)}`,
+      "--config",
+      `mcp_servers.engineeros.args=${JSON.stringify([
+        mcpServer.connectorBin,
+        "mcp",
+        "--workspace",
+        mcpServer.workspace,
+        "--run-id",
+        mcpServer.runId,
+      ])}`,
+    );
+  }
   return previousSessionId
     ? ["exec", "resume", ...optionArgs, previousSessionId, "-"]
     : ["exec", ...optionArgs, "--sandbox", sandbox, "-C", workspace, "-"];
@@ -855,6 +875,7 @@ function launchAgentProcess(
   callbacks,
   profile = {},
   previousSessionId,
+  mcpContext,
 ) {
   if (config.agent_protocol === "acp") {
     if (profile.model || profile.reasoning_effort) {
@@ -872,6 +893,13 @@ function launchAgentProcess(
     profile,
     previousSessionId,
     config.skip_git_repo_check === true,
+    mcpContext
+      ? {
+          connectorBin: process.argv[1],
+          workspace: config.workspace,
+          runId: mcpContext.runId,
+        }
+      : undefined,
   );
 }