GW2 MCP Server

GW2 MCP Server

Um servidor Model Context Provider (MCP) para Guild Wars 2 que conecta Modelos de Linguagem de Grande Porte (LLMs) às fontes de dados do Guild Wars 2.

Recursos

• Pesquisa na Wiki: Pesquise e recupere conteúdo da wiki do Guild Wars 2
• Informações da Carteira: Acesse dados de carteira e moedas do usuário via API GW2
• Cache Inteligente: Cache eficiente com TTL apropriado para dados estáticos e dinâmicos
• Limitação de Taxa: Uso respeitoso da API com limitação de taxa integrada
• Arquitetura Extensível: Design modular para fácil adição de recursos

Requisitos

• Go 1.24 ou superior
• Chave de API do Guild Wars 2 (para funcionalidade de carteira)

Instalação

1. Clone o repositório:

git clone https://github.com/AlyxPink/gw2-mcp.git
cd gw2-mcp

2. Instale as dependências:

go mod tidy

3. Compile o servidor:

go build -o gw2-mcp ./cmd/server

Uso

Executando o Servidor

O servidor MCP se comunica via stdio (entrada/saída padrão):

./gw2-mcp

Você pode configurar o Claude Desktop, LM Studio ou outras ferramentas de LLM para interagir com o servidor usando esta configuração:

{
  "mcpServers": {
    "gw2-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "alyxpink/gw2-mcp:v1"
      ]
    }
  }
}

Ferramentas MCP

O servidor fornece as seguintes ferramentas para interação com LLM:

1. Pesquisa na Wiki (wiki_search)

Pesquise informações na wiki do Guild Wars 2.

Parâmetros:

• query (obrigatório): String de consulta de pesquisa
• limit (opcional): Número máximo de resultados (padrão: 5)

Exemplo:

{
  "tool": "wiki_search",
  "arguments": {
    "query": "Dragon Bash",
    "limit": 3
  }
}

2. Obter Carteira (get_wallet)

Recupere as informações da carteira do usuário, incluindo todas as moedas.

Parâmetros:

• api_key (obrigatório): Chave de API do Guild Wars 2 com escopo de conta

Exemplo:

{
  "tool": "get_wallet",
  "arguments": {
    "api_key": "YOUR_GW2_API_KEY"
  }
}

3. Obter Moedas (get_currencies)

Obtenha informações sobre as moedas do Guild Wars 2.

Parâmetros:

• ids (opcional): Matriz de IDs de moedas específicas para buscar

Exemplo:

{
  "tool": "get_currencies",
  "arguments": {
    "ids": [1, 2, 3]
  }
}

Recursos MCP

O servidor fornece os seguintes recursos:

Lista de Moedas (gw2://currencies)

Lista completa de todas as moedas do Guild Wars 2 com metadados.

Configuração da Chave de API

Para usar a funcionalidade de carteira, você precisa de uma chave de API do Guild Wars 2:

1. Visite Gerenciamento de Chaves de API do Guild Wars 2
2. Crie uma nova chave de API com as seguintes permissões:
   • account - Necessária para acesso à carteira
   • wallet - Necessária para informações de moedas
3. Copie a chave de API gerada

Nota de Segurança: As chaves de API são criptografadas (hash) antes do cache por segurança. Nunca compartilhe sua chave de API.

Estratégia de Cache

O servidor implementa cache inteligente:

• Dados Estáticos (moedas, conteúdo da wiki): Armazenados em cache por 24 horas a 1 ano
• Dados Dinâmicos (saldos da carteira): Armazenados em cache por 5 minutos
• Resultados de Pesquisa: Armazenados em cache por 24 horas

Arquitetura

O projeto segue os princípios da Arquitetura Limpa:

internal/
├── server/          # MCP server implementation
├── cache/           # Caching layer
├── gw2api/          # GW2 API client
└── wiki/            # Wiki API client

Desenvolvimento

Padrões de Código

• Formate o código com gofumpt
• Execute lint com golangci-lint
• Escreva testes unitários para a funcionalidade principal
• Siga mensagens de commit convencionais

Executando Testes

go test ./...

Lint

golangci-lint run

Formatação

gofumpt -w .

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Adicione testes se aplicável
5. Execute lint e formatação
6. Envie um pull request

Licença

GNU Affero General Public License v3.0 - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

• Guild Wars 2 API por fornecer dados abrangentes do jogo
• Guild Wars 2 Wiki pela extensa documentação do jogo
• MCP Go pelo framework de implementação do MCP