@c4a/mcp-service 0.3.7-alpha.1

package/src/__tests__/query-tools.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import type { StorageAdapter } from "@c4a/storage";
+import type { QueryConfig } from "@c4a/query";
+import { registerQueryTools } from "../tools/query.js";
+
+type ToolHandler = (args: unknown) => Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }>;
+
+function createMockAdapter(): StorageAdapter {
+  const adapter = {
+    async initialize() {
+      return;
+    },
+    async search() {
+      return {
+        items: [
+          {
+            id: "sys-1",
+            type: "system",
+            score: 0.9,
+            snippet: "System summary",
+          },
+        ],
+        total: 1,
+        has_more: false,
+        search_mode: "vector",
+      };
+    },
+  } as unknown as StorageAdapter;
+
+  return adapter;
+}
+
+function createToolRegistry() {
+  const tools = new Map<string, ToolHandler>();
+  const server = {
+    tool(name: string, _description: string, _schema: unknown, handler: ToolHandler) {
+      tools.set(name, handler);
+    },
+  } as unknown as { tool: (name: string, description: string, schema: unknown, handler: ToolHandler) => void };
+
+  return { server, tools };
+}
+
+describe("mcp-service query tools", () => {
+  test("query_batch_search returns map result", async () => {
+    const adapter = createMockAdapter();
+    const { server, tools } = createToolRegistry();
+    const queryConfig: QueryConfig = {
+      defaultRootId: "demo-root",
+    };
+
+    registerQueryTools(server as any, { adapterReady: Promise.resolve(adapter), queryConfig });
+
+    const handler = tools.get("query_batch_search");
+    expect(handler).toBeTruthy();
+
+    const response = await handler!({
+      queries: [
+        { name: "order-service", type: "system" },
+        { name: "order-service", type: "component" },
+      ],
+    });
+
+    expect(response.isError).toBeUndefined();
+    const payload = JSON.parse(response.content[0]?.text ?? "{}") as {
+      items?: Record<string, { items?: Array<{ id: string }> }>;
+    };
+    expect(payload.items?.["order-service"]?.items?.length).toBe(1);
+  });
+});

package/src/__tests__/smoke.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, test } from "bun:test";
+import { createServer } from "../server.js";
+
+describe("mcp-service smoke", () => {
+  test("createServer returns instance", () => {
+    const server = createServer();
+    expect(server).toBeTruthy();
+  });
+});

package/src/__tests__/store-tools.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import type { StorageAdapter, Entity } from "@c4a/storage";
+import type { StoreConfig } from "@c4a/store";
+import { registerStoreTools } from "../tools/store.js";
+
+type ToolHandler = (args: unknown) => Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }>;
+
+function createMockAdapter(): StorageAdapter {
+  let entity: Entity | null = null;
+
+  const adapter = {
+    async initialize() {
+      return;
+    },
+    async transaction<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T> {
+      return fn(adapter as StorageAdapter);
+    },
+    async list() {
+      return [];
+    },
+    async readByUuid(uuid: string) {
+      if (entity && entity.uuid === uuid) return entity;
+      return null;
+    },
+    async read(rootId: string, id: string) {
+      if (entity && entity.root_id === rootId && entity.id === id) return entity;
+      return null;
+    },
+    async save(input: Entity) {
+      entity = {
+        ...input,
+        uuid: input.uuid ?? "00000000-0000-0000-0000-000000000001",
+        versions: input.versions ?? ["0.0.0"],
+      };
+      return entity;
+    },
+  } as unknown as StorageAdapter;
+
+  return adapter;
+}
+
+function createToolRegistry() {
+  const tools = new Map<string, ToolHandler>();
+  const server = {
+    tool(name: string, _description: string, _schema: unknown, handler: ToolHandler) {
+      tools.set(name, handler);
+    },
+  } as unknown as { tool: (name: string, description: string, schema: unknown, handler: ToolHandler) => void };
+
+  return { server, tools };
+}
+
+describe("mcp-service store tools", () => {
+  test("store_save accepts document entity", async () => {
+    const adapter = createMockAdapter();
+    const { server, tools } = createToolRegistry();
+    const storeConfig: StoreConfig = {
+      defaultRootId: "demo-root",
+      isRemote: false,
+      rootDir: process.cwd(),
+    };
+
+    registerStoreTools(server as any, { adapterReady: Promise.resolve(adapter), storeConfig });
+
+    const handler = tools.get("store_save");
+    expect(handler).toBeTruthy();
+
+    const response = await handler!({
+      type: "document",
+      data: {
+        id: "doc-1",
+        subtype: "prd",
+      },
+    });
+
+    expect(response.isError).toBeUndefined();
+    const payload = JSON.parse(response.content[0]?.text ?? "{}") as { success?: boolean; entity?: Entity };
+    expect(payload.success).toBe(true);
+    expect(payload.entity?.type).toBe("document");
+  });
+
+  test("store_read returns document entity", async () => {
+    const adapter = createMockAdapter();
+    const { server, tools } = createToolRegistry();
+    const storeConfig: StoreConfig = {
+      defaultRootId: "demo-root",
+      isRemote: false,
+      rootDir: process.cwd(),
+    };
+
+    registerStoreTools(server as any, { adapterReady: Promise.resolve(adapter), storeConfig });
+
+    const saveHandler = tools.get("store_save");
+    const readHandler = tools.get("store_read");
+    expect(saveHandler).toBeTruthy();
+    expect(readHandler).toBeTruthy();
+
+    await saveHandler!({
+      type: "document",
+      data: {
+        id: "doc-2",
+        subtype: "prd",
+      },
+    });
+
+    const response = await readHandler!({
+      id: "doc-2",
+    });
+
+    expect(response.isError).toBeUndefined();
+    const payload = JSON.parse(response.content[0]?.text ?? "{}") as { entity?: Entity };
+    expect(payload.entity?.type).toBe("document");
+  });
+
+  test("store_batch_save returns results list", async () => {
+    const adapter = createMockAdapter();
+    const { server, tools } = createToolRegistry();
+    const storeConfig: StoreConfig = {
+      defaultRootId: "demo-root",
+      isRemote: false,
+      rootDir: process.cwd(),
+    };
+
+    registerStoreTools(server as any, { adapterReady: Promise.resolve(adapter), storeConfig });
+
+    const handler = tools.get("store_batch_save");
+    expect(handler).toBeTruthy();
+
+    const response = await handler!({
+      entities: [
+        {
+          type: "system",
+          data: { id: "sys-1", name: "System" },
+        },
+        {
+          type: "component",
+          data: { id: "cmp-1", name: "Component" },
+        },
+      ],
+    });
+
+    expect(response.isError).toBeUndefined();
+    const payload = JSON.parse(response.content[0]?.text ?? "{}") as {
+      results?: Array<{ id: string; uuid: string; status: string }>;
+      failed?: Array<{ id?: string; error: string }>;
+    };
+    expect(payload.failed?.length ?? 0).toBe(0);
+    expect(payload.results?.length).toBe(2);
+  });
+
+  test("store_batch_save returns failed entry on validation error", async () => {
+    const adapter = createMockAdapter();
+    const { server, tools } = createToolRegistry();
+    const storeConfig: StoreConfig = {
+      defaultRootId: "demo-root",
+      isRemote: false,
+      rootDir: process.cwd(),
+    };
+
+    registerStoreTools(server as any, { adapterReady: Promise.resolve(adapter), storeConfig });
+
+    const handler = tools.get("store_batch_save");
+    expect(handler).toBeTruthy();
+
+    const response = await handler!({
+      entities: [
+        {
+          type: "process",
+          data: { id: "prc-1" },
+        },
+      ],
+    });
+
+    expect(response.isError).toBeUndefined();
+    const payload = JSON.parse(response.content[0]?.text ?? "{}") as {
+      results?: Array<{ id: string; uuid: string; status: string }>;
+      failed?: Array<{ id?: string; error: string }>;
+    };
+    expect(payload.results?.length ?? 0).toBe(0);
+    expect(payload.failed?.length ?? 0).toBe(1);
+  });
+});

package/src/index.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * @c4a/mcp-service - MCP 服务端
+ *
+ * 提供 store_* / query_* 工具
+ *
+ * 支持两种 transport 模式:
+ * - stdio (默认): 被 Agent 自动拉起
+ * - streamable-http: Docker 部署，暴露 HTTP 端口
+ *
+ * 环境变量:
+ * - MCP_TRANSPORT: stdio | streamable-http (默认 stdio)
+ * - MCP_PORT: HTTP 端口 (默认 8051)
+ */
+import { createServer } from "./server.js";
+
+const transport = process.env.MCP_TRANSPORT || "stdio";
+const port = parseInt(process.env.MCP_PORT || "8051", 10);
+
+async function startStdioServer() {
+  const server = createServer();
+  const { StdioServerTransport } = await import(
+    "@modelcontextprotocol/sdk/server/stdio.js"
+  );
+  const stdioTransport = new StdioServerTransport();
+  await server.connect(stdioTransport);
+  console.error("c4a-mcp-service server started (stdio)");
+}
+
+async function startHttpServer() {
+  const { createServer: createHttpServer } = await import("node:http");
+  const { StreamableHTTPServerTransport } = await import(
+    "@modelcontextprotocol/sdk/server/streamableHttp.js"
+  );
+  const { isInitializeRequest } = await import("@modelcontextprotocol/sdk/types.js");
+  const { randomUUID } = await import("node:crypto");
+
+  const sessions: Map<
+    string,
+    {
+      transport: InstanceType<typeof StreamableHTTPServerTransport>;
+      server: ReturnType<typeof createServer>;
+    }
+  > = new Map();
+
+  const httpServer = createHttpServer(async (req, res) => {
+    const url = new URL(req.url || "/", `http://localhost:${port}`);
+
+    if (url.pathname === "/health" && req.method === "GET") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", service: "c4a-mcp-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)) {
+          const mcpServer = createServer();
+          const httpTransport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+              sessions.set(id, { transport: httpTransport, server: mcpServer });
+              console.log(`Session initialized: ${id}`);
+            },
+          });
+
+          httpTransport.onclose = () => {
+            if (httpTransport.sessionId) {
+              sessions.delete(httpTransport.sessionId);
+              console.log(`Session closed: ${httpTransport.sessionId}`);
+            }
+          };
+
+          await mcpServer.connect(httpTransport);
+          session = { transport: httpTransport, server: mcpServer };
+        }
+
+        if (session) {
+          await session.transport.handleRequest(req, res, body);
+        } else {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              error: { code: -32000, message: "Invalid session" },
+              id: null,
+            })
+          );
+        }
+      } else if (req.method === "GET") {
+        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");
+        }
+      } else if (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");
+        }
+      } else {
+        res.writeHead(405, { "Content-Type": "text/plain" });
+        res.end("Method not allowed");
+      }
+      return;
+    }
+
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  });
+
+  httpServer.listen(port, "0.0.0.0", () => {
+    console.log(`c4a-mcp-service server started (http://0.0.0.0:${port}/mcp)`);
+    console.log(`Health check: http://0.0.0.0:${port}/health`);
+  });
+}
+
+async function main() {
+  if (transport === "streamable-http") {
+    await startHttpServer();
+  } else {
+    await startStdioServer();
+  }
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/schemas/querySchemas.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+export const EntityTypeSchema = z.enum([
+  "system",
+  "container",
+  "component",
+  "contract",
+  "product",
+  "process",
+  "sor",
+  "document",
+  "feat",
+]);
+
+export const QuerySearchScopeSchema = EntityTypeSchema.or(z.literal("all"));
+
+export const QuerySearchInputSchema = z.object({
+  query: z.string().describe("搜索关键词"),
+  scope: QuerySearchScopeSchema.optional().describe("实体类型筛选（all 表示不限）"),
+  type_filter: QuerySearchScopeSchema.optional().describe("实体类型筛选（兼容字段）"),
+  root_id: z.string().optional().describe("包边界 root_id（可选）"),
+  versions: z.array(z.string()).optional().describe("版本过滤（可选，命中 versions 包含）"),
+  limit: z.number().optional().default(20).describe("返回结果数量上限"),
+  offset: z.number().optional().default(0).describe("分页偏移量"),
+});
+
+export const QueryBatchSearchQuerySchema = z.object({
+  name: z.string().describe("实体名称"),
+  type: EntityTypeSchema.optional().describe("实体类型（可选）"),
+});
+
+export const QueryBatchSearchInputSchema = z.object({
+  queries: z.array(QueryBatchSearchQuerySchema).describe("批量查询列表"),
+  root_id: z.string().optional().describe("包边界 root_id（可选）"),
+  versions: z.array(z.string()).optional().describe("版本过滤（可选，命中 versions 包含）"),
+  limit: z.number().optional().default(20).describe("返回结果数量上限"),
+  offset: z.number().optional().default(0).describe("分页偏移量"),
+});
+
+export const QueryDepsDirectionSchema = z.enum(["upstream", "downstream", "both"]);
+
+export const QueryDepsInputSchema = z.object({
+  uuid: z.string().optional().describe("实体 UUID（优先使用）"),
+  root_id: z.string().optional().describe("实体 root_id（与 id 搭配）"),
+  id: z.string().optional().describe("实体 ID（与 root_id 搭配）"),
+  direction: QueryDepsDirectionSchema.optional().describe("依赖方向"),
+  depth: z.number().optional().describe("依赖深度"),
+});
+
+export const QueryImpactInputSchema = z.object({
+  uuid: z.string().optional().describe("实体 UUID（优先使用）"),
+  root_id: z.string().optional().describe("实体 root_id（与 id 搭配）"),
+  id: z.string().optional().describe("实体 ID（与 root_id 搭配）"),
+  change_type: z.enum(["upgrade", "deprecate", "remove"]).optional().describe("变更类型"),
+  depth: z.number().optional().describe("影响深度"),
+});
+
+export type QuerySearchInput = z.infer<typeof QuerySearchInputSchema>;
+export type QueryBatchSearchInput = z.infer<typeof QueryBatchSearchInputSchema>;
+export type QueryDepsInput = z.infer<typeof QueryDepsInputSchema>;
+export type QueryImpactInput = z.infer<typeof QueryImpactInputSchema>;