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

Installation

Prerequisites

• Python 3.11 or higher

• OpenAI API key (for semantic search functionality)

Using uv

Setup

Convert APLCart Data

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

Generate Embeddings (Optional; for Semantic Search)

To enable semantic search functionality:

This creates:

• aplcart.index - FAISS index file containing embeddings

• aplcart_metadata.pkl - Metadata for semantic search results

Usage

Running the MCP Server

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:

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

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

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.