stitchery

Module: Stitchery

Generated by Cicadas Bootstrap on 2026-03-22.

Purpose

Stitchery (@aprovan/stitchery) is the backend server that aggregates external tool providers (MCP servers, UTCP clients) into a unified service registry and exposes them via HTTP endpoints. It provides LLM chat and edit capabilities, a service proxy for widget-to-backend communication, and a CLI for local development startup.

Interfaces

Exports:

• Server startup and configuration
• CLI entry point (cli.ts)
• System prompts for AI endpoints (prompts.ts)

HTTP Endpoints:

• POST /api/chat — LLM chat completion with tool use (streams responses)
• POST /api/edit — AI-driven code editing endpoint
• GET /api/proxy/{namespace}/{procedure} — Service proxy (GET with query params)
• POST /api/proxy/{namespace}/{procedure} — Service proxy (POST with body)
• VFS routes for file management

Dependencies:

• MCP SDK — For connecting to MCP tool servers
• UTCP client — For connecting to UTCP tool providers
• AI/LLM SDK — For chat and edit endpoints
• @aprovan/patchwork — ServiceBackend interface

Subsystems

Server

• server/index.ts — HTTP server setup, middleware, route registration
• server/routes.ts — Core API routes (chat, edit, proxy)
• server/services.ts — ServiceRegistry: discovers and registers tools from MCP/UTCP sources; routes proxy calls to the correct backend
• server/vfs-routes.ts — VFS HTTP endpoints for remote file operations
• server/local-packages.ts — Local package discovery for development mode

CLI

• cli.ts — Command-line interface for starting the Stitchery server with configuration options

Prompts

• prompts.ts — System prompt templates for LLM chat and edit endpoints

Key Decisions

• Service aggregation pattern: Stitchery collects tools from multiple heterogeneous sources (MCP, UTCP) into a single registry, presenting a uniform namespace-based API to widgets.
• Proxy routing: Widget service calls arrive as HTTP requests to /api/proxy/{namespace}/{procedure} and are routed to the appropriate registered backend — widgets never communicate directly with tool servers.
• Embedded mode for VS Code: The Stitchery server can be started in-process within the VS Code extension (EmbeddedStitchery), avoiding a separate server process during development.