Skip to main content
Glama
APLCart MCP Server
by xpqz

APLCart MCP Server

A Model Context Protocol (MCP) server that exposes the APLCart idiom collection with semantic search capabilities. APLCart is a searchable collection of APL expressions with descriptions.

Features

  • Find APL expressions by exact syntax match

  • Search across syntax, descriptions, and keywords

  • Get keywords for specific APL expressions

  • Natural language queries using OpenAI embeddings

Related MCP server: Axon.MCP.Server

Installation

Prerequisites

  • Python 3.11 or higher

  • OpenAI API key (for semantic search functionality)

Using 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

Setup

Convert APLCart Data

First, fetch and convert the APLCart TSV data to JSONL format:

# 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

To enable semantic search functionality:

# 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

This creates:

  • aplcart.index - FAISS index file containing embeddings

  • aplcart_metadata.pkl - Metadata for semantic search results

Usage

Running the MCP Server

# Basic usage
uv run python aplcart_mcp_semantic.py

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

Using with Claude Code

The project includes a .mcp.json.template file that automatically configures the MCP server. Save that as .mcp.json, update it with your details, and run /mcp in Claude Code to see available servers.

You can also manually add the server:

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

Using with Claude Desktop

Add this to your Claude Desktop configuration file:

  • 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}"
      }
    }
  }
}

Then restart Claude Desktop to load the MCP server.

Available MCP Tools

  • lookup-syntax - Exact match on APL syntax

    Example: lookup-syntax "⍳10"
  • search - Substring search across syntax, description, and keywords

    Example: search "matrix" limit=10
  • keywords-for - Get keywords for a specific syntax

    Example: keywords-for "∘.≤⍨∘⍳"
  • semantic-search - Natural language search using embeddings

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

Standalone Search Tool

You can also use the semantic search functionality directly:

# 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

Interactive mode commands:

  • Type your query and press Enter to search

  • Type quit, exit, or q to exit (or Ctrl+D or Ctrl+C)

Configuration

Environment Variables

  • OPENAI_API_KEY - Required for semantic search functionality

  • APLCART_USE_DB - Set to 1, true, or yes to use SQLite database backend

File Structure

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

About APLCart

APLCart is a searchable collection of APL idioms and expressions maintained at https://aplcart.info/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: The APLCart data itself is subject to its own licensing terms.

Available Tools

4 tools
keywords-forC

Return the keyword list for the given syntax.

Inputs: syntax (required). Returns: result

lookup-syntaxB

Return the record whose syntax exactly matches the input.

Inputs: syntax (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: keywords-for retrieves keyword lists for a syntax, lookup-syntax finds exact matches, search performs substring matching, and semantic-search handles natural language queries. There is no overlap in functionality, making tool selection straightforward for an agent.

    Naming Consistency3/5

    The naming is mixed with hyphenated patterns (keywords-for, lookup-syntax) and single words (search, semantic-search). While readable, it lacks a consistent verb_noun convention, as keywords-for and lookup-syntax use hyphens and different verb styles, whereas search and semantic-search are more descriptive but not uniformly structured.

    Tool Count5/5

    With 4 tools, the server is well-scoped for its apparent purpose of syntax and keyword lookup. Each tool serves a specific function in the domain, and the count is neither too sparse nor excessive, fitting typical expectations for a focused utility server.

    Completeness4/5

    The toolset covers core search and lookup operations effectively, including exact matching, substring search, and semantic search. A minor gap might be the lack of update or management tools if the domain includes mutable data, but for a query-focused server, the coverage is nearly complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides semantic search capabilities by integrating with an OpenSearch-based search service. It enables users to perform complex document searches across multiple indices with support for advanced filtering and robust error handling.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
      166
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for semantic code search that indexes your codebase and allows AI editors to search using natural language queries.
      9
      9 npm
      52
      MIT