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]>
This commit is contained in:
rootandClaude Opus 5.5 committed
1 parent
efb5d206c1
commit
73ee3c6614
8 files changed
+294
-10
No files matched your search
@@ -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";
|
||||
@@ -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");
|
||||
}
|
||||
Reference in new issue
Block a user