@zetaloop/chappie 0.1.0

package/src/resources.ts

@@ -0,0 +1,189 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import mime from "mime";
+
+export interface ResourceDescriptor {
+	uri: string;
+	name: string;
+	mimeType: string;
+	size: number;
+}
+
+export interface ResourceData extends ResourceDescriptor {
+	blob: string;
+}
+
+type ResourceEntry =
+	| { type: "file"; path: string; descriptor: ResourceDescriptor }
+	| { type: "image"; data: string; descriptor: ResourceDescriptor };
+
+const stores = new Map<string, Map<string, ResourceEntry>>();
+
+export async function registerFile(
+	sessionId: string,
+	path: string,
+): Promise<ResourceDescriptor> {
+	const info = await stat(path);
+	if (!info.isFile()) throw new Error(`${path} is not a file`);
+	const name = basename(path);
+	const descriptor = resourceDescriptor(
+		sessionId,
+		"file",
+		randomUUID(),
+		name,
+		mime.getType(path) ?? "application/octet-stream",
+		info.size,
+	);
+	store(sessionId).set(descriptor.uri, { type: "file", path, descriptor });
+	return descriptor;
+}
+
+export function rememberImages(
+	sessionId: string,
+	content: readonly (TextContent | ImageContent)[],
+): void {
+	for (const block of content) {
+		if (block.type !== "image") continue;
+		const descriptor = imageDescriptor(sessionId, block);
+		store(sessionId).set(descriptor.uri, {
+			type: "image",
+			data: block.data,
+			descriptor,
+		});
+	}
+}
+
+export function imageDescriptor(
+	sessionId: string,
+	image: ImageContent,
+): ResourceDescriptor {
+	const digest = createHash("sha256")
+		.update(image.data, "base64")
+		.digest("hex");
+	const extension = mime.getExtension(image.mimeType) ?? "bin";
+	return resourceDescriptor(
+		sessionId,
+		"image",
+		digest,
+		`image.${extension}`,
+		image.mimeType,
+		Buffer.byteLength(image.data, "base64"),
+	);
+}
+
+export function contentWithImageReferences(
+	sessionId: string,
+	content: readonly (TextContent | ImageContent)[],
+): (TextContent | ImageContent)[] {
+	return content.flatMap((block) =>
+		block.type === "image"
+			? [
+					block,
+					{
+						type: "text" as const,
+						text: JSON.stringify({
+							piImage: imageDescriptor(sessionId, block).uri,
+						}),
+					},
+				]
+			: [block],
+	);
+}
+
+export function resourceDescriptors(details: unknown): ResourceDescriptor[] {
+	if (!details || typeof details !== "object") return [];
+	const resources = (details as { resources?: unknown }).resources;
+	if (!Array.isArray(resources)) return [];
+	return resources.filter((resource): resource is ResourceDescriptor => {
+		if (!resource || typeof resource !== "object") return false;
+		const value = resource as Partial<ResourceDescriptor>;
+		return (
+			typeof value.uri === "string" &&
+			typeof value.name === "string" &&
+			typeof value.mimeType === "string" &&
+			typeof value.size === "number"
+		);
+	});
+}
+
+export function describeResource(
+	sessionId: string,
+	uri: string,
+): ResourceDescriptor {
+	const parsed = parseResourceUri(uri);
+	if (parsed.sessionId !== sessionId) {
+		throw new Error("The resource belongs to another Pi session");
+	}
+	const entry = store(sessionId).get(uri);
+	if (!entry) throw new Error(`Unknown Chappie resource: ${uri}`);
+	return entry.descriptor;
+}
+
+export async function readSessionResource(
+	sessionId: string,
+	uri: string,
+): Promise<ResourceData> {
+	const descriptor = describeResource(sessionId, uri);
+	const entry = store(sessionId).get(uri);
+	if (!entry) throw new Error(`Unknown Chappie resource: ${uri}`);
+	const blob =
+		entry.type === "file"
+			? (await readFile(entry.path)).toString("base64")
+			: entry.data;
+	return { ...descriptor, blob };
+}
+
+export function resourceSessionId(uri: string): string {
+	return parseResourceUri(uri).sessionId;
+}
+
+function store(sessionId: string): Map<string, ResourceEntry> {
+	let resources = stores.get(sessionId);
+	if (!resources) {
+		resources = new Map();
+		stores.set(sessionId, resources);
+	}
+	return resources;
+}
+
+function resourceDescriptor(
+	sessionId: string,
+	kind: "file" | "image",
+	id: string,
+	name: string,
+	mimeType: string,
+	size: number,
+): ResourceDescriptor {
+	return {
+		uri: `chappie://session/${encodeURIComponent(sessionId)}/${kind}/${encodeURIComponent(id)}/${encodeURIComponent(name)}`,
+		name,
+		mimeType,
+		size,
+	};
+}
+
+function parseResourceUri(uri: string): {
+	sessionId: string;
+	kind: string;
+	id: string;
+	name: string;
+} {
+	const parsed = new URL(uri);
+	if (parsed.protocol !== "chappie:" || parsed.hostname !== "session") {
+		throw new Error(`Unsupported Chappie resource: ${uri}`);
+	}
+	const parts = parsed.pathname
+		.slice(1)
+		.split("/")
+		.map((part) => decodeURIComponent(part));
+	if (parts.length !== 4 || !parts.every(Boolean)) {
+		throw new Error(`Invalid Chappie resource: ${uri}`);
+	}
+	const [sessionId, kind, id, name] = parts;
+	if (!sessionId || !kind || !id || !name) {
+		throw new Error(`Invalid Chappie resource: ${uri}`);
+	}
+	return { sessionId, kind, id, name };
+}

package/src/server.ts

@@ -0,0 +1,296 @@
+import { readFileSync } from "node:fs";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
+import * as z from "zod";
+import packageJson from "../package.json" with { type: "json" };
+import type { Broker } from "./broker.ts";
+import { deliveryContent } from "./delivery.ts";
+import {
+	directTools,
+	inputContent,
+	type ToolInput,
+	toolResult,
+} from "./tools.ts";
+
+const instructions = readFileSync(
+	new URL("./instructions.md", import.meta.url),
+	"utf8",
+).trim();
+
+interface RequestContext {
+	mcpReq: {
+		_meta?: Record<string, unknown>;
+		signal: AbortSignal;
+	};
+}
+
+export function createServer(broker: Broker): McpServer {
+	const server = new McpServer(
+		{
+			name: "chappie",
+			version: packageJson.version,
+		},
+		{ instructions },
+	);
+
+	server.registerTool(
+		"init",
+		{
+			title: "Connect to Pi",
+			description: "Connect this ChatGPT conversation to a Pi session.",
+			inputSchema: z.object({
+				sessionId: z
+					.string()
+					.optional()
+					.describe("Pi session to select explicitly"),
+			}),
+			annotations: {
+				openWorldHint: false,
+			},
+		},
+		async (args, context) => {
+			const chatId = requireChatId(context);
+			const { inputs, ...initialized } = await broker.initialize(
+				chatId,
+				args.sessionId,
+				context.mcpReq.signal,
+			);
+			return finishResult(broker, context, textResult(initialized, inputs));
+		},
+	);
+
+	server.registerTool(
+		"chat",
+		{
+			title: "Reply in Pi",
+			description: "Send one complete assistant message to a Pi session.",
+			inputSchema: z.object({
+				text: z.string().min(1).describe("Assistant message to display in Pi"),
+				sessionId: z
+					.string()
+					.optional()
+					.describe("Pi session for this operation only"),
+			}),
+			annotations: {
+				openWorldHint: false,
+			},
+		},
+		async (args, context) => {
+			const chatId = requireChatId(context);
+			const { message, inputs } = await broker.chat(
+				chatId,
+				args.sessionId,
+				args.text,
+				context.mcpReq.signal,
+			);
+			return finishResult(broker, context, textResult({ message }, inputs));
+		},
+	);
+
+	server.registerTool(
+		"tools",
+		{
+			title: "Pi tools",
+			description: "List the tools currently active in a Pi session.",
+			inputSchema: z.object({
+				sessionId: z
+					.string()
+					.optional()
+					.describe("Pi session for this operation only"),
+			}),
+			annotations: {
+				readOnlyHint: true,
+				idempotentHint: true,
+				openWorldHint: false,
+			},
+		},
+		async (args, context) => {
+			const { inputs, ...inspected } = await broker.tools(
+				requireChatId(context),
+				args.sessionId,
+				context.mcpReq.signal,
+			);
+			return finishResult(
+				broker,
+				context,
+				textResult(
+					{ session: inspected.session, tools: inspected.tools },
+					inputs,
+				),
+			);
+		},
+	);
+
+	server.registerTool(
+		"call",
+		{
+			title: "Call Pi tools",
+			description: "Execute one or more tools as a native Pi tool batch.",
+			inputSchema: z.object({
+				calls: z
+					.array(
+						z.object({
+							name: z.string(),
+							arguments: z.record(z.string(), z.unknown()),
+						}),
+					)
+					.min(1),
+				sessionId: z
+					.string()
+					.optional()
+					.describe("Pi session for this operation only"),
+			}),
+			annotations: {
+				openWorldHint: true,
+			},
+		},
+		async (args, context) => {
+			const result = await broker.call(
+				requireChatId(context),
+				args.sessionId,
+				args.calls,
+				context.mcpReq.signal,
+			);
+			return finishResult(
+				broker,
+				context,
+				toolResult(result.toolResults, result.sessionId, result.inputs),
+			);
+		},
+	);
+
+	for (const tool of directTools) {
+		server.registerTool(
+			tool.name,
+			{
+				title: tool.name,
+				description: tool.description,
+				inputSchema: tool.inputSchema,
+				annotations: {
+					readOnlyHint: tool.name === "read",
+					idempotentHint: tool.name === "read",
+					openWorldHint: tool.name === "bash",
+				},
+				...(tool.fileParams
+					? { _meta: { "openai/fileParams": tool.fileParams } }
+					: {}),
+			},
+			async (args, context) => {
+				const input = { ...args } as Record<string, unknown> & {
+					sessionId?: string;
+				};
+				const sessionId = input.sessionId;
+				delete input.sessionId;
+				const calls: ToolInput[] = [{ name: tool.name, arguments: input }];
+				const result = await broker.call(
+					requireChatId(context),
+					sessionId,
+					calls,
+					context.mcpReq.signal,
+				);
+				return finishResult(
+					broker,
+					context,
+					toolResult(result.toolResults, result.sessionId, result.inputs),
+				);
+			},
+		);
+	}
+
+	server.registerTool(
+		"sessions",
+		{
+			title: "Local sessions",
+			description:
+				"List connected Pi sessions and the current conversation binding.",
+			inputSchema: z.object({
+				sessionId: z
+					.string()
+					.optional()
+					.describe("Return only this Pi session when it is online"),
+			}),
+			annotations: {
+				readOnlyHint: true,
+				idempotentHint: true,
+				openWorldHint: false,
+			},
+		},
+		async (args, context) => {
+			const chatId = requestChatId(context);
+			const inputs = chatId
+				? await broker.inputs(chatId, args.sessionId, context.mcpReq.signal)
+				: [];
+			const result = textResult(
+				{
+					binding: chatId ? (broker.binding(chatId) ?? null) : null,
+					sessions: broker.listSessions(args.sessionId),
+				},
+				inputs,
+			);
+			return chatId ? finishResult(broker, context, result) : result;
+		},
+	);
+
+	server.registerResource(
+		"Pi resource",
+		new ResourceTemplate("chappie://session/{sessionId}/{kind}/{id}/{name}", {
+			list: undefined,
+		}),
+		{ title: "Pi resource" },
+		async (uri, _variables, context) => {
+			const resource = await broker.readResource(
+				uri.href,
+				context.mcpReq.signal,
+			);
+			return {
+				contents: [
+					{
+						uri: resource.uri,
+						mimeType: resource.mimeType,
+						blob: resource.blob,
+					},
+				],
+			};
+		},
+	);
+
+	return server;
+}
+
+function textResult(
+	value: unknown,
+	inputs: Parameters<typeof inputContent>[0] = [],
+) {
+	return {
+		content: [
+			{ type: "text" as const, text: JSON.stringify(value) },
+			...inputContent(inputs),
+		],
+	};
+}
+
+async function finishResult<T extends { content: object[] }>(
+	broker: Broker,
+	context: RequestContext,
+	result: T,
+): Promise<T> {
+	const chatId = requireChatId(context);
+	const deliveries = await broker.deliveries(chatId);
+	const completed = {
+		...result,
+		content: [...result.content, ...deliveryContent(deliveries)],
+	} as T;
+	await broker.acknowledgeDeliveries(deliveries, context.mcpReq.signal);
+	return completed;
+}
+
+function requestChatId(context: RequestContext): string | undefined {
+	const value = context.mcpReq._meta?.["openai/session"];
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function requireChatId(context: RequestContext): string {
+	const chatId = requestChatId(context);
+	if (!chatId)
+		throw new Error("ChatGPT did not provide openai/session metadata");
+	return chatId;
+}