Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

feat(mcp): dispatch MCP requests to tools with permission and confirmation

spacesdrived344492ee4c8
diff --git a/backend/mcp/schemas.ts b/backend/mcp/schemas.ts
new file mode 100644
index 0000000..bb7d0f9
--- /dev/null
+++ b/backend/mcp/schemas.ts
@@ -0,0 +1,57 @@
+import { MAX_PAGE_SIZE } from './tool.ts';
+import { ValidationError } from '../lib/errors.ts';
+import { optionalNumber, optionalString } from '../validators/fields.ts';
+import type { JsonSchema } from './tool.ts';
+import type { Fields } from '../validators/fields.ts';
+
+// building blocks for the JSON Schemas tools/list publishes; the validators enforce the same rules on every call
+
+export function objectSchema(properties: Record<string, JsonSchema>, required: string[] = []): JsonSchema {
+ return { type: 'object', properties, required, additionalProperties: false };
+}
+
+export const idProperty = (what: string): JsonSchema => ({ type: 'string', minLength: 1, maxLength: 100, description: `The ${what} id, as a list tool returned it` });
+
+export const pageProperties: Record<string, JsonSchema> = {
+ limit: { type: 'integer', minimum: 1, maximum: MAX_PAGE_SIZE, description: `How many items to return, ${MAX_PAGE_SIZE} at most (default 20)` },
+ cursor: { type: 'string', description: 'The nextCursor from the previous page, to continue the list' },
+};
+
+// added to the schema of every tool that asks for a confirmation first
+export const confirmationProperty: JsonSchema = {
+ type: 'string',
+ description: 'Leave out on the first call. The first call returns a confirmationToken; send it back only after the person agreed to the action it describes.',
+};
+
+export function withConfirmation(schema: JsonSchema): JsonSchema {
+ const properties = (schema.properties ?? {}) as Record<string, JsonSchema>;
+ return { ...schema, properties: { ...properties, confirmationToken: confirmationProperty } };
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+
+export interface Page {
+ limit: number;
+ offset: number;
+}
+
+// the cursor is the position of the next item; it carries no data, so a forged one only skips items the caller owns
+export function parsePage(fields: Fields): Page {
+ const limit = optionalNumber(fields, 'limit') ?? DEFAULT_PAGE_SIZE;
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) throw new ValidationError(`limit must be a whole number from 1 to ${MAX_PAGE_SIZE}`);
+ const cursor = optionalString(fields, 'cursor');
+ const offset = cursor === undefined ? 0 : Number(cursor);
+ if (!Number.isInteger(offset) || offset < 0) throw new ValidationError('cursor must be the nextCursor a previous page returned');
+ return { limit, offset };
+}
+
+export function pageOf<T>(items: T[], { limit, offset }: Page): { items: T[]; nextCursor: string | null; total: number } {
+ const end = offset + limit;
+ return { items: items.slice(offset, end), nextCursor: end < items.length ? String(end) : null, total: items.length };
+}
+
+export function requiredId(fields: Fields, name: string, what: string): string {
+ const value = fields[name];
+ if (typeof value !== 'string' || value.trim() === '' || value.length > 100) throw new ValidationError(`${name} must be the ${what} id a list tool returned`);
+ return value.trim();
+}
diff --git a/backend/mcp/tool.ts b/backend/mcp/tool.ts
new file mode 100644
index 0000000..2accdd4
--- /dev/null
+++ b/backend/mcp/tool.ts
@@ -0,0 +1,55 @@
+import type { Services } from '../container.ts';
+import type { McpPrincipal } from '../services/mcpAccessService.ts';
+import type { Fields } from '../validators/fields.ts';
+import type { McpPermission } from '../../shared/types/mcp.ts';
+
+// a JSON Schema object as tools/list publishes it; the parse function is what actually enforces it
+export type JsonSchema = Record<string, unknown>;
+
+// hints for the client; the server enforces permission and confirmation itself and never relies on them
+export interface ToolAnnotations {
+ readOnlyHint: boolean;
+ destructiveHint: boolean;
+ idempotentHint: boolean;
+ // true when the result holds text other people wrote, such as captions, titles and comments
+ openWorldHint: boolean;
+}
+
+export interface ToolContext {
+ services: Services;
+ principal: McpPrincipal;
+}
+
+// one MCP tool: what it is called, what it accepts, and the single service call it makes
+export interface McpTool<Input> {
+ name: string;
+ title: string;
+ description: string;
+ inputSchema: JsonSchema;
+ annotations: ToolAnnotations;
+ permission: McpPermission;
+ // irreversible or public actions run only on a second call carrying the confirmation token from the first
+ needsConfirmation?(input: Input): boolean;
+ // what the person is asked to confirm, in one plain sentence
+ describe?(input: Input): string;
+ // the same validators the REST API uses; a ValidationError becomes a tool error the model can correct
+ parse(args: Fields): Input;
+ run(input: Input, context: ToolContext): Promise<unknown>;
+}
+
+// method signatures let a tool for one input type sit in a list of McpTool<unknown>; parse is what makes the input safe
+export type AnyTool = McpTool<unknown>;
+
+export function defineTool<Input>(tool: McpTool<Input>): AnyTool {
+ return tool;
+}
+
+export const READ_ONLY: ToolAnnotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+
+// a list result holds at most this many items, with a cursor for the rest, so one call stays far below the
+// 25,000 token limit Claude Code puts on a tool result
+export const MAX_PAGE_SIZE = 50;
+
+export function noInput(): JsonSchema {
+ return { type: 'object', properties: {}, additionalProperties: false };
+}
diff --git a/backend/services/mcpService.ts b/backend/services/mcpService.ts
new file mode 100644
index 0000000..633d692
--- /dev/null
+++ b/backend/services/mcpService.ts
@@ -0,0 +1,162 @@
+import {
+ RPC_ERROR, checkEnvelope, discoverResult, eraResult, errorReply, initializeResult, isReply, methodNotFound, parseMessage,
+ requestEra, resultReply,
+} from '../lib/mcp/protocol.ts';
+import { CONFIRMATION_TTL_MS, createConfirmation, verifyConfirmation } from '../lib/mcp/confirmation.ts';
+import { canWrite } from '../lib/mcp/accessToken.ts';
+import { AppError } from '../lib/errors.ts';
+import { errorFields } from '../lib/logger.ts';
+import type { Era, JsonObject, McpHeaders, McpReply, RpcMessage, ServerIdentity } from '../lib/mcp/protocol.ts';
+import type { AnyTool } from '../mcp/tool.ts';
+import type { Services } from '../container.ts';
+import type { McpPrincipal } from './mcpAccessService.ts';
+import type { AuditRepository } from '../repositories/auditRepository.ts';
+import type { McpConfig } from '../lib/config.ts';
+import type { RequestContext } from '../types/context.ts';
+
+export interface McpServiceDeps {
+ tools: readonly AnyTool[];
+ services: Services;
+ principal: McpPrincipal;
+ audit: AuditRepository;
+ config: McpConfig;
+ server: ServerIdentity;
+ context: RequestContext;
+}
+
+export interface McpService {
+ handle(body: unknown, headers: McpHeaders): Promise<McpReply>;
+}
+
+// a tool past this has stalled on a platform; Claude's own limit is 240 seconds and the Worker's request deadline 30
+const TOOL_TIMEOUT_MS = 25_000;
+// about 10,000 tokens, where Claude Code starts warning; list tools page well below it
+export const MAX_RESULT_CHARS = 40_000;
+
+class ToolTimeoutError extends Error {}
+
+function withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const timeout = new Promise<never>((_, reject) => {
+ timer = setTimeout(() => reject(new ToolTimeoutError()), ms);
+ });
+ return Promise.race([work, timeout]).finally(() => {
+ if (timer !== undefined) clearTimeout(timer);
+ });
+}
+
+function toolResult(era: Era, structured: unknown, isError = false): JsonObject {
+ const text = typeof structured === 'string' ? structured : JSON.stringify(structured);
+ const result: JsonObject = { content: [{ type: 'text', text }], isError };
+ if (!isError && typeof structured === 'object' && structured !== null && !Array.isArray(structured)) result.structuredContent = structured;
+ return eraResult(era, result);
+}
+
+function toolError(era: Era, message: string): JsonObject {
+ return toolResult(era, message, true);
+}
+
+function definition(tool: AnyTool): JsonObject {
+ return { name: tool.name, title: tool.title, description: tool.description, inputSchema: tool.inputSchema, annotations: { title: tool.title, ...tool.annotations } };
+}
+
+// one JSON-RPC request in, one reply out; tools see only the caller's own data through the same services the app uses
+export function createMcpService({ tools, services, principal, audit, config, server, context }: McpServiceDeps): McpService {
+ const { log } = context;
+ const visible = tools.filter(tool => tool.permission === 'read' || canWrite(principal.permission));
+
+ async function record(tool: AnyTool, outcome: string): Promise<void> {
+ const subjectType = principal.via.startsWith('token:') ? 'mcp_access_token' : 'mcp_client';
+ try {
+ await audit.recordForUser(principal.userId, {
+ action: `${subjectType}.called_tool`, subjectType, subjectId: principal.via.slice(principal.via.indexOf(':') + 1), details: { tool: tool.name, outcome },
+ });
+ } catch (err) {
+ log.warn('could not record an MCP tool call', { tool: tool.name, ...errorFields(err) });
+ }
+ }
+
+ // the first call returns what will happen and a token; only a second call with the same arguments and that token runs it
+ async function confirmation(tool: AnyTool, input: unknown, args: JsonObject, era: Era): Promise<JsonObject | null> {
+ if (!tool.needsConfirmation?.(input)) return null;
+ const secret = config.signingSecret;
+ if (!secret) return toolError(era, 'This action needs a confirmation, which the server cannot sign until its owner sets the TOKEN_ENCRYPTION_KEY Worker secret.');
+ const subject = { userId: principal.userId, tool: tool.name, args };
+ if (await verifyConfirmation(args.confirmationToken, subject, secret)) return null;
+ return toolResult(era, {
+ status: 'confirmation_required',
+ action: tool.describe?.(input) ?? `Run ${tool.title}`,
+ confirmationToken: await createConfirmation(subject, secret),
+ expiresInSeconds: CONFIRMATION_TTL_MS / 1000,
+ instructions: 'Show the action to the person. Only if they agree, call this tool again with the same arguments plus confirmationToken.',
+ });
+ }
+
+ async function callTool(message: RpcMessage, era: Era): Promise<McpReply> {
+ const { name, arguments: rawArgs = {} } = message.params;
+ if (typeof name !== 'string') return errorReply(message.id, RPC_ERROR.invalidParams, 'tools/call needs the tool name in params.name.', era.kind === 'modern' ? 400 : 200);
+ if (typeof rawArgs !== 'object' || rawArgs === null || Array.isArray(rawArgs)) {
+ return errorReply(message.id, RPC_ERROR.invalidParams, 'Tool arguments must be an object.', era.kind === 'modern' ? 400 : 200);
+ }
+ const args = rawArgs as JsonObject;
+ const tool = visible.find(candidate => candidate.name === name);
+ if (!tool) {
+ const hidden = tools.some(candidate => candidate.name === name);
+ if (hidden) return resultReply(message.id, toolError(era, 'This connection may only read. To let Claude make changes, allow changes for this client or token in Twiligent, Settings, Claude.'));
+ return errorReply(message.id, RPC_ERROR.invalidParams, `Unknown tool: ${name}`, era.kind === 'modern' ? 400 : 200);
+ }
+
+ let input: unknown;
+ try {
+ input = tool.parse(args);
+ } catch (err) {
+ if (err instanceof AppError) return resultReply(message.id, toolError(era, err.message));
+ throw err;
+ }
+
+ const pending = await confirmation(tool, input, args, era);
+ if (pending) return resultReply(message.id, pending);
+
+ try {
+ const structured = await withTimeout(tool.run(input, { services, principal }), TOOL_TIMEOUT_MS);
+ const result = toolResult(era, structured);
+ const size = JSON.stringify(result.content).length;
+ if (size > MAX_RESULT_CHARS) return resultReply(message.id, toolError(era, 'The result is too large to return at once. Ask for fewer items with limit, or narrow the request.'));
+ if (tool.permission === 'write') await record(tool, 'done');
+ return resultReply(message.id, result);
+ } catch (err) {
+ if (tool.permission === 'write') await record(tool, 'failed');
+ if (err instanceof AppError) return resultReply(message.id, toolError(era, err.message));
+ if (err instanceof ToolTimeoutError) return resultReply(message.id, toolError(era, 'The tool took too long and was stopped. Check whether the change happened before trying again.'));
+ log.error('mcp tool failed', { tool: tool.name, ...errorFields(err) });
+ return resultReply(message.id, toolError(era, `The tool failed unexpectedly. Quote request id ${context.requestId} when reporting it.`));
+ }
+ }
+
+ return {
+ async handle(body, headers) {
+ const parsed = parseMessage(body);
+ if (isReply(parsed)) return parsed;
+ const era = requestEra(parsed, headers);
+ const refused = checkEnvelope(parsed, era, headers);
+ if (refused) return refused;
+ // a notification needs no answer, and this server keeps no state for one to change
+ if (parsed.id === null) return { status: 202, body: null };
+
+ switch (parsed.method) {
+ case 'initialize':
+ return resultReply(parsed.id, initializeResult(parsed.params, server));
+ case 'ping':
+ return resultReply(parsed.id, eraResult(era, {}));
+ case 'server/discover':
+ return resultReply(parsed.id, discoverResult(server));
+ case 'tools/list':
+ return resultReply(parsed.id, eraResult(era, { tools: visible.map(definition) }, true));
+ case 'tools/call':
+ return callTool(parsed, era);
+ default:
+ return methodNotFound(parsed, era);
+ }
+ },
+ };
+}
diff --git a/backend/tests/services/mcpService.test.ts b/backend/tests/services/mcpService.test.ts
new file mode 100644
index 0000000..f5cc6ed
--- /dev/null
+++ b/backend/tests/services/mcpService.test.ts
@@ -0,0 +1,142 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { MAX_RESULT_CHARS, createMcpService } from '../../services/mcpService.ts';
+import { createAuditRepository } from '../../repositories/auditRepository.ts';
+import { readMcpConfig } from '../../lib/config.ts';
+import { createLogger } from '../../lib/logger.ts';
+import { NotFoundError, ValidationError } from '../../lib/errors.ts';
+import { MODERN_VERSION } from '../../lib/mcp/protocol.ts';
+import { READ_ONLY, defineTool, noInput } from '../../mcp/tool.ts';
+import { fakeSupabase } from '../fixtures/fakeSupabase.ts';
+import type { Services } from '../../container.ts';
+import type { McpPermission } from '../../../shared/types/mcp.ts';
+import type { Env } from '../../types/env.ts';
+
+const SECRET = 'k'.repeat(40);
+const ran: string[] = [];
+
+const readTool = defineTool<Record<string, never>>({
+ name: 'read_thing', title: 'Read a thing', description: 'Reads.', inputSchema: noInput(), annotations: READ_ONLY, permission: 'read',
+ parse: () => ({}),
+ run: async () => ({ ok: true }),
+});
+
+const deleteTool = defineTool<{ id: string }>({
+ name: 'delete_thing', title: 'Delete a thing', description: 'Deletes.', inputSchema: noInput(),
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, permission: 'write',
+ needsConfirmation: () => true,
+ describe: ({ id }) => `Delete ${id}.`,
+ parse(args) {
+ if (typeof args.id !== 'string') throw new ValidationError('id is required');
+ return { id: args.id };
+ },
+ async run({ id }) {
+ if (id === 'missing') throw new NotFoundError('No thing with that id.');
+ if (id === 'boom') throw new Error('database password is hunter2');
+ if (id === 'huge') return { text: 'x'.repeat(MAX_RESULT_CHARS) };
+ ran.push(id);
+ return { deleted: id };
+ },
+});
+
+function setup(permission: McpPermission = 'write', env: Partial<Env> = { TOKEN_ENCRYPTION_KEY: SECRET }) {
+ const db = fakeSupabase();
+ const service = createMcpService({
+ tools: [readTool, deleteTool],
+ services: {} as Services,
+ principal: { userId: 'user-1', permission, via: 'token:t1' },
+ audit: createAuditRepository(db),
+ config: readMcpConfig(env as Env),
+ server: { name: 'twiligent', title: 'Twiligent', version: '2.0.0', instructions: 'Use the tools.' },
+ context: { requestId: 'req-42', signal: new AbortController().signal, log: createLogger() },
+ });
+ const call = (name: string, args: Record<string, unknown> = {}) => service.handle({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, {});
+ return { db, service, call };
+}
+
+function result(reply: { body: unknown }): Record<string, unknown> {
+ return (reply.body as { result: Record<string, unknown> }).result;
+}
+
+function text(reply: { body: unknown }): string {
+ return (result(reply).content as { text: string }[])[0].text;
+}
+
+test('a read-only caller sees only read tools and is told how to allow changes when it calls a write tool', async () => {
+ const { service, call } = setup('read');
+ const list = await service.handle({ jsonrpc: '2.0', id: 1, method: 'tools/list' }, {});
+ assert.deepEqual((result(list).tools as { name: string }[]).map(tool => tool.name), ['read_thing']);
+ const reply = await call('delete_thing', { id: 'a' });
+ assert.equal(result(reply).isError, true);
+ assert.match(text(reply), /may only read/);
+});
+
+test('a write tool that needs confirmation runs only on a second call carrying the token for the same arguments', async () => {
+ const { call, db } = setup();
+ const first = await call('delete_thing', { id: 'a' });
+ const pending = result(first).structuredContent as { status: string; action: string; confirmationToken: string };
+ assert.equal(pending.status, 'confirmation_required');
+ assert.equal(pending.action, 'Delete a.');
+ assert.deepEqual(ran, []);
+
+ const other = await call('delete_thing', { id: 'b', confirmationToken: pending.confirmationToken });
+ assert.equal((result(other).structuredContent as { status: string }).status, 'confirmation_required');
+ assert.deepEqual(ran, []);
+
+ const confirmed = await call('delete_thing', { id: 'a', confirmationToken: pending.confirmationToken });
+ assert.deepEqual(result(confirmed).structuredContent, { deleted: 'a' });
+ assert.deepEqual(ran, ['a']);
+ assert.deepEqual(db.table.filter(row => row._table === 'audit_events').map(row => row.action), ['mcp_access_token.called_tool']);
+});
+
+test('without a signing secret a tool that needs confirmation refuses instead of running', async () => {
+ const { call } = setup('write', {});
+ const reply = await call('delete_thing', { id: 'a' });
+ assert.equal(result(reply).isError, true);
+ assert.match(text(reply), /TOKEN_ENCRYPTION_KEY/);
+});
+
+test('bad input and app errors come back as tool errors the model can act on; other errors never leak their message', async () => {
+ const { call } = setup();
+ assert.equal(text(await call('delete_thing', {})), 'id is required');
+ const confirmedCall = async (id: string) => {
+ const first = await call('delete_thing', { id });
+ const token = (result(first).structuredContent as { confirmationToken: string }).confirmationToken;
+ return call('delete_thing', { id, confirmationToken: token });
+ };
+ assert.equal(text(await confirmedCall('missing')), 'No thing with that id.');
+ const boom = await confirmedCall('boom');
+ assert.equal(result(boom).isError, true);
+ assert.doesNotMatch(text(boom), /hunter2/);
+ assert.match(text(boom), /req-42/);
+ assert.match(text(await confirmedCall('huge')), /too large/);
+});
+
+test('an unknown tool or non-object arguments are protocol errors', async () => {
+ const { service, call } = setup();
+ const unknown = await call('nope');
+ assert.equal((unknown.body as { error: { code: number } }).error.code, -32602);
+ const bad = await service.handle({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'read_thing', arguments: [1] } }, {});
+ assert.equal((bad.body as { error: { code: number } }).error.code, -32602);
+});
+
+test('initialize, ping and notifications work for legacy clients without any session', async () => {
+ const { service } = setup();
+ const init = await service.handle({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-11-25' } }, {});
+ assert.equal(result(init).protocolVersion, '2025-11-25');
+ assert.deepEqual(result(await service.handle({ jsonrpc: '2.0', id: 2, method: 'ping' }, { protocolVersion: '2025-11-25' })), {});
+ const note = await service.handle({ jsonrpc: '2.0', method: 'notifications/initialized' }, { protocolVersion: '2025-11-25' });
+ assert.deepEqual(note, { status: 202, body: null });
+});
+
+test('a modern call is served statelessly and marked complete', async () => {
+ const { service } = setup();
+ const meta = { _meta: { 'io.modelcontextprotocol/protocolVersion': MODERN_VERSION } };
+ const reply = await service.handle(
+ { jsonrpc: '2.0', id: 'a', method: 'tools/call', params: { name: 'read_thing', arguments: {}, ...meta } },
+ { protocolVersion: MODERN_VERSION, method: 'tools/call', name: 'read_thing' },
+ );
+ assert.equal(reply.status, 200);
+ assert.equal(result(reply).resultType, 'complete');
+ assert.deepEqual(result(reply).structuredContent, { ok: true });
+});