APLCart MCP Server

Servidor MCP APLCart

Um servidor Model Context Protocol (MCP) que expõe a coleção de expressões idiomáticas APLCart com recursos de busca semântica. APLCart é uma coleção pesquisável de expressões APL com descrições.

Recursos

• Encontre expressões APL por correspondência exata de sintaxe
• Pesquise em sintaxe, descrições e palavras-chave
• Obtenha palavras-chave para expressões APL específicas
• Consultas em linguagem natural usando embeddings da OpenAI

Instalação

Pré-requisitos

• Python 3.11 ou superior
• Chave da API da OpenAI (para funcionalidade de busca semântica)

Usando uv

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone <repository-url>
cd ac-mcp

# Install dependencies
uv sync

Configuração

Converter Dados do APLCart

Primeiro, baixe e converta os dados TSV do APLCart para o formato JSONL:

# Using uv
uv run python aplcart2json.py

# Or with activated venv
python aplcart2json.py

# Optional: Generate SQLite database for faster searches
python aplcart2json.py --db

Gerar Embeddings (Opcional; para Busca Semântica)

Para habilitar a funcionalidade de busca semântica:

# Set your OpenAI API key
export OPENAI_API_KEY='your-api-key-here'

# Generate embeddings
uv run python generate_embeddings.py

# Or with activated venv
python generate_embeddings.py

Isso cria:

• aplcart.index - arquivo de índice FAISS contendo embeddings
• aplcart_metadata.pkl - Metadados para resultados de busca semântica

Uso

Executando o Servidor MCP

# Basic usage
uv run python aplcart_mcp_semantic.py

# With SQLite database backend
APLCART_USE_DB=1 uv run python aplcart_mcp_semantic.py

Usando com Claude Code

O projeto inclui um arquivo .mcp.json.template que configura automaticamente o servidor MCP. Salve-o como .mcp.json, atualize-o com seus dados e execute /mcp no Claude Code para ver os servidores disponíveis.

Você também pode adicionar o servidor manualmente:

claude mcp add aplcart "uv run python aplcart_mcp_semantic.py"

Usando com Claude Desktop

Adicione isto ao seu arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "aplcart": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "YOUR/PATH/HERE/ac-mcp",
        "python",
        "aplcart_mcp_semantic.py"
      ],
      "env": {
        "APLCART_USE_DB": "1",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Em seguida, reinicie o Claude Desktop para carregar o servidor MCP.

Ferramentas MCP Disponíveis

• lookup-syntax - Correspondência exata na sintaxe APL

  Example: lookup-syntax "⍳10"
  

• search - Busca por substring em sintaxe, descrição e palavras-chave

  Example: search "matrix" limit=10
  

• keywords-for - Obter palavras-chave para uma sintaxe específica

  Example: keywords-for "∘.≤⍨∘⍳"
  

• semantic-search - Busca em linguagem natural usando embeddings

  Example: semantic-search "how to split a string on a separator"
  

Ferramenta de Busca Independente

Você também pode usar a funcionalidade de busca semântica diretamente:

# Interactive mode
uv run python search_embeddings.py

# Single query
uv run python search_embeddings.py "find the largest number"

# JSON output
uv run python search_embeddings.py "reverse an array" --json

# More results
uv run python search_embeddings.py "matrix operations" -k 10

Comandos do modo interativo:

• Digite sua consulta e pressione Enter para buscar
• Digite quit, exit ou q para sair (ou Ctrl+D ou Ctrl+C)

Configuração

Variáveis de Ambiente

• OPENAI_API_KEY - Necessária para a funcionalidade de busca semântica
• APLCART_USE_DB - Defina como 1, true ou yes para usar o backend de banco de dados SQLite

Estrutura de Arquivos

ac-mcp/
├── aplcart.jsonl           # Converted APLCart data (run aplcart2json.py to generate)
├── aplcart.db              # SQLite database (optional)
├── aplcart.index           # FAISS embeddings index (run generate_embeddings.py to generate)
├── aplcart_metadata.pkl    # Metadata for semantic search (run generate_embeddings.py to generate)
├── aplcart2json.py         # Converter script
├── generate_embeddings.py  # Embedding generator
├── aplcart_mcp_semantic.py # MCP server with semantic search
├── search_embeddings.py    # Standalone search tool
└── pyproject.toml          # Project dependencies

Sobre o APLCart

APLCart é uma coleção pesquisável de expressões idiomáticas e expressões APL mantida em https://aplcart.info/

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Observação: Os dados do APLCart em si estão sujeitos aos seus próprios termos de licenciamento.