railway-mcp

Instructions

Implementation Reference

• src/tools/template.tool.ts:6-32 (handler)

  Definition of the 'template_list' tool including its description, input schema, and handler function that calls templatesService.listTemplates(searchQuery). This is the core implementation of the MCP tool.

  createTool(
    "template_list",
    formatToolDescription({
      type: 'API',
      description: "List all available templates on Railway",
      bestFor: [
        "Discovering available templates",
        "Planning service deployments",
        "Finding template IDs and sources"
      ],
      notFor: [
        "Listing existing services",
        "Getting service details"
      ],
      relations: {
        nextSteps: ["service_create_from_template"],
        alternatives: ["service_create_from_repo", "service_create_from_image"],
        related: ["database_list_types"]
      }
    }),
    {
      searchQuery: z.string().optional().describe("Optional search query to filter templates by name and description"),
    },
    async ({ searchQuery }) => {
      return templatesService.listTemplates(searchQuery);
    }
  ),

• src/tools/template.tool.ts:26-28 (schema)

  Input schema for the 'template_list' tool using Zod.

  {
    searchQuery: z.string().optional().describe("Optional search query to filter templates by name and description"),
  },

• src/tools/index.ts:16-37 (registration)

  Registration of all tools including templateTools (which contains 'template_list') with the MCP server via server.tool().

  export function registerAllTools(server: McpServer) {
    // Collect all tools
    const allTools = [
      ...databaseTools,
      ...deploymentTools,
      ...domainTools,
      ...projectTools,
      ...serviceTools,
      ...tcpProxyTools,
      ...variableTools,
      ...configTools,
      ...volumeTools,
      ...templateTools,
    ] as Tool[];
  
    // Register each tool with the server
    allTools.forEach((tool) => {
      server.tool(
        ...tool
      );
    });
  } 

• src/services/templates.service.ts:11-75 (helper)

  Supporting utility: templatesService.listTemplates() method which fetches templates from the client API, optionally filters with Fuse.js, categorizes, formats output, and handles errors.

  async listTemplates(searchQuery?: string) {
    try {
      let templates = await this.client.templates.listTemplates();
  
      // If search query is provided, filter templates by name and description
      if (searchQuery) {
        const fuse = new Fuse(templates, {
          keys: [{
            name: 'name',
            weight: 3,
          }, {
            name: 'description',
            weight: 2,
          }],
          threshold: 0.3
        });
        templates = fuse.search(searchQuery).map(result => result.item);
      }
      
      // Group templates by category
      const categorizedTemplates = templates.reduce((acc, template) => {
        if (!acc[template.category]) {
          acc[template.category] = [];
        }
        acc[template.category].push(template);
        return acc;
      }, {} as Record<string, typeof templates>);
  
      const formattedTemplates = Object.entries(categorizedTemplates)
        .map(([category, templates]) => {
          // Sort templates by projects in descending order
          const sortedTemplates = [...templates].sort((a, b) => b.projects - a.projects);
          
          return `
            📁 ${category}
            ${sortedTemplates.map(template => {
              const services = Object.entries(template.serializedConfig.services)
                .map(([id, service]) => `
                    Service: ${service.name}
                    ${service.icon ? `Icon: ${service.icon}` : ''}
                    Source: ${service.source?.image || service.source?.repo || 'N/A'}
                    Variables: ${Object.keys(service.variables || {}).length} configured
                    Networking: ${service.networking?.tcpProxies ? 'TCP Proxy enabled' : 'No TCP Proxy'}, ${Object.keys(service.networking?.serviceDomains || {}).length} domains
                    Volumes: ${Object.keys(service.volumeMounts || {}).length} mounts`
                ).join('\n');
  
              return `  📦 ${template.name}
                ID: ${template.id}
                Description: ${template.description}
                Projects: ${template.projects}
                Services:
                ${services}`;
            }).join('\n')}
        `;
        })
        .join('\n');
  
      return createSuccessResponse({
        text: `Available templates:\n${formattedTemplates}`,
        data: categorizedTemplates
      });
    } catch (error) {
      return createErrorResponse(`Error listing templates: ${formatError(error)}`);
    }
  }