128 lines
4.4 KiB
TypeScript
128 lines
4.4 KiB
TypeScript
import { toolRegistry, type ToolRegistry } from "./tool-registry";
|
|
import { FACECLAW_VERSION } from "../version";
|
|
|
|
/**
|
|
* Minimal MCP (Model Context Protocol) server surface over the assistant
|
|
* bridge's `mcp` channel. The phone serves its ToolRegistry to the external
|
|
* agent: `tools/list`, `tools/call`, and `notifications/tools/list_changed`
|
|
* (emitted by the bridge client when the registry changes).
|
|
*
|
|
* Transport-agnostic: the bridge client hands decoded JSON-RPC messages to
|
|
* handleMessage and provides `send` to deliver replies/notifications.
|
|
*/
|
|
|
|
const MCP_PROTOCOL_VERSION = "2025-06-18";
|
|
|
|
/** Proactive display actions are rate-limited to this many per minute. */
|
|
const PROACTIVE_CALLS_PER_MINUTE = 6;
|
|
|
|
export type McpServerOptions = {
|
|
send: (msg: object) => void;
|
|
/** Whether a voice turn is currently in flight (calls outside one are "proactive"). */
|
|
isTurnActive: () => boolean;
|
|
/** Master setting gate for proactive calls (assistant.allowProactive). */
|
|
allowProactive: () => boolean;
|
|
registry?: ToolRegistry;
|
|
};
|
|
|
|
export class AssistantMcpServer {
|
|
private readonly registry: ToolRegistry;
|
|
private readonly proactiveCallTimes: number[] = [];
|
|
|
|
constructor(private readonly options: McpServerOptions) {
|
|
this.registry = options.registry ?? toolRegistry;
|
|
}
|
|
|
|
/** Notify the agent that the live tool set changed. */
|
|
sendToolsChanged(): void {
|
|
this.options.send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
|
|
}
|
|
|
|
handleMessage(msg: any): void {
|
|
if (!msg || msg.jsonrpc !== "2.0") return;
|
|
if (typeof msg.method !== "string") return; // responses to server-sent requests: none yet
|
|
const id = msg.id;
|
|
const isNotification = id === undefined || id === null;
|
|
|
|
switch (msg.method) {
|
|
case "initialize":
|
|
this.reply(id, {
|
|
protocolVersion:
|
|
typeof msg.params?.protocolVersion === "string"
|
|
? msg.params.protocolVersion
|
|
: MCP_PROTOCOL_VERSION,
|
|
capabilities: { tools: { listChanged: true } },
|
|
serverInfo: { name: "faceclaw", version: FACECLAW_VERSION },
|
|
});
|
|
return;
|
|
case "notifications/initialized":
|
|
return;
|
|
case "ping":
|
|
this.reply(id, {});
|
|
return;
|
|
case "tools/list":
|
|
this.reply(id, {
|
|
tools: this.registry.listTools().map((spec) => ({
|
|
name: spec.name,
|
|
description: spec.description,
|
|
inputSchema: spec.inputSchema,
|
|
})),
|
|
});
|
|
return;
|
|
case "tools/call":
|
|
void this.handleToolCall(id, msg.params);
|
|
return;
|
|
default:
|
|
if (!isNotification) {
|
|
this.options.send({
|
|
jsonrpc: "2.0",
|
|
id,
|
|
error: { code: -32601, message: `Method not supported: ${msg.method}` },
|
|
});
|
|
}
|
|
return;
|
|
}
|
|
}
|
|
|
|
private async handleToolCall(id: unknown, params: any): Promise<void> {
|
|
const name = typeof params?.name === "string" ? params.name : "";
|
|
const args = params?.arguments ?? {};
|
|
// A call while no voice turn is in flight is a proactive action by the
|
|
// remote agent; the phone (never the bridge) enforces the gating.
|
|
const proactive = !this.options.isTurnActive();
|
|
if (proactive && !this.options.allowProactive()) {
|
|
this.replyToolError(id, "Proactive assistant actions are disabled in Settings");
|
|
return;
|
|
}
|
|
if (proactive && !this.admitProactiveCall()) {
|
|
this.replyToolError(id, "Proactive action rate limit exceeded; try again later");
|
|
return;
|
|
}
|
|
const result = await this.registry.callTool(name, args, { proactive });
|
|
this.reply(id, {
|
|
content: [{ type: "text", text: result.ok ? result.content ?? "" : result.error ?? "Tool error" }],
|
|
isError: !result.ok,
|
|
});
|
|
}
|
|
|
|
/** Sliding-window rate limiter for proactive calls. */
|
|
private admitProactiveCall(): boolean {
|
|
const now = Date.now();
|
|
while (this.proactiveCallTimes.length && now - this.proactiveCallTimes[0]! > 60_000) {
|
|
this.proactiveCallTimes.shift();
|
|
}
|
|
if (this.proactiveCallTimes.length >= PROACTIVE_CALLS_PER_MINUTE) return false;
|
|
this.proactiveCallTimes.push(now);
|
|
return true;
|
|
}
|
|
|
|
private reply(id: unknown, result: object): void {
|
|
if (id === undefined || id === null) return;
|
|
this.options.send({ jsonrpc: "2.0", id, result });
|
|
}
|
|
|
|
private replyToolError(id: unknown, text: string): void {
|
|
this.reply(id, { content: [{ type: "text", text }], isError: true });
|
|
}
|
|
}
|