开罗上下文MCP
项目介绍
<div align="center">
1.
2.
3.
Cairo Context MCP Toolkit
AI的Cairo制图师 🗺️
<img src="https://gips0.baidu.com/it/u=2028358583,1942168488&fm=3081&app=3081&f=PNG?w=1036&h=1036" alt="Cairo Cartographer Logo" width="300" /> <br></br>精准导航Cairo文档——您智能的Starknet证明语言向导 👨💻
</div>一个生产就绪的模型上下文协议（MCP）服务器，使用基于大小的分块、多提供商嵌入（Gemini/Mistral）和Qdrant向量搜索在Cairo/Starknet文档中提供语义搜索。构建以防止上下文溢出并提供最相关的结果。您的AI助手现在可以实时学习Cairo语法。
🚀 快速开始
先决条件
1. 安装Docker：
# macOS（使用Homebrew）
brew install docker
# Windows
# 从以下链接下载Docker Desktop：https://www.docker.com/products/docker-desktop/
2. 启动Qdrant向量数据库：
docker run -d -p 6333:6333 qdrant/qdrant
3. 安装Node.js >= 18.0.0 (下载)
设置Cairo上下文
# 1. 克隆并安装依赖项
git clone <repo-url>
cd cairo-context
npm install
# 2. 配置您的嵌入提供商
cp .env.example .env
# 编辑.env - 选择“gemini”或“mistral”，并添加您的API密钥
# 3. 生成嵌入（一次性设置，约3-5分钟）
npm run generate-embeddings
# 4. 构建项目（此步骤后MCP应在线）
npm run build
系统将执行以下操作：
- ✅ 从GitHub下载所有9个文档来源
- ✅ 处理超过2,150个块，并带有漂亮的进度条
- ✅ 使用您选择的提供商生成嵌入
- ✅ 将所有内容存储在Qdrant中，以便进行即时语义搜索
提供商选项：
配置您的IDE
推荐：Roo（VS Code扩展）
- 安装Roo扩展
- 在Roo中点击三个点图标 → MCP服务器 → 编辑全局配置
- 添加以下配置：
{
"mcpServers": {
"cairo-context": {
"command": "node",
"args": [
"C:\\\\Users\\\\<your-username>\\\\path\\\\to\\\\cairo-context\\\\dist\\\\src\\\\index.js"
],
"alwaysAllow": [
"get-cairo-example",
"list-cairo-resources",
"semantic-search-cairo"
],
"disabled": false
}
}
}
替代IDE：
- Claude Code：
claude mcp add cairo-context -- node /path/to/cairo-context/dist/src/index.js - Cursor：添加到
~/.cursor/mcp.json（与Roo相同的JSON结构）
为什么叫“Cairo制图师”？
正如制图师绘制未知领域一样，这个MCP服务器绘制了Cairo文档的地形图，引导AI助手通过：
- 3个MCP工具用于语义搜索和代码检索
- 完整的Cairo Coder导入系统移植到Qdrant
- 8个生产Cairo示例
- 2,150个文档块跨越9个全面的来源
- 动态文档处理来自6个GitHub仓库
- 3个人工智能总结的知识库（Cairo书、核心库、Starknet博客）
再也不用迷失在庞大的文档中。制图师动态地摄取、分块、索引并使用自然语言语义搜索检索相关信息。
特性
🎯 基于大小的语义搜索
解决的问题：之前的MCP服务器在AI进行了过于广泛的搜索后返回巨大的部分，导致聊天崩溃，出现经典的“提示太长”错误消息。
我们的解决方案：
- 基于大小的分块：每个块 = 约500个标记（不是15,000）
- 自动标记舍入：
max_tokens向上舍入到最近的500 - 按分数排序的结果：最佳匹配优先（1.0 → 0.0）
- 可配置限制：控制相关性（
score_threshold）和输出大小（max_tokens）
AI调用MCP工具的示例（仅3个参数）：
semantic-search-cairo({
query: "如何在STARK电路中实现Poseidon哈希？",
score_threshold: 0.5, // 0.0-1.0（越高越严格）
max_tokens: 10000 // 舍入到10000（20个500标记的块）
})
📚 文档来源（总计9个）
3个人工智能总结的来源（由Cairo Coder预处理）：
- Cairo书（234个块）- 综合语言参考
- 核心库（167个块）- 标准库文档
- Starknet博客（182个块）- 最新更新和公告
6个动态摄取的来源（GitHub克隆+处理）：
- Starknet文档（222个块）- 官方Starknet文档
- Starknet Foundry（681个块）- 测试框架文档
- Cairo示例（134个块）- 实用代码示例
- OpenZeppelin（166个块）- 安全合约组件
- Scarb（181个块）- 包管理器文档
- Starknet.js（183个块）- JavaScript SDK指南
总计：2,150个块跨越9个来源
💻 代码示例
8个生产就绪的Cairo程序：
- 计数器合约 - 简单的状态管理
- ERC20代币 - 可互换代币标准
- ERC721 NFT - 不可互换代币标准
- 可控ERC20 - 访问控制模式
- 暂停ERC20 - 应急停止模式
- 重入防护 - 安全模式
- 回滚组件 - 状态恢复模式
- 调试值 - 调试技术
架构
反向工程Cairo Coder导入器 → Qdrant
我们完全将Cairo Coder基于PostgreSQL的导入器系统移植到Qdrant，实现了：
9个来源 → 动态摄取 → Gemini嵌入（3072D）→ Qdrant → 语义搜索
重大工程成就：
- ✅ 移植整个Cairo Coder导入器架构（9个专业导入器，20多个实用工具）
- ✅ 创建Qdrant适配器（
qdrantVectorStore.ts） - ✅ Python包装器针对OpenZeppelin（Antora）和Starknet Foundry（mdbook）
- ✅ 自动维度检测（3072D完整的Gemini嵌入）
- ✅ 增量更新（检测内容更改，仅更新修改过的块）
我们替换的内容：
- PostgreSQL + pgvector扩展
- 复杂的数据库迁移
- 手动依赖关系管理
我们构建的内容：
+ Qdrant向量数据库（1个容器，自动填充）
+ 对所有9个来源的完整Cairo Coder导入器兼容性
+ Gemini或Mistral嵌入
+ 2个来源的Python绕行包装器
+ 自动集合维度匹配
+ 跨越2,150个块的<200毫秒查询延迟
可用工具（总计3个）
1. semantic-search-cairo（主要搜索工具）
使用自然语言查询进行语义搜索，由Gemini嵌入和Qdrant驱动。
参数（简化为2个）：
query（必需） - 自然语言问题score_threshold（可选） - 0.0-1.0，步长为0.05（默认：0.5）max_tokens（可选） - 默认：50000，最小：500（自动舍入到最近的500）
标记舍入示例：
290→500（最少1个块）750→1000（2个块）2400→2500（5个块）10000→10000（20个块）50000→50000（100个块，默认）
示例用法：
// 使用默认设置的广泛搜索
{
query: "如何在STARK电路中实现Poseidon哈希？",
score_threshold: 0.5,
max_tokens: 50000
}
// 输出有限的精确搜索
{
query: "felt252模运算",
score_threshold: 0.7,
max_tokens: 5000 // 返回约10个高度相关的块
}
// 探索模式
{
query: "存储优化技术",
score_threshold: 0.3,
max_tokens: 20000 // 返回约40个松散相关的块
}
2. get-cairo-example
检索完整的Cairo代码示例。
参数：
example_id（必需） - 之一：counter- 简单的状态管理erc20- 可互换代币erc721- NFT标准ownable-erc20- 访问控制pausable-erc20- 应急停止reentrancy-guard- 安全模式rollback-component- 状态恢复debugging- 调试技术
示例：
example_id: "erc20"
3. list-cairo-resources
列出所有可用的文档来源和示例。
参数：无需参数，只需调用该工具即可。
嵌入
支持的提供商：
Gemini（Google AI）- 默认
- 模型：
gemini-embedding-001 - 维度：3072（最高质量）
- 任务类型：
RETRIEVAL_DOCUMENT用于文档，RETRIEVAL_QUERY用于查询 - 成本：~$0.0015用于2,150个块
- 获取API密钥：https://aistudio.google.com/api-keys
Mistral AI - 替代
- 模型：
mistral-embed - 维度：1024（更快，更经济）
- 成本：~$0.0008用于2,150个块
- 获取API密钥：https://console.mistral.ai/api-keys
特性：
- 自动维度匹配：系统检测嵌入尺寸并在需要时重新创建集合
- 提供商切换：在
.env中更改提供商并重新运行嵌入生成 - LangChain集成：两个提供商都使用统一接口
向量数据库
- Qdrant运行在
localhost:6333 - 集合：
cairo-docs - 距离度量：余弦相似度
- 向量：2,150（从9个来源动态摄取）
- 自动管理：如果检测到维度不匹配，集合会自动重新创建
搜索质量
分数阈值指南：
0.9-1.0- 几乎完全匹配0.7-0.9- 高相似度（建议用于精确查询）0.5-0.7- 中等相似度（默认，良好的平衡）0.3-0.5- 较广范围匹配0.0-0.3- 非常宽松匹配（可能包括无关结果）
标记限制指南：
500- 最小（1个块）5000- 快速参考（约10个块）10000- 中等探索（约20个块）50000- 深度挖掘（默认，约100个块）
性能
- 启动：<100毫秒（无初始化开销）
- 搜索：<200毫秒（Gemini嵌入+Qdrant查找）
- 内存：<50MB（与RAG系统相比轻量级）
- 存储：~5KB每块在Qdrant中（2,150个块 = ~10.7MB）
- 摄取：~1-2分钟下载并处理所有9个来源
- 增量更新：仅重新处理更改的文档
许可证
MIT
致谢
- 导入器系统：从KasarLabs/cairo-coder移植（完全反向工程和Qdrant适配）
- 文档：9个来源，包括Cairo Coder的3个人工智能总结文档+6个动态摄取的仓库
- 架构：MCP服务器模式+自定义Qdrant向量存储实现，灵感来自Roo的codebase_search工具