MapleStory MCP Server

MapleStory MCP Server 🍁

Um servidor MCP (Model Context Protocol) abrangente que permite acesso aos dados da API aberta do MapleStory da NEXON. Oferece acesso estruturado a informações de personagens, detalhes de Union, dados de guildas, rankings e mecânicas do jogo por meio do Claude Desktop e outros assistentes de IA compatíveis com MCP.

✨ Recursos

• Informações de personagem: Consulta de estatísticas detalhadas, equipamentos e informações básicas do personagem
• Sistema Union: Acesso à composição da força de ataque Union e rankings
• Gerenciamento de guildas: Consulta de informações de guildas e detalhes de membros
• Rankings: Acesso a diversos leaderboards e dados competitivos
• Mecânicas do jogo: Informações sobre probabilidades de Cubos e reforço Star Force
• Atualizações do jogo: Últimos avisos e anúncios
• Suporte a TypeScript: Segurança total de tipos e suporte a IntelliSense
• Logging abrangente: Registro detalhado de operações para depuração
• Tratamento de erros: Tratamento robusto de erros com mensagens detalhadas

🚀 Início Rápido

Uso com NPX (recomendado)

npx maplestory-mcp-server --api-key YOUR_NEXON_API_KEY

Instalação

npm install -g maplestory-mcp-server

🖥️ Uso com o Claude Desktop

1. Obtenha sua chave de API NEXON

Primeiro, obtenha uma chave de API no Portal de API Aberta NEXON:

1. Faça login com sua conta NEXON
2. Vá para "Centro de Desenvolvedores" → "Gerenciamento de Aplicações"
3. Clique em "Registrar nova aplicação"
4. Preencha as informações da aplicação e registre
5. Copie a chave de API gerada

2. Encontre o arquivo de configuração do Claude Desktop

Localização do arquivo de configuração por sistema operacional:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

3. Adicione a configuração do servidor MCP

Adicione ou modifique o seguinte conteúdo no arquivo de configuração:

{
  "mcpServers": {
    "maplestory-mcp-server": {
      "command": "npx",
      "args": ["-y", "maplestory-mcp-server"],
      "env": {
        "NEXON_API_KEY": "여기에_발급받은_API_키_입력"
      }
    }
  }
}

⚠️ Importante: Substitua YOUR_NEXON_API_KEY pela chave de API real que você recebeu.

4. Reinicie o Claude Desktop

Após modificar o arquivo de configuração, feche completamente o Claude Desktop e abra novamente.

5. Verifique a conexão

Após reiniciar o Claude Desktop, verifique a conexão digitando o seguinte em uma nova conversa:

메이플스토리 API가 정상적으로 작동하는지 확인해줘

Se a conexão for bem-sucedida, o Claude poderá responder a perguntas relacionadas ao MapleStory!

🛠️ Ferramentas MCP disponíveis

Ferramentas de personagem

• get_character_basic_info - Consulta de informações básicas do personagem (nível, classe, mundo, guilda)
• get_character_stats - Consulta de estatísticas detalhadas do personagem e estatísticas de combate
• get_character_equipment - Consulta de equipamentos e detalhes de itens do personagem
• get_character_full_info - Consulta de informações abrangentes do personagem de uma só vez

Ferramentas de Union

• get_union_info - Consulta de nível Union, classificação e informações de artefatos
• get_union_raider - Consulta da composição do tabuleiro da força de ataque Union e blocos
• get_union_ranking - Consulta do ranking de poder Union

Ferramentas de guilda

• get_guild_info - Consulta de informações da guilda, membros e habilidades
• get_guild_ranking - Consulta do ranking de nível de guilda

Ferramentas de ranking

• get_overall_ranking - Consulta abrangente de ranking de nível com opções de filtro

Ferramentas de utilitário

• get_notice_list - Consulta de avisos e anúncios do jogo
• get_notice_detail - Consulta de informações detalhadas de avisos
• get_cube_probability - Consulta de informações de probabilidade de reforço de Cubos
• get_starforce_probability - Consulta de informações de probabilidade de reforço Star Force
• health_check - Verificação de conexão e status da API

📖 Exemplos de uso

🎯 Fazendo perguntas no Claude Desktop

Você pode consultar informações do MapleStory no Claude Desktop usando linguagem natural, como:

Consulta de informações do personagem

"김코인"이라는 캐릭터의 기본 정보를 알려줘

"베라월드용사" 캐릭터의 상세한 스탯 정보를 조회해줘

"리부트용사" 캐릭터가 착용하고 있는 장비 목록을 보여줘

Informações de Union e guilda

"스카니아용사" 캐릭터의 유니온 정보를 조회해줘

"스카니아" 월드의 "길드명" 길드 정보를 알려줘

Consulta de rankings

스카니아 월드의 아크메이지(불,독) 직업 랭킹 1페이지를 보여줘

베라 월드의 유니온 랭킹 상위 20명을 조회해줘

Informações do jogo

메이플스토리 최신 공지사항을 확인해줘

레드 큐브의 강화 확률 정보를 알려줘

💡 Dicas de uso

1. Análise abrangente do personagem

"스카니아용사" 캐릭터의 모든 정보를 종합적으로 분석해줘 (기본정보, 스탯, 장비, 유니온)

2. Gerenciamento de guilda

"베라" 월드의 "우리길드" 길드원들의 레벨과 직업을 정리해줘

3. Comparação de rankings

"스카니아" 월드와 "베라" 월드의 상위 랭커들을 비교 분석해줘

4. Acompanhamento de progresso

"내캐릭터" 캐릭터의 어제와 오늘 스탯 변화를 비교해줘

🔧 Exemplos de programação

Exemplos de chamadas diretas à API para desenvolvedores:

Consulta de informações do personagem

// 기본 캐릭터 정보 조회
const basicInfo = await getCharacterBasicInfo({
  characterName: "스카니아용사"
});

// 상세한 캐릭터 스탯 조회
const stats = await getCharacterStats({
  characterName: "스카니아용사",
  date: "2024-01-15"
});

// 캐릭터 장비 조회
const equipment = await getCharacterEquipment({
  characterName: "스카니아용사"
});

Dados de Union e guilda

// 유니온 정보 조회
const unionInfo = await getUnionInfo({
  characterName: "스카니아용사"
});

// 길드 정보 조회
const guildInfo = await getGuildInfo({
  guildName: "길드명",
  worldName: "스카니아"
});

Rankings e leaderboards

// 종합 랭킹 조회
const rankings = await getOverallRanking({
  worldName: "스카니아",
  className: "아크메이지(불,독)",
  page: 1
});

// 유니온 랭킹 조회
const unionRankings = await getUnionRanking({
  worldName: "스카니아",
  page: 1
});

🔧 Configuração

Variáveis de ambiente

• NEXON_API_KEY - Chave da API aberta NEXON (obrigatória)
• LOG_LEVEL - Nível de logging (padrão: "info")
• NODE_ENV - Ambiente (development/production)

Opções de CLI

• --api-key - Chave da API NEXON
• --port - Porta do servidor (padrão: 3000)
• --debug - Ativar logging de depuração
• --name - Nome do servidor (padrão: "mcp-maple")
• --version - Versão do servidor

🔑 Como obter uma chave de API NEXON

Guia detalhado

1. Acesse o Portal de API Aberta NEXON

   • Visite https://openapi.nexon.com/

2. Crie uma conta e faça login

   • Faça login com sua conta NEXON (a mesma da conta do jogo)
   • Se não tiver uma conta, registre-se

3. Vá para o Centro de Desenvolvedores

   • Clique em "Centro de Desenvolvedores" no menu superior
   • Selecione "Gerenciamento de Aplicações"

4. Registre uma nova aplicação

   • Clique no botão "Registrar nova aplicação"
   • Preencha as informações obrigatórias:
     • Nome da aplicação: MCP Maple (exemplo)
     • Descrição da aplicação: Claude Desktop MCP 서버용
     • URL do serviço: http://localhost (para desenvolvimento)

5. Emita e copie a chave de API

   • Após o registro, verifique a chave de API
   • Copie a chave de API (guarde em local seguro por segurança)

6. Use a chave de API

   • Use como NEXON_API_KEY na configuração do Claude Desktop
   • Ou use como parâmetro --api-key na CLI

💡 Dica: Tenha cuidado para não expor sua chave de API. Não a envie para repositórios públicos como GitHub.

🎮 Jogos e mundos suportados

Mundos do MapleStory

• Scania
• Bera
• Luna
• Zenith
• Croa
• Union
• Elysium
• Enosis
• Red
• Aurora
• Arcane
• Nova
• Reboot
• Reboot2

🚦 Limites de requisição e boas práticas

• Limite de requisições: 500 requisições por dia por chave de API
• Frequência de requisições: Máximo de 1 requisição por segundo
• Atualização de dados: Os dados do personagem são atualizados diariamente
• Cache: Cache de resultados para melhor desempenho
• Tratamento de erros: Tentativas automáticas para falhas temporárias

🧪 Desenvolvimento

Pré-requisitos

• Node.js 18+
• TypeScript 5.4+
• Chave de API NEXON

Configuração

git clone https://github.com/ljy9303/maplestory-mcp-server.git
cd maplestory-mcp-server
npm install
npm run build

Build

npm run build          # TypeScript 빌드
npm run dev            # 개발 모드 (watch)

📚 Referência da API

Ferramentas de informações do personagem

get_character_basic_info

Consulta informações básicas do personagem, incluindo nível, classe, mundo e guilda.

Parâmetros:

• characterName (string, obrigatório): Nome do personagem a ser consultado
• date (string, opcional): Data no formato YYYY-MM-DD

Valores de retorno:

• characterName: Nome do personagem
• level: Nível do personagem
• job: Classe/Profissão do personagem
• world: Nome do mundo/servidor
• guildName: Nome da guilda (se houver)
• exp: Experiência atual
• expRate: Percentual de experiência

get_character_stats

Consulta estatísticas detalhadas do personagem, incluindo dano, probabilidade crítica e todas as estatísticas de combate.

Parâmetros:

• characterName (string, obrigatório): Nome do personagem a ser consultado
• date (string, opcional): Data no formato YYYY-MM-DD

Valores de retorno:

• basicStats: STR, DEX, INT, LUK, HP, MP
• combatStats: Ataque, poder mágico, estatísticas críticas
• defenseStats: Estatísticas de defesa física/mágica
• allStats: Análise completa de estatísticas

Ferramentas de Union

get_union_info

Consulta nível Union, classificação e informações de artefatos.

Parâmetros:

• characterName (string, obrigatório): Nome do personagem a ser consultado
• date (string, opcional): Data no formato YYYY-MM-DD

Valores de retorno:

• unionLevel: Nível Union atual
• unionGrade: Classificação/Posto Union
• unionArtifact: Nível e pontos de artefato

Tratamento de erros

Todas as ferramentas retornam informações de erro consistentes:

{
  success: false,
  error: "오류 설명",
  metadata?: {
    executionTime: number,
    apiCalls: number
  }
}

🤝 Contribuindo

Contribuições são bem-vindas! Leia o guia de contribuição para mais detalhes.

Processo de desenvolvimento

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Escreva suas alterações
4. Adicione testes
5. Verifique se todos os testes passam
6. Envie um pull request

📄 Licença

Este projeto é licenciado sob a licença MIT. Consulte o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

• NEXON por fornecer a API aberta do MapleStory
• Model Context Protocol por fornecer a especificação MCP
• Anthropic por fornecer o Claude e as ferramentas MCP

🔧 Solução de problemas

Problemas comuns

1. mcp-maple não é reconhecido no Claude Desktop

Sintoma: O Claude Desktop não responde a perguntas relacionadas ao MapleStory

Solução:

1. Feche completamente o Claude Desktop
2. Verifique se o caminho do arquivo de configuração está correto:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. Verifique se o formato JSON está correto (vírgulas, parênteses, etc.)
4. Reinicie o Claude Desktop

2. Erro de chave de API

Sintoma: Erro "API key is invalid" ou "Authentication failed"

Solução:

1. Verifique o status da chave de API no Portal de API Aberta NEXON
2. Verifique se a chave de API não expirou
3. Verifique se a chave de API foi inserida corretamente no arquivo de configuração
4. Remova espaços em branco antes e depois da chave de API

3. Personagem não encontrado

Sintoma: Erro "Character not found"

Solução:

1. Digite o nome do personagem corretamente (incluindo maiúsculas/minúsculas e caracteres especiais)
2. Verifique no jogo se o personagem realmente existe
3. Se o personagem foi criado recentemente, aguarde cerca de um dia e tente novamente

4. Limite de requisições excedido

Sintoma: Erro "Rate limit exceeded"

Solução:

1. Aguarde um pouco e tente novamente (cerca de 1 minuto)
2. Reduza a frequência de requisições
3. Tenha cuidado para não exceder o limite de 500 requisições por dia

5. Problemas de conexão de rede

Sintoma: Erro "Network error" ou "Timeout"

Solução:

1. Verifique sua conexão com a internet
2. Verifique as configurações de firewall ou proxy
3. Tente novamente mais tarde

Métodos de depuração

1. Verifique os logs detalhados

npx mcp-maple --debug --api-key YOUR_API_KEY

2. Teste de conexão

Digite o seguinte no Claude Desktop para verificar o status da conexão:

메이플스토리 API 연결 상태를 확인해줘

3. Validação do arquivo de configuração

Verifique se o formato JSON está correto usando um validador JSON online.

Limitações conhecidas

• Limite de chamadas de API: 500 por dia, 1 por segundo
• Atualização de dados: As informações do personagem são atualizadas por volta das 8h da manhã diariamente
• Mundos suportados: Alguns servidores de teste ou mundos especiais podem não ser suportados

📞 Suporte

• Issues: GitHub Issues
• Documentação: Referência da API
• Exemplos: Exemplos de uso

🔗 Projetos relacionados

• MCP TypeScript SDK
• Claude Desktop
• NEXON Open API

---

Feito com ❤️ para a comunidade MapleStory