@executioncontrolprotocol/mcp 0.10.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@executioncontrolprotocol/mcp",
+  "version": "0.10.0",
+  "description": "MCP server adapter for ECP environments",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "peerDependencies": {
+    "@executioncontrolprotocol/core": "^0.10.0",
+    "@executioncontrolprotocol/types": "^0.10.0",
+    "zod": "^3.24.0"
+  },
+  "dependencies": {
+    "@executioncontrolprotocol/node": "0.10.0",
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@executioncontrolprotocol/core": "0.10.0",
+    "@executioncontrolprotocol/format-toon": "0.10.0",
+    "@executioncontrolprotocol/types": "0.10.0",
+    "typescript": "^5.7.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,436 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+import { z } from "zod"
+import type { Ecp } from "@executioncontrolprotocol/core"
+import type { EcpEncodeInput, RunResult, WorkflowManifest } from "@executioncontrolprotocol/types"
+import { ECP_FORMATS } from "@executioncontrolprotocol/types"
+import { createServer, type Server } from "node:http"
+
+/** Options for MCP server creation. @category MCP */
+export interface CreateEcpMcpServerOptions {
+  /** Initialized operational ECP instance. */
+  ecp: Ecp
+  name?: string
+  version?: string
+}
+
+/** JSON mime type used for ECP MCP resources. */
+const JSON_MIME = "application/json"
+
+/** In-process run store shared across MCP server instances in this process. */
+const runs = new Map<string, RunResult>()
+
+/** Wrap a value as an MCP tool text result. */
+function toolText(value: unknown): { content: { type: "text"; text: string }[] } {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] }
+}
+
+/** Wrap a value as MCP resource JSON contents. */
+function jsonContents(uri: URL, value: unknown) {
+  return {
+    contents: [
+      { uri: uri.href, mimeType: JSON_MIME, text: JSON.stringify(value, null, 2) },
+    ],
+  }
+}
+
+/** Register operational tools on the server. */
+function registerEcpTools(server: McpServer, ecp: Ecp): void {
+  server.tool(
+    "ecp.describe_environment",
+    { query: z.record(z.unknown()).optional() },
+    async ({ query }) => toolText(await ecp.describe(query))
+  )
+
+  server.tool(
+    "ecp.search",
+    { query: z.string(), options: z.record(z.unknown()).optional() },
+    async ({ query, options: searchOpts }) =>
+      toolText(await ecp.search(query, searchOpts as import("@executioncontrolprotocol/types").SearchOptions))
+  )
+
+  server.tool(
+    "ecp.validate_workflow",
+    { workflow: z.record(z.unknown()) },
+    async ({ workflow }) =>
+      toolText(await ecp.validate(workflow as unknown as WorkflowManifest))
+  )
+
+  server.tool(
+    "ecp.run_workflow",
+    {
+      workflow: z.record(z.unknown()),
+      input: z.record(z.unknown()).optional(),
+      dryRun: z.boolean().optional(),
+    },
+    async ({ workflow, input, dryRun }) => {
+      const result = await ecp.run(workflow as unknown as WorkflowManifest, {
+        input,
+        dryRun,
+      })
+      runs.set(result.run.id, result)
+      return toolText(result)
+    }
+  )
+
+  const formatSchema = z.enum(["json", "toon", "fluent"])
+
+  server.tool(
+    "ecp.encode",
+    {
+      source: z.union([z.record(z.unknown()), z.string()]),
+      format: formatSchema.optional(),
+      compact: z.boolean().optional(),
+    },
+    async ({ source, format, compact }) => {
+      let op = ecp.encode(source as EcpEncodeInput["source"])
+      if (format === "toon") op = op.uses("@executioncontrolprotocol/format-toon")
+      else if (format === "fluent") op = op.uses("@executioncontrolprotocol/format-fluent")
+      else op = op.uses("@executioncontrolprotocol/format-json")
+      if (compact) op = op.compact()
+      return toolText(await op.process())
+    }
+  )
+
+  server.tool(
+    "ecp.decode",
+    {
+      content: z.union([z.record(z.unknown()), z.string()]),
+      format: z.enum(["json", "toon"]).optional(),
+      strict: z.boolean().optional(),
+      targetSchema: z.string().optional(),
+    },
+    async ({ content, format, strict, targetSchema }) => {
+      let op = ecp.decode(content)
+      if (format === "toon") op = op.uses("@executioncontrolprotocol/format-toon")
+      else op = op.uses("@executioncontrolprotocol/format-json")
+      if (strict) op = op.strict()
+      if (targetSchema) op = op.to(targetSchema as "@executioncontrolprotocol.workflow")
+      else if (!format || format === ECP_FORMATS.JSON) op = op.to("@executioncontrolprotocol.workflow")
+      return toolText(await op.process())
+    }
+  )
+
+  server.tool("ecp.get_run_status", { runId: z.string() }, async ({ runId }) =>
+    toolText(runs.get(runId) ?? { error: "Run not found", runId })
+  )
+}
+
+/** Register discovery resources on the server. */
+function registerEcpResources(server: McpServer, ecp: Ecp): void {
+  server.registerResource(
+    "environment",
+    "ecp://environment/describe",
+    {
+      title: "Environment descriptor",
+      description: "Full ECP environment descriptor: runtime, extensions, capabilities, policies.",
+      mimeType: JSON_MIME,
+    },
+    async (uri) => jsonContents(uri, await ecp.describe())
+  )
+
+  server.registerResource(
+    "capabilities",
+    "ecp://capabilities",
+    {
+      title: "Capabilities",
+      description: "All capabilities available in this environment.",
+      mimeType: JSON_MIME,
+    },
+    async (uri) => jsonContents(uri, (await ecp.describe()).capabilities)
+  )
+
+  server.registerResource(
+    "policies",
+    "ecp://policies",
+    {
+      title: "Policies",
+      description: "All policies governing this environment.",
+      mimeType: JSON_MIME,
+    },
+    async (uri) => jsonContents(uri, (await ecp.describe()).policies)
+  )
+
+  // Reserved expansion `{+id}` so capability ids containing `/` and `.`
+  // (e.g. `@executioncontrolprotocol/test.echo`) match and round-trip correctly.
+  server.registerResource(
+    "capability",
+    new ResourceTemplate("ecp://capabilities/{+id}", {
+      list: async () => {
+        const descriptor = await ecp.describe()
+        return {
+          resources: descriptor.capabilities.map((c) => ({
+            uri: `ecp://capabilities/${c.id}`,
+            name: c.id,
+            ...(c.label ? { title: c.label } : {}),
+            mimeType: JSON_MIME,
+          })),
+        }
+      },
+    }),
+    {
+      title: "Capability detail",
+      description: "A single capability's schemas and metadata by id.",
+      mimeType: JSON_MIME,
+    },
+    async (uri, variables) => {
+      const id = String(variables.id)
+      const descriptor = await ecp.describe()
+      const capability = descriptor.capabilities.find((c) => c.id === id)
+      return jsonContents(uri, capability ?? { error: "Capability not found", id })
+    }
+  )
+
+  server.registerResource(
+    "run",
+    new ResourceTemplate("ecp://runs/{runId}", {
+      list: async () => ({
+        resources: [...runs.keys()].map((id) => ({
+          uri: `ecp://runs/${id}`,
+          name: id,
+          mimeType: JSON_MIME,
+        })),
+      }),
+    }),
+    {
+      title: "Run detail",
+      description: "Result of a workflow run executed via ecp.run_workflow in this process.",
+      mimeType: JSON_MIME,
+    },
+    async (uri, variables) => {
+      const runId = String(variables.runId)
+      return jsonContents(uri, runs.get(runId) ?? { error: "Run not found", runId })
+    }
+  )
+}
+
+/** Format the environment's capabilities as a bullet list for prompts. */
+function capabilityList(
+  capabilities: { id: string; label?: string }[]
+): string {
+  if (capabilities.length === 0) return "(no capabilities are registered)"
+  return capabilities
+    .map((c) => `- ${c.id}${c.label ? ` — ${c.label}` : ""}`)
+    .join("\n")
+}
+
+/** Register guidance prompts on the server. */
+function registerEcpPrompts(server: McpServer, ecp: Ecp): void {
+  server.registerPrompt(
+    "ecp.author_workflow",
+    {
+      title: "Author an ECP workflow",
+      description: "Guide the agent to build a valid @executioncontrolprotocol.workflow manifest for a goal.",
+      argsSchema: { goal: z.string() },
+    },
+    async ({ goal }) => {
+      const descriptor = await ecp.describe()
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Author an ECP workflow manifest (schema "@executioncontrolprotocol.workflow", version "1.0") for this goal:`,
+                "",
+                goal,
+                "",
+                "Only use capabilities available in this environment:",
+                capabilityList(descriptor.capabilities),
+                "",
+                "Rules:",
+                "- Output a single JSON workflow manifest.",
+                "- Each step's `uses` must be one of the capability ids above.",
+                "- Use `as` to commit a step output to state; reference prior state with { \"$ref\": \"state.<key>\" }.",
+                "- Do not include runtime, extension, policy, or secret configuration.",
+                "Then call ecp.validate_workflow to confirm it is valid before running.",
+              ].join("\n"),
+            },
+          },
+        ],
+      }
+    }
+  )
+
+  server.registerPrompt(
+    "ecp.repair_workflow",
+    {
+      title: "Repair an ECP workflow",
+      description: "Guide the agent to fix a workflow using validation errors.",
+      argsSchema: { workflow: z.string(), errors: z.string().optional() },
+    },
+    ({ workflow, errors }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Fix this ECP workflow manifest so it validates against the environment.",
+              "",
+              "Workflow:",
+              workflow,
+              "",
+              "Validation errors:",
+              errors && errors.trim().length > 0
+                ? errors
+                : "(none provided — call ecp.validate_workflow to obtain them)",
+              "",
+              "Return the corrected JSON workflow manifest only, then re-validate.",
+            ].join("\n"),
+          },
+        },
+      ],
+    })
+  )
+
+  server.registerPrompt(
+    "ecp.explain_environment",
+    {
+      title: "Explain the environment",
+      description: "Summarize the capabilities and policies available in this environment.",
+    },
+    async () => {
+      const descriptor = await ecp.describe()
+      const policies =
+        descriptor.policies.length > 0
+          ? descriptor.policies
+              .map((p) => `- ${p.id}${p.summary ? ` — ${p.summary}` : ""}`)
+              .join("\n")
+          : "(no policies are bound)"
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Explain what this ECP environment ("${descriptor.environment.id}") can do.`,
+                "",
+                "Capabilities:",
+                capabilityList(descriptor.capabilities),
+                "",
+                "Policies:",
+                policies,
+              ].join("\n"),
+            },
+          },
+        ],
+      }
+    }
+  )
+}
+
+/**
+ * Create an MCP server exposing ECP operational APIs as tools, resources, and prompts.
+ * @category MCP
+ */
+export function createEcpMcpServer(options: CreateEcpMcpServerOptions): McpServer {
+  const { ecp } = options
+  const server = new McpServer({
+    name: options.name ?? "ecp",
+    version: options.version ?? "1.0.0",
+  })
+
+  registerEcpTools(server, ecp)
+  registerEcpResources(server, ecp)
+  registerEcpPrompts(server, ecp)
+
+  return server
+}
+
+/** Serve MCP over stdio. @category MCP */
+export async function serveStdio(options: {
+  environment: import("@executioncontrolprotocol/core").Environment
+  name?: string
+  version?: string
+}): Promise<void> {
+  const ecp = await options.environment.init()
+  const server = createEcpMcpServer({ ecp, name: options.name, version: options.version })
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+/** Default MCP endpoint path for {@link serveHttp}. */
+const DEFAULT_MCP_PATH = "/mcp"
+
+/**
+ * Serve MCP over Streamable HTTP.
+ *
+ * Implements the MCP Streamable HTTP transport in stateless mode: each POST to
+ * the MCP endpoint gets a fresh {@link McpServer} + transport bound to the same
+ * initialized {@link Ecp}, avoiding request-id collisions between concurrent
+ * clients. Returns the underlying `http.Server` so callers can close it.
+ *
+ * @category MCP
+ */
+export async function serveHttp(options: {
+  environment: import("@executioncontrolprotocol/core").Environment
+  port?: number
+  path?: string
+  name?: string
+  version?: string
+}): Promise<Server> {
+  const ecp = await options.environment.init()
+  const port = options.port ?? 8787
+  const path = options.path ?? DEFAULT_MCP_PATH
+
+  const httpServer = createServer((req, res) => {
+    void (async () => {
+      const url = req.url ?? ""
+      const pathname = url.split("?")[0]
+      if (pathname !== path) {
+        res.writeHead(404, { "Content-Type": JSON_MIME })
+        res.end(JSON.stringify({ error: "Not found" }))
+        return
+      }
+
+      if (req.method !== "POST") {
+        // Stateless mode: no server-initiated streams, so GET/DELETE are
+        // not supported. Mirror the MCP SDK's stateless guidance.
+        res.writeHead(405, { "Content-Type": JSON_MIME, Allow: "POST" })
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Method not allowed. Use POST." },
+            id: null,
+          })
+        )
+        return
+      }
+
+      const server = createEcpMcpServer({
+        ecp,
+        name: options.name,
+        version: options.version,
+      })
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      })
+      res.on("close", () => {
+        void transport.close()
+        void server.close()
+      })
+      try {
+        await server.connect(transport)
+        await transport.handleRequest(req, res)
+      } catch {
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": JSON_MIME })
+          res.end(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              error: { code: -32603, message: "Internal server error" },
+              id: null,
+            })
+          )
+        }
+      }
+    })()
+  })
+
+  await new Promise<void>((resolve) => httpServer.listen(port, resolve))
+  return httpServer
+}

package/test/integration/mcp-server.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"
+import { createEcpMcpServer } from "../../src/index.js"
+import { extension, workflow, step, registerTestExtension } from "@executioncontrolprotocol/core"
+import { environment } from "@executioncontrolprotocol/node"
+import type { Ecp } from "@executioncontrolprotocol/core"
+
+type TextContent = { type: string; text: string }
+
+/** Parse the first text content block of a tool/resource result as JSON. */
+function parseText(content: TextContent[] | undefined): unknown {
+  const text = content?.find((c) => c.type === "text")?.text
+  if (text === undefined) throw new Error("no text content")
+  return JSON.parse(text)
+}
+
+const echoWorkflow = workflow("Echo")
+  .run([step("@executioncontrolprotocol/test.echo", "Echo").with({ value: "hi" }).as("out")])
+  .toManifest()
+
+describe("@executioncontrolprotocol/mcp wire protocol (Client <-> Server)", () => {
+  let ecp: Ecp
+  let client: Client
+
+  beforeEach(async () => {
+    await registerTestExtension()
+    const env = (await environment("mcp-wire")).withExtensions([
+      extension("@executioncontrolprotocol/test", "Test").with({}),
+    ])
+    ecp = await env.init()
+
+    const server = createEcpMcpServer({ ecp })
+    client = new Client({ name: "test-client", version: "1.0.0" })
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+    await Promise.all([
+      server.connect(serverTransport),
+      client.connect(clientTransport),
+    ])
+  })
+
+  afterEach(async () => {
+    await client.close()
+    await ecp.terminate()
+  })
+
+  it("lists the operational tools", async () => {
+    const { tools } = await client.listTools()
+    const names = tools.map((t) => t.name)
+    expect(names).toEqual(
+      expect.arrayContaining([
+        "ecp.describe_environment",
+        "ecp.search",
+        "ecp.validate_workflow",
+        "ecp.run_workflow",
+        "ecp.encode",
+        "ecp.decode",
+        "ecp.get_run_status",
+      ])
+    )
+  })
+
+  it("describes the environment over the wire", async () => {
+    const res = await client.callTool({ name: "ecp.describe_environment", arguments: {} })
+    const descriptor = parseText(res.content as TextContent[]) as {
+      schema: string
+      capabilities: { id: string }[]
+    }
+    expect(descriptor.schema).toBe("@executioncontrolprotocol.environment.describe")
+    expect(descriptor.capabilities.some((c) => c.id.includes("echo"))).toBe(true)
+  })
+
+  it("validates a workflow over the wire", async () => {
+    const res = await client.callTool({
+      name: "ecp.validate_workflow",
+      arguments: { workflow: echoWorkflow as unknown as Record<string, unknown> },
+    })
+    const validation = parseText(res.content as TextContent[]) as { valid: boolean }
+    expect(validation.valid).toBe(true)
+  })
+
+  it("reports validation failure for an unknown capability", async () => {
+    const broken = workflow("Broken")
+      .run([step("@executioncontrolprotocol/test.does-not-exist", "X").with({}).as("o")])
+      .toManifest()
+    const res = await client.callTool({
+      name: "ecp.validate_workflow",
+      arguments: { workflow: broken as unknown as Record<string, unknown> },
+    })
+    const validation = parseText(res.content as TextContent[]) as { valid: boolean }
+    expect(validation.valid).toBe(false)
+  })
+
+  it("runs a workflow and retrieves its status", async () => {
+    const runRes = await client.callTool({
+      name: "ecp.run_workflow",
+      arguments: { workflow: echoWorkflow as unknown as Record<string, unknown> },
+    })
+    const result = parseText(runRes.content as TextContent[]) as {
+      run: { id: string; status: string }
+    }
+    expect(result.run.status).toBe("completed")
+
+    const statusRes = await client.callTool({
+      name: "ecp.get_run_status",
+      arguments: { runId: result.run.id },
+    })
+    const status = parseText(statusRes.content as TextContent[]) as {
+      run: { id: string }
+    }
+    expect(status.run.id).toBe(result.run.id)
+  })
+
+  it("returns a serialized error for an unknown tool", async () => {
+    const res = await client.callTool({ name: "ecp.not_a_tool", arguments: {} })
+    expect(res.isError).toBe(true)
+    const text = (res.content as TextContent[])
+      .map((c) => c.text)
+      .join("\n")
+    expect(text).toContain("not found")
+  })
+
+  it("lists and reads the capabilities resource", async () => {
+    const { resources } = await client.listResources()
+    expect(resources.some((r) => r.uri === "ecp://capabilities")).toBe(true)
+
+    const read = await client.readResource({ uri: "ecp://capabilities" })
+    const capabilities = JSON.parse(read.contents[0]!.text as string) as { id: string }[]
+    expect(capabilities.some((c) => c.id.includes("echo"))).toBe(true)
+  })
+
+  it("reads a single capability via the templated resource", async () => {
+    const read = await client.readResource({ uri: "ecp://capabilities/@executioncontrolprotocol/test.echo" })
+    const capability = JSON.parse(read.contents[0]!.text as string) as { id: string }
+    expect(capability.id).toBe("@executioncontrolprotocol/test.echo")
+  })
+
+  it("lists prompts and renders author_workflow", async () => {
+    const { prompts } = await client.listPrompts()
+    expect(prompts.map((p) => p.name)).toEqual(
+      expect.arrayContaining([
+        "ecp.author_workflow",
+        "ecp.repair_workflow",
+        "ecp.explain_environment",
+      ])
+    )
+
+    const prompt = await client.getPrompt({
+      name: "ecp.author_workflow",
+      arguments: { goal: "echo a value" },
+    })
+    const text = prompt.messages
+      .map((m) => (m.content.type === "text" ? m.content.text : ""))
+      .join("\n")
+    expect(text).toContain("echo a value")
+    expect(text).toContain("@executioncontrolprotocol/test.echo")
+  })
+})

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src", "composite": true },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../types" }, { "path": "../core" }]
+}