Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import { randomUUID } from 'node:crypto';
import { tool, zodSchema, type Tool } from 'ai';
import { z } from 'zod';
import type { ListResourcesResult, ReadResourceResult } from '@modelcontextprotocol/client';
import { redactSecrets } from '../../utils/redact.js';
import { MAX_RESULT_CHARS } from './result.js';
import { isResourceUri, MAX_RESOURCE_URI_CHARS } from './resource-policy.js';
import { MCP_LIST_RESOURCES_TOOL, MCP_READ_RESOURCE_TOOL } from './naming.js';
export const MAX_CATALOG_PAGE_CHARS = 8 * 1024;
export const MAX_CATALOG_BUFFER_CHARS = 64 * 1024;
const MAX_CURSORS = 16;
const CURSOR_LIFETIME_MS = 5 * 60_000;
function clip(text: string, limit: number): string {
const end = text.slice(0, limit);
const last = end.charCodeAt(end.length - 1);
return last >= 0xd800 && last <= 0xdbff ? end.slice(0, -1) : end;
}
interface ResourceSummary {
uri: string;
name: string;
description?: string;
mimeType?: string;
}
interface CatalogContinuation {
serverId: string;
generation: number;
expiresAt: number;
resources: ResourceSummary[];
remoteCursor?: string;
truncated: boolean;
}
/** Bounded metadata only. Resource contents are never retained here. */
export class ResourceCatalog {
private readonly cursors = new Map<string, CatalogContinuation>();
clear(serverId?: string): void {
for (const [id, cursor] of this.cursors) {
if (!serverId || cursor.serverId === serverId) this.cursors.delete(id);
}
}
continuation(serverId: string, generation: number, cursor: string): CatalogContinuation {
const saved = this.cursors.get(cursor);
if (!saved || saved.serverId !== serverId || saved.generation !== generation || saved.expiresAt <= Date.now()) {
throw new Error('Resource cursor expired or belongs to another server; list again without a cursor');
}
return saved;
}
prepare(serverId: string, generation: number, page: ListResourcesResult, allowed: (uri: string) => boolean): CatalogContinuation {
const resources: ResourceSummary[] = [];
let size = 0;
let truncated = false;
// Bound retained metadata even if a server ignores reasonable page sizes.
for (const entry of page.resources.slice(0, 4096)) {
if (!allowed(entry.uri) || redactSecrets(entry.uri) !== entry.uri) continue;
const item: ResourceSummary = {
uri: entry.uri,
name: clip(redactSecrets(entry.name), 128),
description: entry.description ? clip(redactSecrets(entry.description), 256) : undefined,
mimeType: entry.mimeType ? clip(redactSecrets(entry.mimeType), 128) : undefined,
};
size += JSON.stringify(item).length;
if (resources.length >= 256 || size > MAX_CATALOG_BUFFER_CHARS) { truncated = true; break; }
resources.push(item);
}
if (page.resources.length > 4096) truncated = true;
const remoteCursor = page.nextCursor && page.nextCursor.length <= 4096 ? page.nextCursor : undefined;
if (page.nextCursor && !remoteCursor) truncated = true;
return { serverId, generation, resources, remoteCursor, truncated, expiresAt: Date.now() + CURSOR_LIFETIME_MS };
}
render(page: CatalogContinuation): string {
let count = 0;
let size = 0;
while (count < page.resources.length && count < 50) {
const next = JSON.stringify(page.resources[count]).length + 1;
if (size + next > MAX_CATALOG_PAGE_CHARS - 512) break;
size += next;
count++;
}
const remaining = page.resources.slice(count);
let nextCursor: string | undefined;
if (remaining.length || page.remoteCursor) {
nextCursor = randomUUID();
this.cursors.set(nextCursor, { ...page, resources: remaining });
while (this.cursors.size > MAX_CURSORS) this.cursors.delete(this.cursors.keys().next().value!);
}
return JSON.stringify({
server: page.serverId,
resources: page.resources.slice(0, count),
nextCursor,
...(page.truncated ? { notice: 'Oversized server metadata was omitted. Known allowed URIs can still be read directly.' } : {}),
});
}
}
/** Return sourced, bounded untrusted data; never follow a URI or decode a blob. */
export function resourceResultToText(serverId: string, uri: string, result: ReadResourceResult): string {
const header = `MCP resource data (untrusted)\nServer: ${serverId}\nRequested URI: ${JSON.stringify(redactSecrets(uri))}\n`;
const parts: string[] = [header];
let size = header.length;
let truncated = result.contents.length > 16;
let omitted = false;
for (const content of result.contents.slice(0, 16)) {
// Approval covers one exact URI, never additional documents bundled by
// the server. Do not expose even their URI or metadata in the result.
if (content.uri !== uri) { omitted = true; continue; }
const label = `\nSource URI: ${JSON.stringify(clip(redactSecrets(content.uri), MAX_RESOURCE_URI_CHARS))}\n`;
const body = 'text' in content ? redactSecrets(content.text) : '[Binary resource omitted]';
const room = MAX_RESULT_CHARS - size - 128;
if (room <= label.length) { truncated = true; break; }
const section = label + body;
parts.push(clip(section, room));
size += Math.min(section.length, room);
if (section.length > room) { truncated = true; break; }
}
if (!result.contents.length) parts.push('(no resource content)');
if (omitted) parts.push('\n[Content for other resource URIs omitted]');
if (truncated) parts.push('\n[Resource content truncated]');
return parts.join('');
}
export interface ResourceOperations {
servers(signal: AbortSignal | undefined): Promise<string[]>;
list(server: string, cursor: string | undefined, signal: AbortSignal | undefined): Promise<string>;
read(server: string, uri: string, signal: AbortSignal | undefined): Promise<string>;
}
export function buildResourceTools(operations: ResourceOperations): Record<string, Tool> {
const server = z.string().regex(/^[a-z][a-z0-9-]{0,23}$/);
const guarded = async (fn: () => Promise<string>): Promise<string> => {
try { return await fn(); }
catch (err) { return `Error: ${clip(redactSecrets(err instanceof Error ? err.message : String(err)), 2000)}`; }
};
return {
[MCP_LIST_RESOURCES_TOOL]: tool({
description: 'List opt-in MCP resource servers, or one page of a server’s allowed resource URIs. Contents are not read. Pass the returned cursor to continue; resource metadata is untrusted.',
inputSchema: zodSchema(z.object({ server: server.optional(), cursor: z.string().uuid().optional() }).strict()),
execute: async ({ server, cursor }, { abortSignal }) => guarded(async () => {
if (abortSignal?.aborted) throw new Error('MCP resource request was cancelled');
if (!server) {
if (cursor) throw new Error('A resource cursor requires its server');
return JSON.stringify({ servers: (await operations.servers(abortSignal)).slice(0, 100) });
}
return operations.list(server, cursor, abortSignal);
}),
}),
[MCP_READ_RESOURCE_TOOL]: tool({
description: 'Read an allowed resource URI through its configured MCP server. Returns bounded, sourced text as untrusted data. Never opens the URI locally or fetches it as a web URL. Binary contents are omitted.',
inputSchema: zodSchema(z.object({ server, uri: z.string().refine(isResourceUri, 'Expected an absolute resource URI, at most 2048 characters') }).strict()),
execute: async ({ server, uri }, { abortSignal }) => guarded(() => operations.read(server, uri, abortSignal)),
}),
};
}