xpqz/ac-mcp
If you are the rightful owner of ac-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server that provides semantic search capabilities for the APLCart idiom collection.
lookup-syntax
Exact match on APL syntax
search
Substring search across syntax, description, and keywords
keywords-for
Get keywords for a specific syntax
semantic-search
Natural language search using embeddings
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
# 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
Generate 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.py
This 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.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", "python", "YOUR/PATH/HERE/ac-mcp/aplcart_mcp_semantic.py"],
"cwd": "YOUR/PATH/HERE/ac-mcp",
"env": {
"OPENAI_API_KEY": "your-api-key-here",
"APLCART_USE_DB": "1"
}
}
}
}
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=10
-
keywords-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 10
Interactive mode commands:
- Type your query and press Enter to search
- Type
quit
,exit
, orq
to exit (or Ctrl+D or Ctrl+C)
Configuration
Environment Variables
OPENAI_API_KEY
- Required for semantic search functionalityAPLCART_USE_DB
- Set to1
,true
, oryes
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 file for details.
Note: The APLCart data itself is subject to its own licensing terms.