@c4a/mcp-service 0.3.7-alpha.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@c4a/mcp-service",
+  "version": "0.3.7-alpha.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "bin": {
+    "c4a-mcp-service": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./src/server.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@c4a/core": "workspace:*",
+    "@c4a/storage": "workspace:*",
+    "@c4a/store": "workspace:*",
+    "@c4a/version": "workspace:*",
+    "@c4a/query": "workspace:*",
+    "zod": "^3.23.0",
+    "typescript": "^5.4.0",
+    "@types/bun": "latest",
+    "yaml": "^2.3.4"
+  }
+}

package/src/__e2e__/e2eUtils.ts

@@ -0,0 +1,258 @@
+import { createServer } from "node:http";
+import { mkdir, mkdtemp, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer as createMcpServiceServer } from "../server.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { resetAdapter, SQLiteStore } from "@c4a/storage";
+
+const E2E_TMP_ROOT = join(process.cwd(), ".tmp", "e2e");
+
+export type E2eDirOptions = {
+  outsideRepo?: boolean;
+};
+
+export async function withCwd<T>(dir: string, fn: () => Promise<T>): Promise<T> {
+  const previousCwd = process.cwd();
+  process.chdir(dir);
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previousCwd);
+  }
+}
+
+export async function withE2eDir<T>(
+  name: string,
+  fn: (dir: string) => Promise<T>,
+  options: E2eDirOptions = {},
+): Promise<T> {
+  await mkdir(E2E_TMP_ROOT, { recursive: true });
+  const dirName = `${name}-${Date.now()}`;
+  if (!options.outsideRepo) {
+    const dir = join(E2E_TMP_ROOT, dirName);
+    await mkdir(dir, { recursive: true });
+    try {
+      return await fn(dir);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+      resetSQLiteStore();
+    }
+  }
+  const externalDir = await mkdtemp(join(tmpdir(), "c4a-e2e-"));
+  const linkPath = join(E2E_TMP_ROOT, dirName);
+  await symlink(externalDir, linkPath);
+  try {
+    return await fn(externalDir);
+  } finally {
+    await unlink(linkPath);
+    await rm(externalDir, { recursive: true, force: true });
+    resetSQLiteStore();
+  }
+}
+
+export async function createMcpClient(dir: string): Promise<{ client: Client; close: () => Promise<void> }> {
+  const mcpServicePath = fileURLToPath(new URL("../index.ts", import.meta.url));
+  const transport = new StdioClientTransport({
+    command: "bun",
+    args: [mcpServicePath],
+    cwd: dir,
+    env: {
+      ...process.env,
+      C4A_HOME: dir,
+      MCP_TRANSPORT: "stdio",
+    },
+    stderr: "pipe",
+  });
+  const client = new Client({ name: "c4a-mcp-service-e2e", version: "0.0.0" });
+  await client.connect(transport);
+  return {
+    client,
+    close: async () => {
+      await client.close();
+    },
+  };
+}
+
+export async function withMcpServiceServer<T>(fn: (url: string) => Promise<T>): Promise<T> {
+  const previousBackendUrl = process.env.C4A_STORAGE_BACKEND_URL;
+  delete process.env.C4A_STORAGE_BACKEND_URL;
+  try {
+    const sessions: Map<
+      string,
+      { transport: StreamableHTTPServerTransport; server: ReturnType<typeof createMcpServiceServer> }
+    > = new Map();
+    let lastSession:
+      | { transport: StreamableHTTPServerTransport; server: ReturnType<typeof createMcpServiceServer> }
+      | null = null;
+
+    const serverCwd = process.cwd();
+    const httpServer = createServer(async (req, res) => {
+      const previousCwd = process.cwd();
+      if (previousCwd !== serverCwd) {
+        process.chdir(serverCwd);
+      }
+      try {
+        const url = new URL(req.url || "/", "http://localhost");
+
+        if (url.pathname === "/health" && req.method === "GET") {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ status: "ok", service: "c4a-service" }));
+          return;
+        }
+
+        if (url.pathname === "/mcp") {
+          const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+          if (req.method === "POST") {
+            const chunks: Buffer[] = [];
+            for await (const chunk of req) {
+              chunks.push(chunk);
+            }
+            const body = JSON.parse(Buffer.concat(chunks).toString());
+
+            let session = sessionId ? sessions.get(sessionId) : undefined;
+
+            if (!session && (isInitializeRequest(body) || !sessionId)) {
+              const mcpServer = createMcpServiceServer();
+              const httpTransport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => {
+                  sessions.set(id, { transport: httpTransport, server: mcpServer });
+                  lastSession = { transport: httpTransport, server: mcpServer };
+                },
+              });
+              httpTransport.onclose = () => {
+                if (httpTransport.sessionId) {
+                  sessions.delete(httpTransport.sessionId);
+                }
+              };
+
+              await mcpServer.connect(httpTransport);
+              session = { transport: httpTransport, server: mcpServer };
+              lastSession = session;
+            }
+
+            if (!session && sessions.size === 1) {
+              session = Array.from(sessions.values())[0];
+            }
+            if (!session && lastSession) {
+              session = lastSession;
+            }
+
+            if (session) {
+              await session.transport.handleRequest(req, res, body);
+              const activeSessionId = session.transport.sessionId;
+              if (activeSessionId && !sessions.has(activeSessionId)) {
+                sessions.set(activeSessionId, session);
+              }
+            } else {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  jsonrpc: "2.0",
+                  error: { code: -32000, message: "Invalid session" },
+                  id: null,
+                }),
+              );
+            }
+            return;
+          }
+          if (req.method === "GET" || req.method === "DELETE") {
+            const session = sessionId ? sessions.get(sessionId) : undefined;
+            if (session) {
+              await session.transport.handleRequest(req, res);
+            } else {
+              res.writeHead(400, { "Content-Type": "text/plain" });
+              res.end("Invalid session");
+            }
+            return;
+          }
+
+          res.writeHead(405, { "Content-Type": "text/plain" });
+          res.end("Method not allowed");
+          return;
+        }
+
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+      } finally {
+        if (process.cwd() !== previousCwd) {
+          process.chdir(previousCwd);
+        }
+      }
+    });
+
+    await new Promise<void>((resolve) => {
+      httpServer.listen(0, "127.0.0.1", () => resolve());
+    });
+
+    const address = httpServer.address();
+    if (!address || typeof address === "string") {
+      throw new Error("无法获取 MCP 服务端口");
+    }
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+
+    try {
+      return await fn(baseUrl);
+    } finally {
+      await new Promise<void>((resolve) => {
+        httpServer.close(() => resolve());
+      });
+    }
+  } finally {
+    if (previousBackendUrl === undefined) {
+      delete process.env.C4A_STORAGE_BACKEND_URL;
+    } else {
+      process.env.C4A_STORAGE_BACKEND_URL = previousBackendUrl;
+    }
+  }
+}
+
+export async function withMcpClient<T>(baseUrl: string, fn: (client: Client) => Promise<T>): Promise<T> {
+  const client = new Client({ name: "c4a-e2e-client", version: "0.1.0" });
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/mcp`));
+  await client.connect(transport);
+  try {
+    return await fn(client);
+  } finally {
+    await transport.close();
+  }
+}
+
+export async function writeProjectConfig(dir: string, rootId: string): Promise<void> {
+  const contextDir = join(dir, ".context");
+  await mkdir(contextDir, { recursive: true });
+  const content = [
+    "mode: local",
+    "local:",
+    `  defaultProject: ${rootId}`,
+    "  enableVectorSearch: false",
+    "",
+  ].join("\n");
+  await writeFile(join(contextDir, ".c4a.yaml"), content, "utf-8");
+}
+
+export function parseToolResponse<T>(
+  payload: { content?: Array<{ type: string; text?: string }> }
+): T {
+  const text = payload.content?.find((item) => item.type === "text")?.text ?? payload.content?.[0]?.text ?? "";
+  if (!text) {
+    return {} as T;
+  }
+  return JSON.parse(text) as T;
+}
+
+function resetSQLiteStore(): void {
+  resetAdapter();
+  const storeClass = SQLiteStore as unknown as { closeInstance?: () => void };
+  if (typeof storeClass.closeInstance === "function") {
+    storeClass.closeInstance();
+  }
+}

package/src/__e2e__/mcpFixtures.ts

@@ -0,0 +1,244 @@
+import { parseToolResponse } from "./e2eUtils.js";
+
+export const ROOT_ID = "demo";
+
+export type ToolResponse<T> = {
+  isError?: boolean;
+  data: T;
+};
+
+type E2eEntity = {
+  uuid?: string;
+  id?: string;
+  type?: string;
+  kind?: string;
+  scope?: string;
+  perspective?: string;
+  versions?: string[];
+  data?: Record<string, unknown>;
+};
+
+export type StoreSaveResult = {
+  success?: boolean;
+  id?: string;
+  entity?: E2eEntity;
+};
+
+export type StoreReadResult = {
+  entity?: E2eEntity;
+};
+
+export type StoreListResult = {
+  items?: Array<{ uuid?: string; id?: string; type?: string; versions?: string[] }>;
+};
+
+export type VersionPublishResult = {
+  success?: boolean;
+  version?: string;
+  affected_entities?: number;
+};
+
+export type ErrorResponse = {
+  code?: string;
+  message?: string;
+  details?: Record<string, unknown>;
+  recoverable_actions?: Array<{ action: string; label?: string; params?: Record<string, unknown> }>;
+};
+
+export function buildSystemData(id: string, description: string): Record<string, unknown> {
+  return {
+    schema: "c4a/v1",
+    type: "software-system",
+    system: {
+      id,
+      name: id,
+      description,
+      scope: "project",
+    },
+  };
+}
+
+export function buildContainerData(
+  id: string,
+  systemId: string,
+  description: string,
+  contractRef?: string,
+): Record<string, unknown> {
+  return {
+    schema: "c4a/v1",
+    type: "container",
+    system_id: systemId,
+    container: {
+      id,
+      name: id,
+      description,
+      scope: "project",
+      system_id: systemId,
+      technology: [{ language: "ts" }],
+      apis: contractRef ? [{ type: "openapi", ref: contractRef }] : [],
+    },
+  };
+}
+
+export function buildComponentData(
+  id: string,
+  containerId: string | undefined,
+  description: string,
+  contractRef?: string,
+): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    schema: "c4a/v1",
+    type: "component",
+    component: {
+      id,
+      name: id,
+      description,
+      scope: "project",
+      implements_contracts: contractRef ? [contractRef] : [],
+    },
+  };
+  if (containerId) {
+    base.container_id = containerId;
+    (base.component as Record<string, unknown>).container_id = containerId;
+  }
+  return base;
+}
+
+export function buildContractData(id: string, description: string): Record<string, unknown> {
+  return {
+    schema: "c4a/v1",
+    type: "contract",
+    contract: {
+      id,
+      name: id,
+      description,
+      contract_type: "openapi",
+      status: "implemented",
+    },
+  };
+}
+
+type ToolClient = {
+  callTool: (input: { name: string; arguments: Record<string, unknown> }) => Promise<unknown>;
+};
+
+type ToolCallResult = {
+  isError?: boolean;
+  content?: Array<{ type: string; text?: string }>;
+};
+
+function coerceToolResult(payload: unknown): ToolCallResult {
+  return payload as ToolCallResult;
+}
+
+export async function callTool<T>(
+  client: ToolClient,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<ToolResponse<T>> {
+  const result = coerceToolResult(await client.callTool({ name, arguments: args }));
+  return { isError: result.isError, data: parseToolResponse<T>(result) };
+}
+
+export async function saveEntity(
+  client: ToolClient,
+  params: {
+    type: "system" | "container" | "component" | "contract";
+    id: string;
+    data: Record<string, unknown>;
+    version?: string;
+    rootId?: string;
+  },
+): Promise<StoreSaveResult> {
+  const { data } = await callTool<StoreSaveResult>(client, "store_save", {
+    type: params.type,
+    id: params.id,
+    data: params.data,
+    root_id: params.rootId ?? ROOT_ID,
+    version: params.version,
+  });
+  return data;
+}
+
+export async function readEntity(
+  client: ToolClient,
+  params: { id: string; version?: string; rootId?: string },
+): Promise<StoreReadResult> {
+  const { data } = await callTool<StoreReadResult>(client, "store_read", {
+    id: params.id,
+    root_id: params.rootId ?? ROOT_ID,
+    version: params.version,
+    format: "object",
+  });
+  return data;
+}
+
+export async function listEntities(
+  client: ToolClient,
+  params: { id?: string; version?: string; type?: string; rootId?: string },
+): Promise<StoreListResult> {
+  const { data } = await callTool<StoreListResult>(client, "store_list", {
+    root_id: params.rootId ?? ROOT_ID,
+    id: params.id,
+    version: params.version,
+    type: params.type ?? "all",
+  });
+  return data;
+}
+
+export async function publishVersion(
+  client: ToolClient,
+  params: { version: string; publishAs?: string; rootId?: string },
+): Promise<VersionPublishResult> {
+  const { data } = await callTool<VersionPublishResult>(client, "version_publish", {
+    root_id: params.rootId ?? ROOT_ID,
+    version: params.version,
+    publish_as: params.publishAs,
+  });
+  return data;
+}
+
+export async function addVersion(
+  client: ToolClient,
+  params: { uuid: string; version: string },
+): Promise<void> {
+  await callTool(client, "version_add", {
+    uuid: params.uuid,
+    version: params.version,
+  });
+}
+
+export async function seedReleaseReadyData(
+  client: ToolClient,
+  version?: string,
+  rootId?: string,
+): Promise<void> {
+  await saveEntity(client, {
+    type: "system",
+    id: "sys",
+    data: buildSystemData("sys", "System desc"),
+    version,
+    rootId,
+  });
+  await saveEntity(client, {
+    type: "contract",
+    id: "contract-api",
+    data: buildContractData("contract-api", "Contract desc"),
+    version,
+    rootId,
+  });
+  await saveEntity(client, {
+    type: "container",
+    id: "svc",
+    data: buildContainerData("svc", "sys", "Container desc", "contract-api"),
+    version,
+    rootId,
+  });
+  await saveEntity(client, {
+    type: "component",
+    id: "cmp",
+    data: buildComponentData("cmp", "svc", "Component desc", "contract-api"),
+    version,
+    rootId,
+  });
+}