APLCart MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@APLCart MCP Server how to split a string on a separator"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncSetup
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 --dbGenerate Embeddings (Optional; for Semantic Search)
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.pyThis creates:
aplcart.index- FAISS index file containing embeddingsaplcart_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.pyUsing 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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 syntaxExample: lookup-syntax "⍳10"search- Substring search across syntax, description, and keywordsExample: search "matrix" limit=10keywords-for- Get keywords for a specific syntaxExample: keywords-for "∘.≤⍨∘⍳"semantic-search- Natural language search using embeddingsExample: 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 10Interactive mode commands:
Type your query and press Enter to search
Type
quit,exit, orqto exit (or Ctrl+D or Ctrl+C)
Configuration
Environment Variables
OPENAI_API_KEY- Required for semantic search functionalityAPLCART_USE_DB- Set to1,true, oryesto 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 dependenciesAbout 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 toolskeywords-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
searchB
Substring search across syntax, description and keywords (case-insensitive).
Inputs: query (required), limit. Returns: result
semantic-searchA
Natural language search using semantic embeddings. Use this for queries in everyday language when exact keywords might not match.
Inputs: query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
MCP server for searching Airweave collections with natural language queries.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- FlicenseNot gradedqualityDmaintenanceAn MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.166-
- AlicenseAqualityDmaintenanceMCP server for semantic code search that indexes your codebase and allows AI editors to search using natural language queries.99 npm52MIT
- AlicenseAqualityBmaintenanceMCP server for semantic code search with AST-aware chunking, hybrid vectors, and query syntax.121Apache 2.0