# APLCart MCP Server

A Model Context Protocol (MCP) server that exposes the [APLCart](https://aplcart.info) 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

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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:
```bash
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`

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

```bash
# 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](LICENSE) file for details.

Note: The APLCart data itself is subject to its own [licensing terms](https://github.com/abrudz/aplcart/blob/master/LICENSE).