Skip to content

A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.

7.1 KB
Raw Blame
/**
 * Model Context Protocol server for a tool catalog: JSON-RPC 2.0 handling of
 * initialize, ping, tools/list and tools/call, and resources/list and
 * resources/read for the resources an application supplies, such as MCP Apps
 * views (`ui://` resources) that tools name in `_meta.ui.resourceUri`. Transports (HTTP, stdio) pass
 * parsed messages in and send the returned responses out.
 */

import { ToolError } from '../catalog.js';

/** Protocol revisions this server implements, newest first. */
export const MCP_PROTOCOL_VERSIONS = Object.freeze([
  '2025-11-25',
  '2025-06-18',
  '2025-03-26',
]);

const PARSE_ERROR = -32700;
const INVALID_REQUEST = -32600;
const METHOD_NOT_FOUND = -32601;
const INVALID_PARAMS = -32602;
const INTERNAL_ERROR = -32603;
const RESOURCE_NOT_FOUND = -32002;

/**
 * Describe catalog tools as MCP tool definitions.
 *
 * `descriptions` may override a tool's `title` and `description` by name.
 * `decorate(definition, tool)` may return extra fields to merge into each
 * definition, such as application metadata.
 */
export function toMcpTools(catalog, { descriptions = {}, decorate } = {}) {
  return catalog.list().map((tool) => {
    const override = descriptions[tool.name] || {};
    const title = override.title ?? tool.title;
    const definition = {
      name: tool.name,
      title,
      description: override.description ?? tool.description,
      inputSchema: tool.inputSchema,
      annotations: { title, ...tool.annotations },
      ...(tool.ui
        ? {
            _meta: {
              ui: { ...tool.ui },
              // The flat key is the earlier form of the same field, which
              // some hosts still read; the MCP Apps SDK sends both.
              ...(tool.ui.resourceUri
                ? { 'ui/resourceUri': tool.ui.resourceUri }
                : {}),
            },
          }
        : {}),
    };
    return decorate
      ? { ...definition, ...decorate(definition, tool) }
      : definition;
  });
}

/**
 * Create a protocol handler. `handle(message, { signal })` resolves to the
 * JSON-RPC response, or null for notifications.
 */
export function createMcpServer({
  catalog,
  name,
  version,
  instructions,
  descriptions,
  decorate,
  resources = [],
}) {
  const tools = () => toMcpTools(catalog, { descriptions, decorate });
  const resourceByUri = new Map(
    resources.map((resource) => [resource.uri, resource]),
  );
  const methods = {
    initialize(params) {
      const requested = params?.protocolVersion;
      return {
        protocolVersion: MCP_PROTOCOL_VERSIONS.includes(requested)
          ? requested
          : MCP_PROTOCOL_VERSIONS[0],
        capabilities: {
          tools: { listChanged: false },
          ...(resources.length ? { resources: { listChanged: false } } : {}),
        },
        serverInfo: { name, version },
        ...(instructions ? { instructions } : {}),
      };
    },
    ping: () => ({}),
    'tools/list': () => ({ tools: tools() }),
    'resources/list': () => ({
      resources: resources.map(({ text, ...entry }) => entry),
    }),
    'resources/read'(params) {
      const resource = resourceByUri.get(params?.uri);
      if (!resource)
        throw rpcError(RESOURCE_NOT_FOUND, `Unknown resource: ${params?.uri}`);
      const { uri, mimeType, text, _meta } = resource;
      return {
        contents: [{ uri, mimeType, text, ...(_meta ? { _meta } : {}) }],
      };
    },
    async 'tools/call'(params, { signal }) {
      if (typeof params?.name !== 'string')
        throw rpcError(INVALID_PARAMS, 'tools/call needs a tool name');
      if (!catalog.get(params.name))
        throw rpcError(INVALID_PARAMS, `Unknown tool: ${params.name}`);
      try {
        const result = await catalog.call(params.name, params.arguments ?? {}, {
          signal,
        });
        // Only an app reads a tool the model cannot call, and apps read
        // structuredContent.
        const appOnly =
          catalog.get(params.name).ui?.visibility?.includes('model') === false;
        return {
          // The data is repeated as JSON text for clients that do not read
          // structuredContent.
          content: [
            { type: 'text', text: result.summary },
            ...(appOnly
              ? []
              : [{ type: 'text', text: JSON.stringify(result.data) }]),
            ...(result.images || []).map((item) => ({
              type: 'image',
              data: item.data,
              mimeType: item.mimeType,
            })),
          ],
          structuredContent: result.data,
          isError: false,
        };
      } catch (error) {
        if (signal?.aborted) throw error;
        // Expected failures are reported to the model so it can adjust; other
        // errors are not described, so internal details never leave the server.
        const known = error instanceof ToolError;
        return {
          content: [
            {
              type: 'text',
              text: known ? error.message : 'The tool failed; try again later',
            },
          ],
          structuredContent: {
            error: known ? error.code : 'unavailable',
            ...(known && error.retryAfterSeconds != null
              ? { retry_after_seconds: error.retryAfterSeconds }
              : {}),
          },
          isError: true,
        };
      }
    },
  };

  return Object.freeze({
    async handle(message, { signal } = {}) {
      if (!isObject(message) || message.jsonrpc !== '2.0')
        return failure(
          message?.id ?? null,
          INVALID_REQUEST,
          'Invalid JSON-RPC message',
        );
      const isRequest = message.id !== undefined;
      if (typeof message.method !== 'string')
        // Responses from the client are accepted and ignored: this server
        // sends no requests of its own.
        return isRequest &&
          message.result === undefined &&
          message.error === undefined
          ? failure(message.id, INVALID_REQUEST, 'Missing method')
          : null;
      if (!isRequest) return null;
      const method = Object.hasOwn(methods, message.method)
        ? methods[message.method]
        : null;
      if (!method)
        return failure(
          message.id,
          METHOD_NOT_FOUND,
          `Unknown method: ${message.method}`,
        );
      if (message.params !== undefined && !isObject(message.params))
        return failure(message.id, INVALID_PARAMS, 'params must be an object');
      try {
        const result = await method(message.params, { signal });
        return { jsonrpc: '2.0', id: message.id, result };
      } catch (error) {
        if (error?.rpcCode)
          return failure(message.id, error.rpcCode, error.message);
        return failure(message.id, INTERNAL_ERROR, 'Internal error');
      }
    },
  });
}

/** A JSON-RPC parse-error response, for transports that cannot parse input. */
export function parseErrorResponse() {
  return failure(null, PARSE_ERROR, 'Parse error');
}

function failure(id, code, message) {
  return { jsonrpc: '2.0', id, error: { code, message } };
}

function rpcError(code, message) {
  return Object.assign(new Error(message), { rpcCode: code });
}

function isObject(value) {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
}