RSS3 MCP Server

Instructions

Implementation Reference

• index.js:150-223 (handler)

  Generic handler for executing all dynamically-generated API tools (names like 'API-getNodeOperationProfitByAddress'). Matches tool name to OpenAPI operation via openApiLookup and calls HttpClient.executeOperation with parameters, returning JSON response or error.

  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)

  Dynamic tool registration/listing handler. Iterates OpenAPI definitions to generate tool list with names constructed as `${toolName}-${method.name}` (truncated to 64 chars), producing entries like 'API-getNodeOperationProfitByAddress'.

  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:78-84 (helper)

  Converts OpenAPI specs to MCP tools using OpenAPIToMCPConverter, creating the openApiLookup dictionary that maps tool names (e.g., 'API-getNodeOperationProfitByAddress') to their corresponding OpenAPI operations used in handler and listing.

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

• index.js:71-77 (helper)

  Initializes OpenAPIToMCPConverter and HttpClient instances from fetched RSS3 OpenAPI specs (gi.rss3.io and ai.rss3.io), foundational for dynamic tool generation.

  const converterWithClients = openApiSpecs.map((o) => {
  	const converter = new OpenAPIToMCPConverter(o.spec);
  	return {
  		converter,
  		client: o.client,
  	};
  });

• index.js:156-175 (schema)

  Special handler within tool caller that provides input schema for any API tool (including 'API-getNodeOperationProfitByAddress') by looking up method.inputSchema from OpenAPI defs.

  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`);
  }