RSS3 MCP Server

Instructions

Implementation Reference

• index.js:150-223 (handler)

  This shared handler executes all dynamically generated API tools, including "API-getNodeRewardsByEpoch". It resolves the tool name to an OpenAPI operation and invokes it using the HttpClient, handling responses and errors appropriately.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
  	// console.error("call tool", request.params);
  	const { name, arguments: params } = request.params;
  
  	console.error("name", name);
  
  	if (name === "API-get-input-schema") {
  		for (const mcpToolWithClient of mcpToolWithClients) {
  			for (const [toolName, def] of Object.entries(
  				mcpToolWithClient.mcpTools.tools,
  			)) {
  				for (const method of def.methods) {
  					const toolNameWithMethod = `${toolName}-${method.name}`;
  					const truncatedToolName = toolNameWithMethod.slice(0, 64);
  					if (truncatedToolName === params.toolName) {
  						return {
  							content: [
  								{ type: "text", text: JSON.stringify(method.inputSchema) },
  							],
  						};
  					}
  				}
  			}
  		}
  		throw new Error(`Method ${params.toolName} not found`);
  	}
  
  	// find operation
  	const mcpToolWithClient = mcpToolWithClients.find(
  		(t) => t.mcpTools.openApiLookup[name],
  	);
  	if (!mcpToolWithClient) {
  		throw new Error(`Method ${name} not found`);
  	}
  
  	const operation = mcpToolWithClient.mcpTools.openApiLookup[name];
  
  	// execute
  	try {
  		const response = await mcpToolWithClient.client.executeOperation(
  			operation,
  			params,
  		);
  		return {
  			content: [
  				{
  					type: "text", // currently this is the only type that seems to be used by mcp server
  					text: JSON.stringify(response.data), // TODO: pass through the http status code text?
  				},
  			],
  		};
  	} catch (error) {
  		console.error("Error in tool call", error);
  		if (error instanceof HttpClientError) {
  			console.error(
  				"HttpClientError encountered, returning structured error",
  				error,
  			);
  			const data = error.data?.response?.data ?? error.data ?? {};
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify({
  							status: "error", // TODO: get this from http status code?
  							...(typeof data === "object" ? data : { data: data }),
  						}),
  					},
  				],
  			};
  		}
  		throw error;
  	}
  });

• index.js:100-147 (registration)

  Registers and lists all available tools dynamically from OpenAPI specs. Tool names are constructed as `{toolName}-{method.name}` truncated to 64 characters, which includes "API-getNodeRewardsByEpoch".

  server.setRequestHandler(ListToolsRequestSchema, async () => {
  	console.error("list tools");
  	/**
  	 * @typedef {import("@modelcontextprotocol/sdk/types.js").Tool} Tool
  	 * @type {Tool[]}
  	 */
  	const tools = [];
  
  	for (const mcpToolWithClient of mcpToolWithClients) {
  		for (const [toolName, def] of Object.entries(
  			mcpToolWithClient.mcpTools.tools,
  		)) {
  			for (const method of def.methods) {
  				console.error("method", method);
  				const toolNameWithMethod = `${toolName}-${method.name}`;
  				const truncatedToolName = toolNameWithMethod.slice(0, 64);
  				const trimmedDescription = method.description.split("Error")[0].trim();
  				tools.push({
  					name: truncatedToolName,
  					description: trimmedDescription,
  					inputSchema: {
  						type: "object",
  						properties: {},
  					},
  				});
  			}
  		}
  	}
  
  	tools.unshift({
  		name: "API-get-input-schema",
  		description:
  			"Get the input schema for a given API. We should always use this tool to get the input schema for a given API before calling the API.",
  		inputSchema: {
  			type: "object",
  			properties: {
  				toolName: {
  					type: "string",
  					description: "The name of the tool to get the input schema for",
  				},
  			},
  		},
  	});
  
  	console.error("tools", tools);
  
  	return { tools };
  });

• index.js:156-175 (schema)

  Special handler within the main tool caller that provides the input schema for any tool, including "API-getNodeRewardsByEpoch", by looking it up from the OpenAPI method definition.

  if (name === "API-get-input-schema") {
  	for (const mcpToolWithClient of mcpToolWithClients) {
  		for (const [toolName, def] of Object.entries(
  			mcpToolWithClient.mcpTools.tools,
  		)) {
  			for (const method of def.methods) {
  				const toolNameWithMethod = `${toolName}-${method.name}`;
  				const truncatedToolName = toolNameWithMethod.slice(0, 64);
  				if (truncatedToolName === params.toolName) {
  					return {
  						content: [
  							{ type: "text", text: JSON.stringify(method.inputSchema) },
  						],
  					};
  				}
  			}
  		}
  	}
  	throw new Error(`Method ${params.toolName} not found`);
  }

• index.js:78-84 (helper)

  Helper that converts OpenAPI specifications to MCP tools using OpenAPIToMCPConverter, creating the lookup maps used for tool resolution (openApiLookup). This enables tools like "API-getNodeRewardsByEpoch".

  const mcpToolWithClients = converterWithClients.map((cwc) => {
  	const mcpTools = cwc.converter.convertToMCPTools();
  	return {
  		mcpTools,
  		client: cwc.client,
  	};
  });

• index.js:40-70 (helper)

  Fetches OpenAPI specifications from RSS3 endpoints (gi.rss3.io and ai.rss3.io) and initializes HttpClients, providing the source for all dynamic tools including "API-getNodeRewardsByEpoch".

  const openApiSpecs = (
  	await Promise.allSettled([
  		fetch("https://gi.rss3.io/docs/openapi.json").then(async (res) => {
  			if (!res.ok) throw new Error(`HTTP error! status: ${res.status}`);
  			return res.json();
  		}),
  		fetch("https://ai.rss3.io/openapi.json").then(async (res) => {
  			if (!res.ok) throw new Error(`HTTP error! status: ${res.status}`);
  			return res.json();
  		}),
  	]).then((results) => {
  		return results.map((result) => {
  			if (result.status === "fulfilled") {
  				const client = new HttpClient(
  					{
  						baseUrl: result.value.servers[0].url,
  					},
  					result.value,
  				);
  				return {
  					spec: result.value,
  					client,
  				};
  			}
  
  			console.error("Failed to fetch openapi spec", result.reason);
  			return null;
  		});
  	})
  ).filter(Boolean);