create-windy 0.2.23 → 0.2.24

package/template/apps/server/src/mcp/adapter.test.ts

@@ -0,0 +1,195 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  createFoundationSnapshot,
+  loadFoundationModules,
+} from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { createSystemToolHandlers } from "../agent/routes.js";
+import { GovernedToolRegistry } from "../agent/tool-registry.js";
+import { PlatformMcpAdapter } from "./adapter.js";
+
+const clients: Client[] = [];
+
+afterEach(async () => {
+  await Promise.all(clients.splice(0).map((client) => client.close()));
+});
+
+describe("Platform MCP Adapter", () => {
+  test("只发现当前 Actor 获准的 query Tool 并返回结构化结果", async () => {
+    const fixture = createFixture();
+    const client = await connectClient(fixture, "limited-token");
+    const listed = await client.listTools();
+
+    expect(listed.tools.map(({ name }) => name)).toEqual([
+      "system.features.list",
+    ]);
+    expect(listed.tools[0]).toMatchObject({
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+      },
+      inputSchema: { type: "object" },
+      outputSchema: { type: "object" },
+    });
+
+    const called = await client.callTool({
+      name: "system.features.list",
+      arguments: { pageSize: 2 },
+    });
+    expect(called.isError).not.toBe(true);
+    expect(called.structuredContent).toMatchObject({
+      page: 1,
+      pageSize: 2,
+    });
+  });
+
+  test("直接调用未授权或未知 Tool 使用相同脱敏错误", async () => {
+    const fixture = createFixture();
+    const client = await connectClient(fixture, "limited-token");
+
+    const denied = await client.callTool({
+      name: "system.users.list",
+      arguments: {},
+    });
+    const missing = await client.callTool({
+      name: "system.unknown.list",
+      arguments: {},
+    });
+
+    expect(denied).toMatchObject({
+      isError: true,
+      content: [{ type: "text", text: "工具不可用或无权限。" }],
+    });
+    expect(missing).toEqual(denied);
+  });
+
+  test("未认证和跨源浏览器请求在协议解析前拒绝", async () => {
+    const fixture = createFixture();
+    const anonymousRequest = mcpRequest();
+    const anonymousContext =
+      await fixture.runtime.createGuardContext(anonymousRequest);
+    const anonymous = await fixture.adapter.handle(
+      anonymousRequest,
+      anonymousContext,
+    );
+    expect(anonymous.status).toBe(401);
+    expect(anonymous.headers.get("www-authenticate")).toBe("Bearer");
+
+    const missingEntryRequest = mcpRequest("target-only-token");
+    const missingEntryContext =
+      await fixture.runtime.createGuardContext(missingEntryRequest);
+    const missingEntry = await fixture.adapter.handle(
+      missingEntryRequest,
+      missingEntryContext,
+    );
+    expect(missingEntry.status).toBe(403);
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .some(({ action }) => action === "security.denied"),
+    ).toBe(true);
+
+    const crossOriginRequest = mcpRequest("limited-token", "https://evil.test");
+    const crossOriginContext =
+      await fixture.runtime.createGuardContext(crossOriginRequest);
+    const denied = await fixture.adapter.handle(
+      crossOriginRequest,
+      crossOriginContext,
+    );
+    expect(denied.status).toBe(403);
+  });
+});
+
+function createFixture() {
+  const modules = loadFoundationModules();
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: {
+        resolve: (request) => {
+          const authorization = request.headers.get("authorization");
+          if (
+            authorization !== "Bearer limited-token" &&
+            authorization !== "Bearer target-only-token"
+          ) {
+            return undefined;
+          }
+          return {
+            id: "actor-limited",
+            type: "user",
+            name: "受限用户",
+            roleCodes: ["member"],
+            permissionKeys:
+              authorization === "Bearer limited-token"
+                ? ["system.agent.read", "system.feature.read"]
+                : ["system.feature.read"],
+          };
+        },
+      },
+      featureCatalog: modules.flatMap(({ features }) => features),
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  const handlers = createSystemToolHandlers(
+    createSystemRepositories(createFoundationSnapshot()),
+    runtime,
+  );
+  const registry = new GovernedToolRegistry(modules, handlers, runtime);
+  return {
+    adapter: new PlatformMcpAdapter(
+      registry,
+      runtime,
+      modules.flatMap(({ features }) => features),
+    ),
+    runtime,
+  };
+}
+
+async function connectClient(
+  fixture: ReturnType<typeof createFixture>,
+  token: string,
+): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(
+    new URL("http://localhost/api/mcp"),
+    {
+      requestInit: {
+        headers: { authorization: `Bearer ${token}` },
+      },
+      fetch: async (input, init) => {
+        const request = new Request(input, init);
+        const context = await fixture.runtime.createGuardContext(request);
+        return fixture.adapter.handle(request, context);
+      },
+    },
+  );
+  const client = new Client({ name: "windy-test", version: "0.1.0" });
+  clients.push(client);
+  await client.connect(transport);
+  return client;
+}
+
+function mcpRequest(token?: string, origin?: string): Request {
+  const headers = new Headers({
+    accept: "application/json, text/event-stream",
+    "content-type": "application/json",
+  });
+  if (token) headers.set("authorization", `Bearer ${token}`);
+  if (origin) headers.set("origin", origin);
+  return new Request("http://localhost/api/mcp", {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-11-25",
+        capabilities: {},
+        clientInfo: { name: "windy-test", version: "0.1.0" },
+      },
+    }),
+  });
+}

package/template/apps/server/src/mcp/adapter.ts

@@ -0,0 +1,204 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import type {
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestGuardContext } from "../guards.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  GovernedToolRegistry,
+  ToolExecutionError,
+  type RegisteredTool,
+} from "../agent/tool-registry.js";
+
+export class PlatformMcpAdapter {
+  readonly #feature: FeatureFlagDefinition;
+
+  constructor(
+    private readonly tools: GovernedToolRegistry,
+    private readonly runtime: ReturnType<typeof createServerRuntime>,
+    features: FeatureFlagDefinition[],
+  ) {
+    const feature = findFeature(features, "system.agent");
+    if (!feature) throw new Error("MCP Adapter 缺少 system.agent Feature");
+    this.#feature = feature;
+  }
+
+  async handle(
+    request: Request,
+    context: RequestGuardContext,
+    parsedBody?: unknown,
+  ): Promise<Response> {
+    const rejected = rejectRequest(request, context);
+    if (rejected) return rejected;
+    const access = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: "system.agent.read" },
+      feature: this.#feature,
+    });
+    if (!access.decision.allowed) {
+      return Response.json(
+        {
+          error: "FORBIDDEN",
+          reason: access.decision.reason,
+        },
+        { status: 403 },
+      );
+    }
+
+    const server = this.createServer(context);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      enableJsonResponse: true,
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    try {
+      return await transport.handleRequest(request, { parsedBody });
+    } finally {
+      await server.close();
+    }
+  }
+
+  private createServer(context: RequestGuardContext): Server {
+    const server = new Server(
+      { name: "windy-platform", version: "0.1.0" },
+      {
+        capabilities: { tools: {} },
+        instructions:
+          "仅调用当前账号可见的只读业务工具；权限和数据范围由 Windy 平台逐次校验。",
+      },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: await this.allowedQueryTools(context),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) =>
+      this.callTool(
+        request.params.name,
+        toToolInput(request.params.arguments ?? {}),
+        context,
+      ),
+    );
+    return server;
+  }
+
+  private async allowedQueryTools(
+    context: RequestGuardContext,
+  ): Promise<Tool[]> {
+    const tools = await Promise.all(
+      this.tools
+        .definitions()
+        .filter(({ operation }) => operation === "query")
+        .map(async (tool) =>
+          (await this.tools.allowed(tool.key, context))
+            ? toMcpTool(tool)
+            : undefined,
+        ),
+    );
+    return tools.filter((tool): tool is Tool => tool !== undefined);
+  }
+
+  private async callTool(
+    key: string,
+    input: ModuleToolInput,
+    context: RequestGuardContext,
+  ): Promise<CallToolResult> {
+    const definition = this.tools
+      .definitions()
+      .find((tool) => tool.key === key && tool.operation === "query");
+    if (!definition) return toolError("工具不可用或无权限。");
+    try {
+      const result = await this.tools.execute(key, input, context);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: toStructuredContent(result),
+      };
+    } catch (error) {
+      if (!(error instanceof ToolExecutionError)) throw error;
+      if (error.code === "TOOL_NOT_FOUND" || error.code === "TOOL_FORBIDDEN") {
+        return toolError("工具不可用或无权限。");
+      }
+      if (error.code === "TOOL_INPUT_INVALID") {
+        return toolError("工具输入不符合契约。");
+      }
+      if (error.code === "TOOL_TIMEOUT") {
+        return toolError("工具执行超时。");
+      }
+      return toolError("工具执行失败。");
+    }
+  }
+}
+
+function toMcpTool(tool: RegisteredTool): Tool {
+  return {
+    name: tool.key,
+    title: tool.label,
+    description: tool.description,
+    inputSchema: toMcpSchema(tool.inputSchema),
+    outputSchema: toMcpSchema(tool.outputSchema),
+    annotations: {
+      title: tool.label,
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  };
+}
+
+function toMcpSchema(
+  schema: RegisteredTool["inputSchema"],
+): Tool["inputSchema"] {
+  if (schema.type !== "object") {
+    throw new Error("MCP Tool Schema 顶层类型必须是 object");
+  }
+  return schema as Tool["inputSchema"];
+}
+
+function toToolInput(
+  value: Readonly<Record<string, unknown>>,
+): ModuleToolInput {
+  return JSON.parse(JSON.stringify(value)) as ModuleToolInput;
+}
+
+function toStructuredContent(
+  result: ModuleToolResult,
+): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(result)) as Record<string, unknown>;
+}
+
+function toolError(message: string): CallToolResult {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
+function rejectRequest(
+  request: Request,
+  context: RequestGuardContext,
+): Response | undefined {
+  if (context.actor.type === "anonymous") {
+    return Response.json(
+      { error: "UNAUTHENTICATED" },
+      {
+        status: 401,
+        headers: { "www-authenticate": "Bearer" },
+      },
+    );
+  }
+  const origin = request.headers.get("origin");
+  if (origin && origin !== new URL(request.url).origin) {
+    return Response.json({ error: "ORIGIN_DENIED" }, { status: 403 });
+  }
+  return undefined;
+}

package/template/apps/server/src/mcp/routes.ts

@@ -0,0 +1,21 @@
+import type { RouteApp } from "../system/routes.js";
+import { PlatformMcpAdapter } from "./adapter.js";
+
+interface McpRouteContext {
+  readonly request: Request;
+  readonly body?: unknown;
+  readonly guardContext: Parameters<PlatformMcpAdapter["handle"]>[1];
+}
+
+export function registerMcpRoutes(
+  app: RouteApp,
+  adapter: PlatformMcpAdapter,
+): void {
+  const handle = (rawContext: unknown) => {
+    const context = rawContext as McpRouteContext;
+    return adapter.handle(context.request, context.guardContext, context.body);
+  };
+  app.get("/mcp", handle);
+  app.post("/mcp", handle);
+  app.delete("/mcp", handle);
+}

package/template/apps/server/src/module-host/tool-handlers.ts

@@ -1,4 +1,4 @@
-import type { ModuleToolHandlers } from "../agent/routes.js";
+import type { ModuleToolHandlers } from "../agent/tool-registry.js";
 import type { InitializedModuleHosts } from "./initialize.js";
 import { toModuleActor } from "./request-context.js";
 
@@ -14,10 +14,11 @@ export function createModuleToolHandlerMap(
       registration.toolKey,
       {
         scopeMode: registration.scopeMode,
-        execute: (query, context) =>
-          registration.execute(query, {
-            actor: toModuleActor(context.actor),
-            requestId: context.requestId,
+        execute: (input, context) =>
+          registration.execute(input, {
+            actor: toModuleActor(context.guardContext.actor),
+            requestId: context.guardContext.requestId,
+            signal: context.signal,
           }),
       },
     ]),

package/template/apps/server/src/observability/http-observability.test.ts

@@ -50,4 +50,25 @@ describe("HTTP observability", () => {
     expect(responseStatus(new Response(null, { status: 503 }), 200)).toBe(503);
     expect(responseStatus({}, 201)).toBe(201);
   });
+
+  test("同一次 observation 重复完成时不重复记录日志", () => {
+    const records: Record<string, unknown>[] = [];
+    const observer = new HttpObservability(new RuntimeMetrics(), {
+      info(fields) {
+        records.push(fields);
+      },
+    });
+    const observation = observer.begin("GET");
+    const input = {
+      request: new Request("https://example.test/api/failure"),
+      guardContext: context,
+      observation,
+      responseValue: new Response(null, { status: 500 }),
+    };
+
+    observer.complete(input);
+    observer.complete(input);
+
+    expect(records).toHaveLength(1);
+  });
 });

package/template/apps/server/src/observability/http-observability.ts

@@ -27,6 +27,7 @@ export class HttpObservability {
       input.observation,
       statusCode,
     );
+    if (durationMs === undefined) return;
     this.logger.info(
       {
         event: "http.request.completed",

package/template/apps/server/src/observability/metrics.ts

@@ -34,8 +34,11 @@ export class RuntimeMetrics {
     };
   }
 
-  finishRequest(observation: RequestObservation, statusCode: number): number {
-    if (observation.finished) return 0;
+  finishRequest(
+    observation: RequestObservation,
+    statusCode: number,
+  ): number | undefined {
+    if (observation.finished) return;
     observation.finished = true;
     this.activeRequests = Math.max(0, this.activeRequests - 1);
     const durationMs =

package/template/docs/operations/observability.md

@@ -33,6 +33,11 @@ Web、Server、License 和 Signing 接受 `x-request-id`。只保留 1 至 128
 
 请求完成日志禁止记录完整 URL、query、请求或响应 body、Cookie、Authorization、Secret、连接串和原始异常。需要增加字段时，必须先判断其基数和敏感性，并补充防泄漏测试。生产日志采集器应按 JSON 字段解析，按 `requestId` 关联，不依赖自由文本。
 
+请求观测在全局 `onRequest` 建立，在响应完成时原子取出并结束。未匹配路由、Guard
+拒绝和 handler 异常与正常请求遵循同一生命周期；即使框架同时触发 error 与
+after-response 路径，同一个请求也只能扣减一次活跃计数并写一条完成日志。业务路由
+不能假设只有匹配成功的请求才存在观测状态。
+
 ## Server 指标
 
 `GET /api/metrics` 输出 Prometheus text format，并设置 `Cache-Control: no-store`。当前指标包括：
@@ -45,6 +50,9 @@ Web、Server、License 和 Signing 接受 `x-request-id`。只保留 1 至 128
 
 ## 当前验证状态
 
-已验证：共享关联标识校验、四个服务的 liveness/readiness 分离、Server 指标格式、Server/License 请求完成日志字段、Web 到 Server 的标识透传，均有 Bun 单元或边界测试；工作区 typecheck 和 Oxlint 已通过。Dockerfile 已声明 readiness `HEALTHCHECK`。
+已验证：共享关联标识校验、四个服务的 liveness/readiness 分离、Server 指标格式、
+Server/License 请求完成日志字段、Web 到 Server 的标识透传，以及 Server 未匹配路由、
+异常路由只完成一次观测且不会终止进程，均有 Bun 单元或边界测试；工作区 typecheck 和
+Oxlint 已通过。Dockerfile 已声明 readiness `HEALTHCHECK`。
 
 尚未由本页证明：生产 Compose、新环境部署、备份恢复、升级回滚、原生 Linux amd64 runner、告警规则、长稳运行、多实例和大容量。这些项必须由后续生产恢复演练和目标环境记录单独闭环；Docker Desktop 或 QEMU 上的 amd64 运行不能写成原生 Linux amd64 已认证。

package/template/docs/platform/agent-runtime.md

@@ -62,6 +62,18 @@ Tool handler 仍通过 `registerToolHandlers` 注册。模型提出 Tool Call
 Tool 请求不能携带权限列表、License、Scope 或“已授权”标志。客户端或模型提供的这些
 字段会被拒绝，未知 Tool 也不会形成注册表探测通道。
 
+## 跨进程 Limits 契约
+
+Manifest 的 Operation limits 同时包含输入、执行时间和输出上限。Southwind AI Server
+在调用远端 Agent Server 前先执行 `maxInputBytes` 校验；跨进程请求只逐字段发送 Agent
+Server 负责执行的 `maxDurationSeconds` 和 `maxOutputBytes`。禁止通过展开 Manifest
+对象透传 limits：TypeScript 的结构类型不会在运行时移除额外字段，而 Agent Server
+契约会以 `extra=forbid` 拒绝未知字段。
+
+这个边界保证输入上限仍由持有原始业务输入的 Server 强制执行，同时避免 Python Runtime
+被平台内部但不属于远端契约的字段阻断。新增 limits 字段时，必须分别决定执行归属，并在
+真实 HTTP 序列化测试中确认请求体。
+
 ## 本地 Compose profile
 
 选择 `system.agent` 的 create-windy 项目会生成 `agent` profile 和随机内部 Token。
@@ -114,13 +126,13 @@ SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，
 `run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
 cursor 恢复；不要重新创建 Run 或重复执行 Tool。
 
-## 从 create-windy 0.2.21 或更早版本升级
+## 从 create-windy 0.2.23 或更早版本升级
 
 先检查计划，再应用连续 recipe：
 
 ```bash
-bunx --bun create-windy@0.2.22 update --check
-bunx --bun create-windy@0.2.22 update
+bunx --bun create-windy@0.2.24 update --check
+bunx --bun create-windy@0.2.24 update
 bun install
 ```
 

package/template/docs/platform/agent-tools.md

@@ -1,44 +1,104 @@
 # Agent Tool 注册与执行
 
-## 当前状态
+## 能力契约
 
-Server 端已提供 Agent Tool 的最小闭环：
+Agent Tool 是业务模块向平台 Agent Runtime 和后续 MCP Adapter 暴露业务能力的唯一
+声明。业务模块不得分别维护 Agent、MCP 或 OpenAPI Tool Key。
 
-- 工具定义来自模块 manifest 的 `tools` 字段。
-- `GET /api/agent/tools` 返回已注册工具和当前请求是否有权限。
-- `POST /api/agent/tools/:key/execute` 执行工具。
-- 执行前使用 Permission Guard 校验 `permissionKey`。
-- 权限拒绝记录 `security.denied` 审计事件。
-- 执行成功记录 `agent.tool.execute` 审计事件。
-- ModuleHost 通过 `registerAiOperationHandlers` 注册模型无关 Operation plan。
-- Guarded Run facade 只把 Operation `allowedToolKeys` 中的定义交给模型。
-- Agent Server 的 Tool Call 必须通过短时 Execution Grant 回到受限 Tool Host。
-- Tool Host 使用宿主绑定的 Actor 与 Scope 重新执行 Operation/Tool Guard；客户端和模型
-  不能传权限、License、Scope 或授权结论。
+每个 Tool 在 Module Manifest 中声明：
 
-OpenAPI 文档由 `@elysiajs/swagger` 提供，随 Server 启动自动暴露。
+- 稳定 Key、中文名称和模型可理解的说明；
+- 输入、输出 JSON Schema Key；
+- `query`、`command` 或 `background` 操作类型；
+- Feature、Permission、Audit Action 和 `platform/request` 数据范围模式；
+- 数据分类、幂等策略、审批策略；
+- 最大执行时间、输入字节数和输出字节数。
 
-## 当前工具
+JSON Schema 通过同一 Manifest 的 `jsonSchemas` 注册。Schema Key 全局唯一，顶层必须是
+`object`；Tool 引用未知 Schema、Schema 重复、限制非正整数、查询能力错误声明审批时，
+Composition 在 Server 监听前失败。
 
-- `system.users.list`：查询用户。
-- `system.features.list`：查询功能开关。
-- `system.audit.list`：查询审计日志。
+业务实现通过 `@southwind-ai/server-sdk` 的 `registerToolHandlers()` 注册类型化 JSON
+Handler。Handler 的 `scopeMode` 必须与 Manifest 相同，并收到宿主提供的 Actor、
+Request ID 和超时 AbortSignal，不能接收客户端提交的权限或数据范围。
+
+## 统一执行 Registry
+
+`GovernedToolRegistry` 是原生 Agent Tool Route、Agent Runtime Tool Host 和 MCP Adapter
+共用的执行 Interface。每次调用按以下顺序执行：
+
+1. 解析当前 Server Actor；
+2. 重新执行 License、Feature 和 Permission Guard；
+3. 对 `scopeMode=request` 验证 Server 构造的数据范围；
+4. 按输入 Schema 应用默认值、类型归一化并移除未声明字段；
+5. 检查输入大小并执行带超时信号的 Handler；
+6. 检查输出大小和输出 Schema，输出漂移 fail closed；
+7. 写入不含 Tool 原始参数和结果的受控审计摘要。
+
+输入中出现 `actorId`、`permissionKeys`、`departmentId` 等未声明字段会在 Handler 前被
+移除，不能成为授权事实。输出 Schema 不执行字段移除；Handler 返回未知字段或错误类型
+会被视为实现漂移并拒绝。
+
+## HTTP 接口
 
-## 开发态鉴权
+- `GET /api/agent/tools`：返回 Tool 描述、输入输出 Schema 和当前 Actor 的 `allowed`。
+- `POST /api/agent/tools/:key/execute`：使用 JSON object body 执行 Tool。
 
-开发态可用：
+基础分页 Tool 仍兼容旧 query 参数；新业务调用应使用 JSON body。
+
+开发态可使用：
 
 ```text
 Authorization: Bearer dev-admin-token
 ```
 
-该 token 来自内存运行时上下文，只用于本地闭环验证，不是生产登录体系。
+该 Token 只用于本地闭环验证，不是生产登录体系。
+
+## 当前只读工具
+
+- `system.users.list`：查询当前数据范围内的脱敏用户。
+- `system.features.list`：查询功能开关。
+- `system.audit.list`：查询审计事件。
+
+三者共用 `system.pagination.input.v1` 与 `system.page.output.v1` Schema。
+
+## Agent Runtime
+
+ModuleHost 通过 `registerAiOperationHandlers` 注册模型无关 Operation plan。Guarded Run
+facade 只允许 Operation `allowedToolKeys` 中的定义进入模型上下文。Agent Server 的 Tool
+Call 必须通过短时 Execution Grant 回到受限 Tool Host，随后由统一 Registry 使用宿主绑定
+的 Actor 与 Scope 再次授权。
+
+Agent Runtime、环境变量、SSE 与 Compose profile 见
+[Agent Runtime 接入与运行](./agent-runtime.md)。
+
+## MCP Streamable HTTP
+
+选择 `system.agent` 模块后，Server 在 `POST /api/mcp` 暴露官方 MCP TypeScript SDK
+v1 的无状态 Streamable HTTP Endpoint；`GET` 和 `DELETE` 也注册在同一路径，由无状态
+Transport 返回协议允许的状态。
+
+接入要求：
+
+- 请求必须使用现有平台 Bearer Token 或 Session Cookie 完成身份解析；
+- 入口先经过 `system.agent` Feature 与 `system.agent.read` Permission Guard；
+- 带浏览器 `Origin` 的请求必须与 Endpoint 同源；
+- `tools/list` 只返回当前 Actor 获准的 `query` Tool；
+- `tools/call` 不信任列表阶段结果，每次重新执行 Tool Guard 和数据范围校验；
+- 成功结果同时提供 MCP 文本 `content` 与 `structuredContent`；
+- 未授权与未知 Tool 返回同形脱敏错误，避免形成能力探测面。
+
+示例 MCP Endpoint：
+
+```text
+http://localhost:9747/api/mcp
+```
+
+MCP 使用无状态模式，不保存授权快照或长期 Session。Feature、角色或数据范围变化会在下一次
+调用立即生效。
 
-## 当前边界
+## 后续边界
 
-- 工具执行复用系统资源 Repository；未配置 `DATABASE_URL` 时使用内存仓储，配置后使用 Drizzle 仓储。
-- 工具参数当前只支持基础分页参数。
-- 审计事件写入内存 sink；配置 `DATABASE_URL` 后会通过有界重试写入 PostgreSQL `audit_logs`，持续失败会增加计数并输出告警，审计查询优先读取该表。详细降级语义见 [平台审计可靠写入](./audit-reliability.md)。
-- Agent Runtime、环境变量、SSE 与 Compose profile 见
-  [Agent Runtime 接入与运行](./agent-runtime.md)。
-- 后续应继续完善 Agent Tool 的结构化输入 schema、写操作幂等和执行结果追踪。
+- `command/background` 在具备幂等键、审批和可追踪执行结果前不得通过 MCP 暴露。
+- 完整 Tool 参数和结果默认不进入审计、日志或 Trace。
+- OpenAPI 继续承担普通 HTTP 集成，不自动把所有 Route 机械转换为 Tool。