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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 });+});