Phone Carrier Detector

Servidor MCP Phone Carrier Detector

Um servidor MCP (Model Context Protocol) para detectar a operadora e a localização de números de telefone chineses.

Recursos

• 🔍 Detecção de operadora: Suporta identificação de números das três principais operadoras da China (China Mobile, China Unicom, China Telecom)
• 📍 Detecção de localização: Fornece informações de localização em nível de província e cidade
• 📱 Operadoras virtuais: Suporta identificação de números de operadoras virtuais
• 🚀 Processamento em lote: Suporta detecção em lote de vários números de telefone (até 100)
• 📊 Informações detalhadas: Fornece informações detalhadas como operadora, localização, prefixo, etc.
• 🎯 Alta precisão: Baseado em um banco de dados real de faixas de números de operadoras chinesas (492.088 registros)
• ⚡ Alto desempenho: Banco de dados em memória, com velocidade de consulta extremamente rápida

Operadoras suportadas

Operadora	Principais faixas de números
China Mobile	134-139, 147, 150-152, 157-159, 172, 178, 182-184, 187-188, 198
China Unicom	130-132, 145, 155-156, 166, 175-176, 185-186
China Telecom	133, 149, 153, 173, 177, 180-181, 189, 199
China Broadnet	192
China Tietong	174

Instalação

Método 1: Instalação a partir do código-fonte

git clone https://github.com/dahuangbaojian/sms-mcp-server.git
cd sms-mcp-server

Método 2: Uso direto

O projeto é implementado usando a biblioteca padrão do Python, sem dependências adicionais. Para executar os testes:

pip install pytest

Como usar

No cliente MCP

1. Configure o cliente MCP (como Claude Desktop):

{
  "mcpServers": {
    "phone-carrier-detector": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {}
    }
  }
}

2. Reinicie o cliente e então você poderá usar as seguintes ferramentas:

Detecção de número único

请帮我检测手机号码 13812345678 的运营商和归属地信息

Detecção em lote de números

请帮我批量检测这些号码的运营商和归属地：13812345678, 18687654321, 13312345678

Ferramentas da API

1. detect_carrier

Detecta a operadora e a localização de um único número de telefone.

Parâmetros:

• phone_number (string): O número de telefone a ser detectado (11 dígitos)

Exemplo de saída:

{
  "success": true,
  "phone_number": "13812345678",
  "carrier": "China Mobile",
  "carrier_cn": "移动",
  "province": "江苏",
  "city": "连云港",
  "prefix": "1381234"
}

2. batch_detect_carriers

Detecta a operadora e a localização de vários números de telefone em lote.

Parâmetros:

• phone_numbers (array): Lista de números de telefone a serem detectados (até 100)

Exemplo de saída:

{
  "success": true,
  "total": 3,
  "results": [
    {
      "success": true,
      "phone_number": "13812345678",
      "carrier": "China Mobile",
      "province": "江苏",
      "city": "连云港"
    }
  ]
}

Fonte de dados

O projeto usa um banco de dados real de localização de números de telefone chineses, incluindo:

• 492.088 registros
• Cobertura de todas as principais operadoras
• Precisão em nível de cidade
• Atualizações em tempo real

Desenvolvimento

Executar testes

# 运行所有测试
python tests/run_tests.py --all

# 运行单元测试
python tests/run_tests.py --unit

# 运行集成测试
python tests/run_tests.py --integration

# 运行数据解析器测试
python tests/run_tests.py --data

Analisar dados

# 从原始数据文件生成数据库
python parse_phone_data.py

Teste local

python mcp_server.py

Estrutura do projeto

.
├── mcp_server.py              # MCP协议主服务
├── parse_phone_data.py        # 数据解析脚本
├── data/                      # 数据目录
│   ├── 手机号归属地1219.txt   # 原始数据文件
│   └── phone_database.json    # 解析后的数据库
├── tests/                     # 测试目录
│   ├── test_mcp_server.py     # 单元测试
│   ├── test_mcp_integration.py # 集成测试
│   ├── test_data_parser.py    # 数据解析测试
│   └── run_tests.py           # 测试运行器
├── package.json               # MCP配置
├── mcp-metadata.json          # MCP元数据
└── README.md                  # 项目说明

Stack tecnológico

• Python 3.8+
• Protocolo MCP 2024-11-05
• JSON-RPC 2.0
• Expressões regulares - Validação de formato de número
• Banco de dados em memória - Consultas de alto desempenho

Características de desempenho

• Uso de memória: ~100MB (incluindo 490 mil registros)
• Velocidade de consulta: Busca em tabela hash O(1)
• Suporte a concorrência: Processamento assíncrono, suporta alta concorrência
• Tratamento de erros: Tratamento de erros e validação de parâmetros abrangentes

Contribuição

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

1. Faça um fork do projeto
2. Crie um branch de funcionalidade (git checkout -b feature/AmazingFeature)
3. Faça commit das alterações (git commit -m 'Add some AmazingFeature')
4. Envie para o branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Licença

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

Registro de alterações

v1.0.0

• Lançamento da versão inicial
• Suporte à detecção das três principais operadoras da China
• Suporte à detecção de localização (província + cidade)
• Suporte à detecção de operadoras virtuais
• Suporte à detecção em lote de números
• Baseado em banco de dados real (490 mil+ registros)
• Implementação completa do protocolo MCP
• Cobertura abrangente de testes

Suporte

Se você encontrar algum problema ou tiver sugestões, por favor:

1. Consulte Issues
2. Crie uma nova Issue
3. Envie um e-mail para huangjian@ztinfo.cn

---

⭐ Se este projeto foi útil para você, dê uma estrela!