Text Classification (Model2Vec)

Um servidor para classificação de texto usando embeddings estáticos do Model2Vec, suportando múltiplos transportes como stdio e HTTP/SSE.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Text Classification MCP Server (Model2Vec)

Um poderoso servidor Model Context Protocol (MCP) que fornece ferramentas abrangentes de classificação de texto usando embeddings estáticos rápidos do Model2Vec (Minish Lab).

🛠️ Ferramentas e Recursos Completos do MCP

Este servidor fornece 6 ferramentas essenciais, 2 recursos e 1 modelo de prompt para classificação de texto:

🏷️ Ferramentas de Classificação

  • classify_text - Classificar texto único com pontuações de confiança
  • batch_classify - Classificar múltiplos textos simultaneamente

📝 Ferramentas de Gerenciamento de Categorias

  • add_custom_category - Adicionar categorias personalizadas individuais
  • batch_add_custom_categories - Adicionar múltiplas categorias de uma vez
  • list_categories - Visualizar todas as categorias disponíveis
  • remove_categories - Remover categorias indesejadas

📊 Recursos

  • categories://list - Acessar lista de categorias programaticamente
  • model://info - Obter informações do modelo e do sistema

💬 Modelos de Prompt

  • classification_prompt - Modelo de prompt de classificação pronto para uso

🚀 Principais Recursos

  • Zero-instalação: Basta uv run — as dependências são declaradas inline (PEP 723)
  • Múltiplos Transportes: Suporta stdio (local), HTTP/SSE e HTTP Streamable
  • Classificação Rápida: Usa embeddings estáticos eficientes do Model2Vec
  • 10 Categorias Padrão: Tecnologia, negócios, saúde, esportes, entretenimento, política, ciência, educação, viagem, comida
  • Categorias Personalizadas: Adicione suas próprias categorias com descrições
  • Processamento em Lote: Classifique múltiplos textos de uma vez
  • Endpoints de Recursos: Acesse listas de categorias e informações do modelo
  • Modelos de Prompt: Prompts integrados para tarefas de classificação

📋 Instalação

Pré-requisitos

  • Python 3.10+
  • uv gerenciador de pacotes

Configuração Rápida

Nenhuma etapa de instalação separada é necessária — as dependências são declaradas inline no script (PEP 723) e resolvidas automaticamente pelo uv.

🏃‍♂️ Executando o Servidor

Transporte Stdio (Padrão)

uv run text_classifier_server.py

Transporte HTTP/SSE

# SSE on default port 8000
uv run text_classifier_server.py --http

# SSE on custom port
uv run text_classifier_server.py --http 9000

Transporte HTTP Streamable

uv run text_classifier_server.py --streamable-http

🔧 Configuração

Para Claude Desktop

Transporte Stdio (Local)

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "text-classifier": {
      "command": "uv",
      "args": ["run", "/path/to/text_classifier_server.py"]
    }
  }
}

Transporte HTTP (Remoto)

Inicie o servidor com uv run text_classifier_server.py --http, depois adicione:

{
  "mcpServers": {
    "text-classifier": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Para Claude Code

claude mcp add text-classifier -- uv run /Users/olivier/DEV/mcp-text-classifier/text_classifier_server.py

🛠️ Ferramentas Disponíveis

classify_text

Classifique um único texto em categorias predefinidas com pontuações de confiança.

Parâmetros:

  • text (string): O texto a ser classificado
  • top_k (int, opcional): Número de categorias principais a retornar (padrão: 3)

Retorna: JSON com previsões, pontuações de confiança e descrições das categorias

Exemplo:

classify_text("Apple announced new AI features", top_k=3)

batch_classify

Classifique múltiplos textos simultaneamente para processamento eficiente.

Parâmetros:

  • texts (lista): Lista de textos a classificar
  • top_k (int, opcional): Número de categorias principais por texto (padrão: 1)

Retorna: JSON com resultados de classificação em lote

Exemplo:

batch_classify(["Tech news", "Sports update", "Business report"], top_k=2)

add_custom_category

Adicione uma nova categoria personalizada para classificação.

Parâmetros:

  • category_name (string): Nome da nova categoria
  • description (string): Descrição para gerar o embedding da categoria

Retorna: JSON com resultado da operação

Exemplo:

add_custom_category("automotive", "Cars, vehicles, transportation, automotive industry")

batch_add_custom_categories

Adicione múltiplas categorias personalizadas em uma única operação para eficiência.

Parâmetros:

  • categories_data (lista): Lista de dicionários com chaves 'name' e 'description'

Retorna: JSON com resultados da operação em lote

Exemplo:

batch_add_custom_categories([
    {"name": "automotive", "description": "Cars, vehicles, transportation"},
    {"name": "music", "description": "Music, songs, artists, albums, concerts"}
])

list_categories

Liste todas as categorias disponíveis e suas descrições.

Parâmetros: Nenhum

Retorna: JSON com todas as categorias e suas descrições

remove_categories

Remova uma ou múltiplas categorias do sistema de classificação.

Parâmetros:

  • category_names (lista): Lista de nomes de categorias a remover

Retorna: JSON com resultados de remoção para cada categoria

Exemplo:

remove_categories(["automotive", "custom_category"])

📚 Recursos Disponíveis

  • categories://list: Obter lista de categorias disponíveis com metadados
  • model://info: Obter informações sobre o modelo Model2Vec carregado e status do sistema

💬 Prompts Disponíveis

  • classification_prompt: Modelo para tarefas de classificação de texto com contexto e instruções

Parâmetros:

  • text (string): O texto a ser classificado

Retorna: Prompt formatado para classificação com categorias disponíveis listadas

🧪 Testes

Teste com MCP Inspector

npx @modelcontextprotocol/inspector uv run text_classifier_server.py

🔍 Solução de Problemas

Falha no download do modelo

# Manual model download
uv run python -c "from model2vec import StaticModel; StaticModel.from_pretrained('minishlab/potion-base-8M')"

📖 Detalhes Técnicos

  • Modelo: minishlab/potion-base-8M do Model2Vec
  • Similaridade: Similaridade de cosseno entre embeddings de texto e categoria
  • Desempenho: Modelo de ~30MB, inferência rápida com embeddings estáticos
  • Protocolo: Especificação MCP 2024-11-05
  • Transportes: stdio, HTTP+SSE, HTTP Streamable

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione testes para novas funcionalidades
  4. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

  • Model2Vec por Minish Lab para embeddings estáticos rápidos
  • Anthropic pela especificação do Model Context Protocol
  • FastMCP pelo excelente framework MCP em Python

Precisa de ajuda? Consulte a seção de solução de problemas ou abra uma issue no repositório.