APLCart MCP Server

Servidor MCP de APLCart

Un servidor de Model Context Protocol (MCP) que expone la colección de modismos APLCart con capacidades de búsqueda semántica. APLCart es una colección buscable de expresiones APL con descripciones.

Características

• Encuentra expresiones APL por coincidencia exacta de sintaxis
• Busca entre sintaxis, descripciones y palabras clave
• Obtén palabras clave para expresiones APL específicas
• Consultas en lenguaje natural usando embeddings de OpenAI

Instalación

Requisitos previos

• Python 3.11 o superior
• Clave de API de OpenAI (para la funcionalidad de búsqueda 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

Configuración

Convertir datos de APLCart

Primero, obtén y convierte los datos TSV de APLCart al 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

Generar embeddings (opcional; para búsqueda semántica)

Para habilitar la funcionalidad de búsqueda 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

Esto crea:

• aplcart.index - archivo de índice FAISS que contiene los embeddings
• aplcart_metadata.pkl - metadatos para los resultados de búsqueda semántica

Uso

Ejecutar el 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

Usar con Claude Code

El proyecto incluye un archivo .mcp.json.template que configura automáticamente el servidor MCP. Guárdalo como .mcp.json, actualízalo con tus datos y ejecuta /mcp en Claude Code para ver los servidores disponibles.

También puedes agregar el servidor manualmente:

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

Usar con Claude Desktop

Agrega esto a tu archivo de configuración de 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}"
      }
    }
  }
}

Luego reinicia Claude Desktop para cargar el servidor MCP.

Herramientas MCP disponibles

• lookup-syntax - Coincidencia exacta en sintaxis APL

  Example: lookup-syntax "⍳10"
  

• search - Búsqueda de subcadenas en sintaxis, descripción y palabras clave

  Example: search "matrix" limit=10
  

• keywords-for - Obtén palabras clave para una sintaxis específica

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

• semantic-search - Búsqueda en lenguaje natural usando embeddings

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

Herramienta de búsqueda independiente

También puedes usar la funcionalidad de búsqueda semántica directamente:

# 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 del modo interactivo:

• Escribe tu consulta y presiona Enter para buscar
• Escribe quit, exit o q para salir (o Ctrl+D o Ctrl+C)

Configuración

Variables de entorno

• OPENAI_API_KEY - Requerida para la funcionalidad de búsqueda semántica
• APLCART_USE_DB - Configúrala en 1, true o yes para usar el backend de base de datos SQLite

Estructura de archivos

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

Acerca de APLCart

APLCart es una colección buscable de modismos y expresiones APL mantenida en https://aplcart.info/

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Nota: Los datos de APLCart en sí están sujetos a sus propios términos de licencia.