APLCart MCP Server

APLCart MCP服务器

一个模型上下文协议（MCP）服务器，它公开了 APLCart 具有语义搜索功能的习语集合。APLCart是一个可搜索的APL表达式集合，其中包含描述。

特性

• 通过精确语法匹配查找APL表达式
• 跨语法、描述和关键字搜索
• 获取特定APL表达式的关键字
• 使用OpenAI嵌入的自然语言查询

安装

先决条件

• Python 3.11或更高版本
• OpenAI API密钥（用于语义搜索功能）

使用紫外线

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone 
cd ac-mcp

# Install dependencies
uv sync

设置

转换APLCart数据

首先，获取APLCart TSV数据并将其转换为JSONL格式：

# 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

生成嵌入（可选；用于语义搜索）

要启用语义搜索功能，请执行以下操作：

# 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

这将创建：

• aplcart.index -包含嵌入的FAISS索引文件
• aplcart_metadata.pkl -语义搜索结果的元数据

用法

运行MCP服务器

# Basic usage
uv run python aplcart_mcp_semantic.py

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

使用Claude代码

该项目包括 .mcp.json.template 自动配置MCP服务器的文件。另存为 .mcp.json，用您的详细信息更新它，然后运行 /mcp 在Claude Code中查看可用服务器。

您还可以手动添加服务器：

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

与Claude Desktop一起使用

将此添加到您的Claude Desktop配置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %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}"
      }
    }
  }
}

然后重新启动Claude Desktop以加载MCP服务器。

可用的MCP工具

• lookup-syntax -APL语法完全匹配

  Example: lookup-syntax "⍳10"

• search -在语法、描述和关键字之间进行子字符串搜索

  Example: search "matrix" limit=10

• keywords-for -获取特定语法的关键字

  Example: keywords-for "∘.≤⍨∘⍳"

• semantic-search -使用嵌入的自然语言搜索

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

独立搜索工具

您还可以直接使用语义搜索功能：

# 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

交互模式命令：

• 键入您的查询，然后按Enter键进行搜索
• 类型 quit, exit，或 q 退出（或Ctrl+D或Ctrl+C）

配置

环境变量

• OPENAI_API_KEY -语义搜索功能所需
• APLCART_USE_DB -设置为 1, true，或 yes 使用SQLite数据库后端

文件结构

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

关于APLCart

APLCart是APL习语和表达的可搜索集合，维护在https://aplcart.info/

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

注：APLCart数据本身受其自身 许可条款.