Star Wars MCP Server

Instructions

Implementation Reference

• src/index.ts:96-141 (handler)

  Handler function that searches for planets by name using the SWAPI API, processes the results, and returns formatted text output or handles errors.

    async ({ search }) => {
      try {
        const response = await this.axiosInstance.get<SearchResponse<Planets>>(
          "/planets/",
          {
            params: { search },
          }
        );
  
        if (response.data.results.length === 0) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Nenhum planeta encontrado com o nome "${search}".`,
              },
            ],
          };
        }
  
        const planetsInfo = response.data.results
          .map((planet) => {
            return `Nome: ${planet.name}
              Clima: ${planet.climate}
              Terreno: ${planet.terrain}
              População: ${planet.population}
              Diâmetro: ${planet.diameter}km
              Período de Rotação: ${planet.rotation_period}h
              Período Orbital: ${planet.orbital_period} dias
              `;
          })
          .join("\n---\n\n");
  
        return {
          content: [
            {
              type: "text" as const,
              text: `Encontrados ${response.data.results.length} planeta(s):\n\n${planetsInfo}`,
            },
          ],
        };
      } catch (error) {
        return this.handleError(error, "buscar planetas");
      }
    }
  );

• src/index.ts:92-94 (schema)

  Zod input schema defining the 'search' parameter as a string for the search_planets tool.

  inputSchema: {
    search: z.string().describe("Nome do planeta para buscar"),
  },

• src/index.ts:87-95 (registration)

  Registration of the 'search_planets' tool on the MCP server, including name, title, description, and input schema.

  this.server.registerTool(
    "search_planets",
    {
      title: "Buscar Planetas",
      description: "Busca planetas do Star Wars por nome",
      inputSchema: {
        search: z.string().describe("Nome do planeta para buscar"),
      },
    },

• src/types.ts:20-35 (schema)

  TypeScript interface for the Planets type used in the SearchResponse within the handler.

  export interface Planets {
    name: string;
    diameter: string;
    rotation_period: string;
    orbital_period: string;
    gravity: string;
    population: string;
    climate: string;
    terrain: string;
    surface_water: string;
    residents: string[];
    films: string[];
    url: string;
    created: string;
    edited: string;
  }

• src/index.ts:278-305 (helper)

  Helper function for standardized error handling in tool executions, called by the search_planets handler.

  private handleError(error: unknown, operation: string) {
    if (axios.isAxiosError(error)) {
      const axiosError = error as AxiosError;
      return {
        content: [
          {
            type: "text" as const,
            text: `Erro ao ${operation}: ${
              axiosError.response?.data ||
              axiosError.message ||
              "Erro desconhecido"
            }`,
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [
        {
          type: "text" as const,
          text: `Erro inesperado ao ${operation}: ${error}`,
        },
      ],
      isError: true,
    };
  }