feat(mcp): contracts, capability stats migration and MCP SDK dependency

- contracts/mcp.ts: capability stats/tools, MCP server status/config schemas, mcpToolVisible
- api.ts: GET /capabilities/stats, GET /capabilities/tools, GET /mcp/status, PATCH /mcp/config
- migration 0039: mcp_server_config single row + audit_event capability index
- deno.json: npm:@modelcontextprotocol/[email protected].1

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/contracts/src/api.ts

@@ -11,6 +11,7 @@ import * as execution from "./execution.ts";
 import * as files from "./files.ts";
 import * as identity from "./identity.ts";
 import * as instances from "./instances.ts";
+import * as mcp from "./mcp.ts";
 import * as ops from "./ops.ts";
 import * as organization from "./organization.ts";
 import * as pi from "./pi.ts";
@@ -1564,6 +1565,40 @@ export const Api = {
       body: z.object({ input: z.unknown(), preview: z.boolean().default(false) }),
       response: z.object({ output: z.unknown(), taskId: Id.nullable(), planId: Id.nullable() }),
     }),
+    stats: ep({
+      method: "get",
+      path: "/capabilities/stats",
+      scope: "read",
+      summary: "能力调用统计：每能力调用数、失败数、平均耗时、最近调用、调用来源（内置 Agent / MCP / REST）",
+      query: mcp.CapabilityStatsQuery,
+      response: mcp.CapabilityStatsResponse,
+    }),
+    tools: ep({
+      method: "get",
+      path: "/capabilities/tools",
+      scope: "read",
+      summary: "能力清单：描述符、工具名、输入输出 JSON Schema、当前授权状态",
+      response: mcp.CapabilityToolsResponse,
+    }),
+  },
+
+  // ── 对外 MCP 服务端(Streamable HTTP 在 /mcp,不进 OpenAPI;这里是状态与配置)──
+  mcp: {
+    status: ep({
+      method: "get",
+      path: "/mcp/status",
+      scope: "admin",
+      summary: "MCP 服务端状态：启用、允许的 API Key、当前会话、最近调用、限速",
+      response: mcp.McpServerStatus,
+    }),
+    update: ep({
+      method: "patch",
+      path: "/mcp/config",
+      scope: "admin",
+      summary: "修改 MCP 服务端配置（启用开关、允许的 API Key）",
+      body: mcp.McpServerConfigUpdate,
+      response: mcp.McpServerConfig,
+    }),
   },
 
   // ── 设置 ──
@@ -2328,3 +2363,4 @@ export type EndpointResponse<E extends EndpointDef> = z.infer<E["response"]>;
 
 export * from "./files.ts";
 export * from "./schedules.ts";
+export * from "./mcp.ts";

packages/contracts/src/mcp.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { CapabilityDescriptor, type CapabilityKind } from "./capability.ts";
+import { type ApiScope, Id, Timestamp } from "./common.ts";
+
+// 对外 MCP 服务端与能力可视化(REQ R13、§10.3、§12.3)。
+// MCP 每个 tool 对应一个已注册能力(工具名 `域__动作`),调用走同一个 registry.invoke(授权 / 审计 / 幂等键 / 操作账本)。
+
+/** MCP 端点(相对 API_PREFIX);Streamable HTTP,POST 发消息、GET 开服务端推送流、DELETE 结束会话 */
+export const MCP_PATH = "/mcp";
+/** MCP 协议里声明的服务端名 */
+export const MCP_SERVER_NAME = "uhd-media-tool";
+
+/** 调用来源归类:内置 Agent(含后台任务)、MCP、REST(控制台 / API Key 直接调用) */
+export const CapabilityCaller = z.enum(["agent", "mcp", "rest", "other"]);
+export type CapabilityCaller = z.infer<typeof CapabilityCaller>;
+
+/** 审计 payload.source → 调用来源 */
+export function callerOfSource(source: string | null | undefined): CapabilityCaller {
+  if (source === "agent" || source === "task") return "agent";
+  if (source === "mcp") return "mcp";
+  if (source === "web" || source === "cli") return "rest";
+  return "other";
+}
+
+/**
+ * 能力当前的授权状态(服务端按 automation_grant 判定):
+ * - read_only:read / preview,只看 scope,不需要授权;
+ * - granted:有覆盖它的有效持续授权(自动来源仍受自动化总开关约束);
+ * - needs_approval:没有持续授权,需要单次审批(或控制台手动执行);
+ * - agent_only:只在 Agent 会话内可用(agent.* 能力,例如派生子会话)。
+ */
+export const CapabilityAuthState = z.enum(["read_only", "granted", "needs_approval", "agent_only"]);
+export type CapabilityAuthState = z.infer<typeof CapabilityAuthState>;
+
+export const CapabilityStatsQuery = z.object({
+  days: z.coerce.number().int().min(1).max(90).default(7),
+});
+export type CapabilityStatsQuery = z.infer<typeof CapabilityStatsQuery>;
+
+const CallerCounts = z.object({
+  agent: z.number().int().nonnegative(),
+  mcp: z.number().int().nonnegative(),
+  rest: z.number().int().nonnegative(),
+  other: z.number().int().nonnegative(),
+});
+
+/** 单个能力在统计窗口内的调用汇总(来自 audit_event 的 capability.invoke / capability.denied) */
+export const CapabilityStatsItem = z.object({
+  capabilityId: z.string(),
+  calls: z.number().int().nonnegative(),
+  /** outcome = error / invalid */
+  failures: z.number().int().nonnegative(),
+  /** 授权或白名单拒绝 */
+  denied: z.number().int().nonnegative(),
+  avgDurationMs: z.number().nonnegative().nullable(),
+  lastCalledAt: Timestamp.nullable(),
+  lastOutcome: z.string().nullable(),
+  lastCaller: CapabilityCaller.nullable(),
+  byCaller: CallerCounts,
+});
+export type CapabilityStatsItem = z.infer<typeof CapabilityStatsItem>;
+
+export const CapabilityStatsResponse = z.object({
+  days: z.number().int(),
+  since: Timestamp,
+  items: z.array(CapabilityStatsItem),
+});
+export type CapabilityStatsResponse = z.infer<typeof CapabilityStatsResponse>;
+
+/** 能力清单(给工具页与会话页工具卡片):描述符 + 工具名 + JSON Schema + 授权状态 */
+export const CapabilityToolInfo = CapabilityDescriptor.extend({
+  toolName: z.string(),
+  inputJsonSchema: z.record(z.string(), z.unknown()),
+  outputJsonSchema: z.record(z.string(), z.unknown()),
+  authState: CapabilityAuthState,
+  /** 覆盖它的有效持续授权数 */
+  activeGrants: z.number().int().nonnegative(),
+  /** 能否经 MCP 暴露(agent.* 只在 Agent 会话内) */
+  mcpExposed: z.boolean(),
+});
+export type CapabilityToolInfo = z.infer<typeof CapabilityToolInfo>;
+
+export const CapabilityToolsResponse = z.object({
+  /** 自动化总开关:关着时 execute 类能力对自动来源(Agent / MCP / API Key)一律拒绝 */
+  automationEnabled: z.boolean(),
+  readOnlyReconcile: z.boolean(),
+  items: z.array(CapabilityToolInfo),
+});
+export type CapabilityToolsResponse = z.infer<typeof CapabilityToolsResponse>;
+
+/** MCP 服务端配置(mcp_server_config 单行) */
+export const McpServerConfig = z.object({
+  enabled: z.boolean(),
+  /** 允许连接的 API Key;null = 所有未撤销的 Key */
+  allowedApiKeyIds: z.array(Id).nullable(),
+  updatedAt: Timestamp.nullable(),
+});
+export type McpServerConfig = z.infer<typeof McpServerConfig>;
+
+export const McpServerConfigUpdate = z
+  .object({
+    enabled: z.boolean(),
+    allowedApiKeyIds: z.array(Id).max(200).nullable(),
+  })
+  .partial();
+export type McpServerConfigUpdate = z.infer<typeof McpServerConfigUpdate>;
+
+export const McpSessionInfo = z.object({
+  /** 会话 ID 前 8 位(完整 ID 等同会话凭据,不回显) */
+  idPrefix: z.string(),
+  apiKeyId: z.string(),
+  apiKeyName: z.string(),
+  clientName: z.string().nullable(),
+  createdAt: Timestamp,
+  lastSeenAt: Timestamp,
+  toolCalls: z.number().int().nonnegative(),
+});
+export type McpSessionInfo = z.infer<typeof McpSessionInfo>;
+
+export const McpRecentCall = z.object({
+  at: Timestamp,
+  capabilityId: z.string(),
+  outcome: z.string(),
+  actorId: z.string().nullable(),
+  durationMs: z.number().nullable(),
+  errorCode: z.string().nullable(),
+});
+export type McpRecentCall = z.infer<typeof McpRecentCall>;
+
+export const McpServerStatus = McpServerConfig.extend({
+  /** 相对站点根的端点路径(/api/v1/mcp) */
+  path: z.string(),
+  transport: z.literal("streamable-http"),
+  serverName: z.string(),
+  serverVersion: z.string(),
+  /** 每个 API Key 每分钟的工具调用上限 */
+  rateLimitPerMinute: z.number().int().positive(),
+  /** 每个 API Key 同时保持的会话上限 */
+  maxSessionsPerKey: z.number().int().positive(),
+  sessions: z.array(McpSessionInfo),
+  recentCalls: z.array(McpRecentCall),
+  /** 常见 Key 组合能看到的工具数(read / read + organize.execute / admin) */
+  toolsByScope: z.object({
+    read: z.number().int().nonnegative(),
+    readExecute: z.number().int().nonnegative(),
+    admin: z.number().int().nonnegative(),
+  }),
+});
+export type McpServerStatus = z.infer<typeof McpServerStatus>;
+
+/** MCP 工具可见性:能力 scope 被 Key 覆盖;没有 organize.execute(或 admin)时只给 read / preview 类 */
+export function mcpToolVisible(
+  d: Pick<CapabilityDescriptor, "id" | "kind" | "scope">,
+  scopes: readonly string[],
+): boolean {
+  if (d.id.startsWith("agent.")) return false;
+  const has = (s: ApiScope) =>
+    scopes.includes("admin") || scopes.includes(s) || (s === "organize.read" && scopes.includes("organize.execute"));
+  if (!has(d.scope)) return false;
+  const readish: readonly CapabilityKind[] = ["read", "preview"];
+  return readish.includes(d.kind) || has("organize.execute");
+}

packages/contracts/test/db-sync.test.ts

@@ -132,6 +132,8 @@ const INTERNAL_TABLES = [
   // W9-I 进程心跳(0034):服务端内部,经 /system/health 的专用 DTO 暴露
   "ProcessHeartbeat",
   "ProcessHeartbeatSample",
+  // AG-1 MCP 服务端单行配置(0039):经 /mcp/status 与 /mcp/config 的专用 DTO 暴露
+  "McpServerConfig",
   // C1-B 恢复码 / Passkey / WebAuthn 挑战(0037):服务端内部,经 contracts/auth.ts 的专用 DTO 暴露
   "AdminRecoveryCode",
   "AdminPasskey",

packages/db/migrations/0039_capability_stats.ts

@@ -0,0 +1,36 @@
+import type { Kysely } from "kysely";
+import { dropTables, execDdl } from "../src/migration-helpers.ts";
+
+// AG-1 对外 MCP 服务端与能力统计:
+// - mcp_server_config:单行配置(启用开关、允许连接的 API Key;null = 所有未撤销的 Key)。
+// - 能力调用统计直接汇总 audit_event(capability.invoke / capability.denied 覆盖读写全部能力,
+//   capability_invocation 只记有副作用的调用);补一条按能力 + 时间的部分索引。
+
+// biome-ignore lint/suspicious/noExplicitAny: 迁移不依赖应用表类型
+export async function up(db: Kysely<any>): Promise<void> {
+  await execDdl(
+    db,
+    `
+create table mcp_server_config (
+  id integer primary key default 1 check (id = 1),
+  enabled boolean not null default true,
+  allowed_api_key_ids text[],
+  updated_by text,
+  updated_at timestamptz not null default now()
+);
+insert into mcp_server_config (id) values (1);
+
+create index if not exists audit_event_capability_idx on audit_event (target_id, at)
+  where target_type = 'capability';
+`,
+  );
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: 同上
+export async function down(db: Kysely<any>): Promise<void> {
+  await execDdl(
+    db,
+    `drop index if exists audit_event_capability_idx;
+${dropTables(["mcp_server_config"])}`,
+  );
+}

packages/db/src/types.ts

@@ -868,6 +868,14 @@ export interface MediaAssetTable {
   download_task_id: string | null;
 }
 
+export interface McpServerConfigTable {
+  id: Generated<number>;
+  enabled: Generated<boolean>;
+  allowed_api_key_ids: string[] | null;
+  updated_by: string | null;
+  updated_at: GeneratedTimestamptz;
+}
+
 export interface MediaEntityTable {
   id: Generated<string>;
   kind: MediaEntityKind;
@@ -1623,6 +1631,7 @@ export interface DB {
   library_root: LibraryRootTable;
   login_attempt: LoginAttemptTable;
   media_asset: MediaAssetTable;
+  mcp_server_config: McpServerConfigTable;
   media_entity: MediaEntityTable;
   media_server_instance: MediaServerInstanceTable;
   metadata_field: MetadataFieldTable;
@@ -1772,6 +1781,9 @@ export type LoginAttemptUpdate = Updateable<LoginAttemptTable>;
 export type MediaAssetRow = Selectable<MediaAssetTable>;
 export type NewMediaAsset = Insertable<MediaAssetTable>;
 export type MediaAssetUpdate = Updateable<MediaAssetTable>;
+export type McpServerConfigRow = Selectable<McpServerConfigTable>;
+export type NewMcpServerConfig = Insertable<McpServerConfigTable>;
+export type McpServerConfigUpdate = Updateable<McpServerConfigTable>;
 export type MediaEntityRow = Selectable<MediaEntityTable>;
 export type NewMediaEntity = Insertable<MediaEntityTable>;
 export type MediaEntityUpdate = Updateable<MediaEntityTable>;

packages/db/test/schema.test.ts

@@ -109,6 +109,8 @@ const EXPECTED_TABLES = [
   // W9-I 进程心跳(0034)
   "process_heartbeat",
   "process_heartbeat_sample",
+  // AG-1 MCP 服务端配置(0039)
+  "mcp_server_config",
   // C1-B 恢复码 / Passkey / WebAuthn 挑战(0037)
   "admin_recovery_code",
   "admin_passkey",
@@ -132,6 +134,8 @@ const NON_ENTITY_TABLES = [
   // 进程心跳:instance_id 主键 / 只追加的采样
   "process_heartbeat",
   "process_heartbeat_sample",
+  // 单行配置(id = 1)
+  "mcp_server_config",
   // 一次性凭据:只记创建 / 用掉的时间
   "admin_recovery_code",
   "webauthn_challenge",