Reservation System MCP Server

Servidor MCP do Sistema de Reservas

Este é um servidor de API do Sistema de Reservas baseado no Model Context Protocol (MCP) para WeChat Cloud Development, permitindo que modelos de IA acessem e gerenciem dados de reservas com segurança.

Recursos

🔧 Ferramentas Suportadas

1. query_reservations - Consultar registros de reservas

   • Suporta filtragem por ID do usuário, status e ID do item de reserva
   • Permite definir limite de registros retornados
   • Retorna informações de reserva formatadas

2. update_reservation_status - Atualizar status da reserva

   • Cancelar reserva (status definido como 10)
   • Restaurar reserva (status definido como 1)
   • Cancelamento pelo sistema (status definido como 99)
   • Permite adicionar motivo do cancelamento

3. delete_reservation - Excluir registro de reserva

   • Exclui permanentemente o registro de reserva especificado
   • Operação irreversível, use com cautela

📊 Descrição dos Status de Reserva

• 1 - ✅ Reserva confirmada
• 10 - ❌ Cancelada
• 99 - ⚠️ Cancelada pelo sistema

Instalação e Configuração

1. Instalar dependências

cd mcp-reservation-server
npm install

2. Configurar variáveis de ambiente

Copie o arquivo de exemplo de variáveis de ambiente e configure:

cp .env.example .env

Edite o arquivo .env:

WECHAT_APP_ID=你的微信小程序AppID
WECHAT_APP_SECRET=你的微信小程序Secret
WECHAT_ENV_ID=你的微信云环境ID

3. Compilar o projeto

npm run build

4. Iniciar o servidor

npm start

Ou modo de desenvolvimento:

npm run dev

Uso em clientes de IA

Configurar o cliente MCP

Adicione este servidor MCP ao arquivo de configuração do seu cliente de IA:

{
  "mcpServers": {
    "reservation": {
      "command": "node",
      "args": ["/path/to/mcp-reservation-server/dist/index.js"],
      "env": {
        "WECHAT_APP_ID": "你的AppID",
        "WECHAT_APP_SECRET": "你的Secret", 
        "WECHAT_ENV_ID": "你的环境ID"
      }
    }
  }
}

Exemplo de configuração do Claude Desktop

{
  "mcpServers": {
    "reservation": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-reservation-server\\dist\\index.js"],
      "env": {
        "WECHAT_APP_ID": "",
        "WECHAT_APP_SECRET": "",
        "WECHAT_ENV_ID": ""
      }
    }
  }
}

Exemplos de uso

Consultar registros de reserva

请查询所有状态为成功的预约记录

Cancelar reserva

请取消预约ID为 JOIN123456 的预约，理由是"用户主动取消"

Excluir reserva

请永久删除预约ID为 JOIN123456 的记录

Referência da API

Endpoints da API WeChat Cloud Development

Este servidor MCP utiliza os seguintes endpoints da API WeChat Cloud Development:

• Obter Access Token: GET https://api.weixin.qq.com/cgi-bin/token
• Consulta ao banco de dados: POST https://api.weixin.qq.com/tcb/databasequery
• Atualização no banco de dados: POST https://api.weixin.qq.com/tcb/databaseupdate
• Exclusão no banco de dados: POST https://api.weixin.qq.com/tcb/databasedelete

Coleções do banco de dados

• ax_join: Tabela de registros de reservas
  • JOIN_ID: ID do registro de reserva
  • JOIN_USER_ID: ID do usuário
  • JOIN_MEET_ID: ID do item de reserva
  • JOIN_MEET_TITLE: Título do item de reserva
  • JOIN_STATUS: Status da reserva
  • JOIN_REASON: Motivo do cancelamento
  • Outros campos...

Notas de segurança

1. Proteção de variáveis de ambiente: Garanta que informações sensíveis, como o AppSecret do WeChat, sejam definidas por meio de variáveis de ambiente e não codificadas no código
2. Controle de acesso: Garanta que apenas clientes de IA confiáveis possam acessar este servidor MCP
3. Logs de operação: O servidor registra todas as chamadas de API para fins de auditoria
4. Backup de dados: Operações de exclusão são irreversíveis; recomenda-se fazer backup regular dos dados importantes

Solução de problemas

Erros comuns

1. AccessToken inválido (40014)

   • Verifique se o AppID e o AppSecret estão corretos
   • Confirme as configurações da lista de permissões de IP

2. AccessToken expirado (42001)

   • O servidor atualiza o token automaticamente; se o problema persistir, verifique o horário do sistema

3. Falha na consulta ao banco de dados

   • Verifique se o ID do ambiente cloud está correto
   • Confirme se a coleção do banco de dados existe

Modo de depuração

Defina a variável de ambiente para habilitar logs de depuração:

LOG_LEVEL=debug npm start

Desenvolvimento

Estrutura do projeto

mcp-reservation-server/
├── src/
│   ├── index.ts          # 主服务器文件
│   ├── wechat-api.ts     # 微信API客户端
│   └── types.ts          # 类型定义
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Comandos de build

• npm run build - Compilar TypeScript
• npm run dev - Executar em modo de desenvolvimento
• npm run clean - Limpar arquivos de build

Licença

Licença MIT

Contribuições

Contribuições são bem-vindas! Envie Issues e Pull Requests!