Skip to main content
Glama
RamosJSouza

Simple MCP Server - Star Wars API

by RamosJSouza
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Simple MCP Server - Star Wars API

📋 Sobre o Projeto

Este é um micro projeto para demonstração da criação de um Model Context Protocol (MCP) Server utilizando a API aberta SWAPI (Star Wars API) para fins de ilustração e portfólio.

O projeto demonstra como criar um servidor MCP funcional que pode ser integrado ao Claude Desktop ou testado através do MCP Inspector, fornecendo acesso a dados do universo Star Wars através de ferramentas e recursos estruturados.

Related MCP server: SWAPI MCP Server

🚀 Funcionalidades

Tools Disponíveis

  • search_characters - Busca personagens por nome

  • search_planets - Busca planetas por nome

  • search_films - Busca filmes por título

  • search_characters_byId - Busca personagem específico por ID

Resources Disponíveis

  • all_films - Lista todos os filmes ordenados por episódio

🛠️ Tecnologias Utilizadas

  • TypeScript - Linguagem principal

  • Node.js - Runtime

  • Model Context Protocol (MCP) SDK - Framework para criação do servidor

  • Axios - Cliente HTTP para requisições à API

  • Zod - Validação de esquemas

  • SWAPI API - Fonte de dados (Star Wars)

📦 Instalação

Pré-requisitos

  • Node.js (versão 18 ou superior)

  • npm ou yarn

Passos para Instalação

  1. Clone o repositório:

    git clone https://github.com/RamosJSouza/simple-mcp-server.git
cd simple-mcp-server

  2. Instale as dependências:

    npm install

  3. Compile o projeto:

    npm run build

🎯 Como Usar

Opção 1: MCP Inspector (Recomendado para Testes)

O MCP Inspector é uma ferramenta web que permite testar e interagir com servidores MCP de forma visual e intuitiva.

  1. Execute o inspector:

    npm run inspector

  2. Acesse a interface:

    • Abra seu navegador em: http://localhost:6274

    • Use o token fornecido no terminal para autenticação

  3. Teste as funcionalidades:

    • Explore os tools disponíveis na aba "Tools"

    • Visualize os resources na aba "Resources"

    • Execute consultas e veja os resultados em tempo real

🖼️ Interface do MCP Inspector

MCP Inspector Interface

Interface do MCP Inspector mostrando a busca por "anakin" e o resultado detalhado do personagem Anakin Skywalker com todas as informações (nome, altura, massa, ano de nascimento, gênero, cor dos olhos, cor do cabelo e cor da pele). A ferramenta permite testar todos os tools disponíveis de forma interativa.

Documentação oficial do MCP Inspector: Model Context Protocol Inspector

Opção 2: Claude Desktop

Para integrar com o Claude Desktop:

  1. Configure o arquivo de configuração:

    {
  "mcpServers": {
    "simple-mcp-server": {
      "command": "node",
      "args": ["C:\\caminho\\para\\seu\\projeto\\build\\index.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

  2. Localização do arquivo de configuração:

    • Windows: C:\Users\[SEU_USUARIO]\AppData\Roaming\Claude\claude_desktop_config.json

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  3. Reinicie o Claude Desktop para carregar a nova configuração

📚 Scripts Disponíveis

npm run build      # Compila o projeto TypeScript
npm run watch      # Compila em modo watch (desenvolvimento)
npm run inspector  # Executa o MCP Inspector para testes

🏗️ Estrutura do Projeto

simple-mcp-server/
├── src/
│   ├── index.ts          # Servidor MCP principal
│   └── types.ts          # Definições de tipos TypeScript
├── build/                # Código compilado (gerado)
├── package.json          # Configurações e dependências
├── tsconfig.json         # Configurações do TypeScript
└── README.md            # Este arquivo

🔧 Configuração e Personalização

Adicionando Novos Tools

Para adicionar novos tools ao servidor:

  1. Defina o schema no arquivo types.ts

  2. Implemente o tool no método setupTools()

  3. Compile o projeto com npm run build

Exemplo de Tool

this.server.registerTool(
    "nome_do_tool",
    {
        title: "Título do Tool",
        description: "Descrição do que o tool faz",
        inputSchema: {
            parametro: z.string().describe("Descrição do parâmetro"),
        },
    },
    async ({ parametro }) => {
        // Implementação do tool
        return {
            content: [
                {
                    type: "text" as const,
                    text: "Resultado do tool",
                }
            ]
        };
    }
);

🐛 Solução de Problemas

Problemas Comuns

  1. Porta em uso no Inspector:

    # Erro: "Proxy Server PORT IS IN USE at port 6277"
# Solução: Aguarde alguns segundos e tente novamente

  2. Claude Desktop não detecta o MCP:

    • Verifique se o caminho no arquivo de configuração está correto

    • Reinicie completamente o Claude Desktop

    • Verifique se o projeto foi compilado (npm run build)

  3. Erros de compilação:

    • Execute npm install para garantir que todas as dependências estão instaladas

    • Verifique se está usando Node.js versão 18 ou superior

📖 Documentação Adicional

👨‍💻 Desenvolvedor

RAMOS DE SOUZA JANONES
Desenvolvedor Full Stack
LinkedIn: linkedin.com/in/ramos-souza
GitHub: github.com/RamosJSouza

Resumo Profissional

Desenvolvedor Full Stack com mais de 14 anos de experiência em arquiteturas escaláveis, microserviços e soluções cloud-native. Especialista em Node.js, React, Angular e DevOps, com histórico de liderança técnica e redução de 20% no tempo de entrega em projetos críticos. Focado em inovação, performance e mentoria de equipes ágeis.

Habilidades Técnicas

  • Linguagens: JavaScript, TypeScript, Python, PHP

  • Frontend: React, React Native, Next.js, Angular, Redux, Styled Components, Storybook

  • Backend: Node.js, NestJS, Express, GraphQL, REST

  • Bancos de Dados: PostgreSQL, MongoDB, MySQL

  • Cloud & DevOps: AWS, Serverless, GCP, Azure, Docker, Kubernetes, CI/CD (GitHub Actions, Azure DevOps)

  • Mensageria: Kafka, RabbitMQ

  • Testes: Cypress, Jest, TDD (Test-Driven Development)

  • Outras Ferramentas: Power BI, Pentaho ETL

  • Desenvolvimento com IA: Cursor AI, GitHub Copilot, Model Context Protocol (MCP), Prompt Engineering, Context Engineering, Desenvolvimento de Agentes de IA

  • Soft Skills: Liderança técnica, mentoria, resolução de problemas, colaboração ágil

⚠️ Nota Importante

Este projeto foi desenvolvido 100% manualmente, sem utilização de IA para geração de código. Todo o desenvolvimento foi realizado através de conhecimento técnico próprio e experiência profissional, mesmo sendo um simples MCP Server.

📄 Licença

Este projeto é de código aberto e está disponível sob a licença MIT.

Projeto criado para fins educacionais e demonstração de habilidades técnicas em desenvolvimento de servidores MCP.

Available Tools

4 tools
search_charactersSearch characters Star WarsB

Search characters Star Wars, in API by name

ParametersJSON Schema
NameRequiredDescriptionDefault
searchYesName os an caracters os Star Wars Films

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it searches 'by name' and does not mention return format, pagination, or confirm that this is a read-only operation, leaving significant gaps for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded, but it is grammatically awkward ('Search characters Star Wars') and duplicates the title. It is concise but lacks structure and fails to add meaningful detail beyond the basic purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter, read-only search tool with a fully descriptive schema, the description is minimally sufficient. However, it does not explicitly differentiate from sibling tools or describe what the response contains, and the low complexity only partially compensates for these omissions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'search' parameter, so the baseline is 3. The description's 'by name' merely restates the schema's intent and adds no extra detail about matching behavior, case sensitivity, or expected input format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the verb 'Search' with the resource 'characters Star Wars' and specifies 'by name', which distinguishes it from the sibling tool search_characters_byId. However, the phrasing is awkward and repeats the title, and it does not explicitly mention the alternative of searching by ID.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by name' implies this tool is for name-based character searches, giving some usage context. However, there is no explicit mention of when to use this tool versus search_characters_byId or the other sibling tools, nor any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_characters_byIdSearch character by ID Star WarsB

Search a specific Star Wars character by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID of the Star Wars character

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. 'Search' implies a read-only operation, which is transparent. However, it does not disclose what happens if the ID is not found, the return format, or any potential side effects. For a simple lookup this may be sufficient, but more detail would improve clarity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the verb and resource. It contains no filler, repetition, or unnecessary context, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup tool with no output schema and no annotations, the description adequately conveys the tool's purpose and scope. It could mention not-found behavior or the expected response, but given the tool's simplicity, the current description is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes the single parameter 'id' as 'ID of the Star Wars character', giving 100% schema coverage. The description only adds the redundant word 'specific', which is already implied by fetching by ID, so it provides no additional semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search a specific Star Wars character by ID' clearly states a verb ('search'), resource ('Star Wars character'), and scope ('by ID'), which is useful. However, it does not explicitly distinguish this from the sibling tool 'search_characters', which likely searches across characters generally.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this should be used when you have a known ID, nor does it exclude it for other search scenarios. There is no explicit context or alternative naming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_filmsSearch films Star WarsD

Search films Star Wars, in API by title

ParametersJSON Schema
NameRequiredDescriptionDefault
searchYesTitle of a Star Wars film

TDQS

D1.7/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not state whether the search is case-sensitive, supports partial matches, returns a list or a single result, or any details about pagination or error handling. This is a critical gap for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short but under-specified, with awkward phrasing ('in API by title') that does not earn its place. It lacks informative content, making it more of an under-specification than a concise summary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and no annotations, so the description must explain return values and behavior. It fails to mention what the search returns, whether it returns a collection or a single object, or any constraints on the search. The description is inadequate for a simple search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage for the single parameter 'search' with a clear description ('Title of a Star Wars film'). The description's 'by title' is redundant, adding no new meaning beyond the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search films Star Wars, in API by title' largely restates the tool name and title without adding meaningful specificity. It conveys a verb+resource but fails to clarify scope or behavior, distinguishing it from siblings only by resource name, which is already evident from the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like search_characters or search_planets. There is no mention of prerequisites, exclusions, or typical use cases, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_planetsSearch planets Star WarsB

Search planets Star Wars, in API by name

ParametersJSON Schema
NameRequiredDescriptionDefault
searchYesName of a planet in Star Wars Films

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the behavioral disclosure burden. It only states 'by name' but does not reveal return format, matching behavior (exact vs partial), pagination, or case sensitivity. This is minimal transparency for a search tool, though it is not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that gets to the point, though the phrasing 'in API' is slightly awkward and the 'Star Wars' mention is redundant with the title. It is efficient without being overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter search tool with no output schema, the description provides the core purpose but lacks details about return values or limitations. It is adequate for basic use but leaves gaps around expected results and edge cases, making it a minimum viable score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a clear description for the 'search' parameter ('Name of a planet in Star Wars Films'), giving 100% coverage. The description's 'by name' reiterates this without adding new details, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (search) and resource (planets in Star Wars), with the parameter 'by name' adding specificity. It does not explicitly distinguish from sibling search tools like search_films or search_characters, but the resource focus on planets makes the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage; you would use this tool to search for Star Wars planets by name. However, it provides no explicit guidance on when to choose this over sibling tools (e.g., 'use search_characters for characters') or any exclusions, so it falls short of a 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv1.0.0
    • First observedsearch_characters
    • First observedsearch_characters_byId
    • First observedsearch_films
    • First observedsearch_planets
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3/5.0
Disambiguation5/5

Each tool targets a distinct resource or query type: films by title, planets by name, characters by name or ID. The two character tools are clearly separated by their ID/name parameter, leaving no ambiguity.

Naming Consistency4/5

All tools follow the verb 'search_' followed by a resource name, which is consistent. The single exception is 'search_characters_byId', which mixes camelCase for 'Id' while other names use all lowercase and underscores, a minor deviation from the pattern.

Tool Count5/5

With 4 tools, the server is well-scoped for a simple search-focused API. The count is within the ideal range and each tool covers a unique, necessary operation.

Completeness3/5

The server covers three core resources (films, characters, planets) but omits other common Star Wars categories like starships, vehicles, and species. Additionally, films and planets only support search by name, lacking ID-based lookups that characters have, which leaves notable gaps for users needing specific items.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • starwars

    johnpapa
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides access to the SWAPI Star Wars API, enabling users to query characters, planets, films, species, vehicles, and starships with automatic pagination and caching.
    40
    10
    MIT

  • mcp-server-swapy

    gustafsilva
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for querying the Star Wars universe via the SWAPI API, providing access to characters, films, starships, vehicles, species, and planets.
    ISC

  • swapi-build

    eldermoraes
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server that provides access to Star Wars data (people, films, planets, species, starships, vehicles) through tools like list, get, random, and search.
    3
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/RamosJSouza/simple_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server