Files
gods-eye-view/src/tools/mcp/protocol.js
T
Sameh Khamis 996b95eb45 Load the God's Eye View panel through the MCP server
Hosts serve panels from their own sites and may refuse other addresses;
Codex refuses any address on the user's machine. The panel now never
requests the app's server: it loads the app's panel build and data
through panel_request, a tool only the panel may call, which requests
the path from the app's server. One path in every host; only map
providers load directly.

npm run build:panel writes the panel build to dist/panel, served at
/panel/: one app script, one stylesheet, Cesium's script, and Cesium's
workers as one script Cesium runs from memory. Tools may now be marked
app-only. The panel CORS rules are gone.
2026-10-02 18:29:42 -07:00

218 lines
7.1 KiB
JavaScript

/**
* 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);
}