开罗上下文MCP工具包
AI的开罗制图师🗺️
精确浏览开罗文档——Starknet证明语言的智能指南👨💻
一个生产就绪的模型上下文协议（MCP）服务器，使用以下命令在Cairo/Starknet文档中提供语义搜索 基于大小的分块, 多提供者嵌入 （双子座/西北风），以及 Qdrant矢量搜索。旨在防止上下文溢出，同时提供最相关的结果。你的AI助手现在可以动态学习Cairo语法。
______________________________________________________________________
🚀 快速开始
先决条件
1.安装Docker：
# macOS (using Homebrew)
brew install docker
# Windows
# Download Docker Desktop from: https://www.docker.com/products/docker-desktop/2.启动Qdrant矢量数据库：
docker run -d -p 6333:6333 qdrant/qdrant3.安装Node.js>=18.0.0 (下载)
设置开罗背景
# 1. Clone and install dependencies
git clone
cd cairo-context
npm install
# 2. Configure your embedding provider
cp .env.example .env
# Edit .env - choose "gemini" or "mistral" and add your API key
# 3. Generate embeddings (one-time setup, ~3-5 minutes)
npm run generate-embeddings
# 4. Build the project (MCP should be online after this step)
npm run build该系统将：
- ✅ 从GitHub下载所有9个文档源
- ✅ 使用漂亮的进度条处理2150+个块
- ✅ 使用您选择的提供商生成嵌入
- ✅ 将所有内容存储在Qdrant中，以进行即时语义搜索
提供商选项：
配置IDE
推荐：Roo（VS代码扩展）
- 安装 Roo扩展
- 点击 3点图标 在Roo→ MCP服务器 → 编辑全局配置
- 添加此配置：
{
"mcpServers": {
"cairo-context": {
"command": "node",
"args": [
"C:\\\\Users\\\\\\\\path\\\\to\\\\cairo-context\\\\dist\\\\src\\\\index.js"
],
"alwaysAllow": [
"get-cairo-example",
"list-cairo-resources",
"semantic-search-cairo"
],
"disabled": false
}
}
}替代IDE：
- 克劳德代码:
claude mcp add cairo-context -- node /path/to/cairo-context/dist/src/index.js - 光标：添加到
~/.cursor/mcp.json（JSON结构与Roo相同）
______________________________________________________________________
为什么是“开罗制图师”？
正如制图师绘制未知领域的地图一样，这个MCP服务器 绘制开罗文献景观图，指导人工智能助手完成以下任务：
- 3个MCP工具 用于语义搜索和代码检索
- 完整的开罗编码器编码器系统 移植到Qdrant
- 8个开罗生产实例
- 2150个文档块 9个综合来源
- 动态文档处理 来自6个GitHub存储库 - 3个人工智能总结知识库 （开罗图书，核心图书馆，Starknet博客）
不再迷失在海量文档中制图员使用自然语言语义搜索动态地摄取、块、索引和检索相关答案。
______________________________________________________________________
特性
🎯 基于大小的语义搜索
问题解决了：以前的MCP服务器已返回 大块路段 在人工智能进行了过于宽泛的搜索后，通过经典的“提示太长”错误消息导致聊天崩溃。
我们的解决方案:
- 基于大小的分块：每个块= 约500个代币 （不是15000）
- 自动令牌舍入:
max_tokens四舍五入到最接近的500 - 分数排序结果：最佳匹配优先（1.0→0.0）
- 可配置的限制：控制两者的相关性(
score_threshold)输出大小(max_tokens)
AI如何调用MCP工具的示例 （仅3个参数）：
semantic-search-cairo({
query: "How do I implement Poseidon hash in a STARK circuit?",
score_threshold: 0.5, // 0.0-1.0 (higher = stricter)
max_tokens: 10000 // Rounds to 10000 (20 chunks of 500 tokens)
})📚 文档来源（共9个）
3 AI汇总来源 （由Cairo Coder预处理）：
- 开罗图书 （234块）-综合语言参考
- 核心库 （167块）-标准库文档
- Starknet博客 （182块）-最新更新和公告
6动态摄入来源 （GitHub克隆+处理）：
- 斯塔克内特文件 （222块）-Starknet官方文件
- 斯塔克内特铸造厂 （681块）-测试框架文档
- 开罗举例 （134个块）-实用代码示例
- OpenZeppelin （166块）-保护合同组件
- 疤痕 （181块）-包管理器文档
- 网站 Starknet.js （183块）-JavaScript SDK指南
总计: 2150块 来自9个来源
💻 代码示例
8个已准备就绪的开罗节目：
- 反向合同 -简单的状态管理
- ERC20代币 -可替换代币标准
- ERC721 NFT -不可替代的代币标准
- 拥有ERC20 -访问控制模式
- 可暂停ERC20 -紧急停止模式
- 再入境警卫 -安全模式
- 回滚组件 -状态恢复模式
- 调试值 -调试技术
______________________________________________________________________
建筑
逆向工程开罗编码器Ingester→ Qdrant
我们完全移植了Cairo Coder基于PostgreSQL的ingester系统，以与Qdrant配合使用，实现：
9 Sources → Dynamic Ingestion → Gemini Embeddings (3072D) → Qdrant → Semantic Search重大工程成就:
- ✅ 整个开罗Coder ingester建筑 （9个专业入口，20多个实用程序）
- ✅ 已创建Qdrant适配器 (
qdrantVectorStore.ts) - ✅ Python包装器 OpenZeppelin（安托拉）和Starknet Foundry（mdbook）
- ✅ 自动尺寸检测 （3072D全双子座嵌入）
- ✅ 增量更新 （检测内容更改，仅更新修改的块）
我们替换了什么:
- PostgreSQL + pgvector extension
- Complex database migrations
- Manual dependency management我们建造了什么:
+ Qdrant vector database (1 container, auto-refilled)
+ Full Cairo Coder ingester compatibility for all 9 sources
+ Gemini or Mistral embeddings
+ Python bypass wrappers for 2 of the sources
+ Automatic collection dimension matching
+ <200ms query latency across 2,150 chunks______________________________________________________________________
可用工具（共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个块，默认）
示例用法:
// Broad search with default settings
{
query: "How do I implement Poseidon hash in a STARK circuit?",
score_threshold: 0.5,
max_tokens: 50000
}
// Precise search with limited output
{
query: "felt252 modular arithmetic",
score_threshold: 0.7,
max_tokens: 5000 // Returns ~10 highly relevant chunks
}
// Exploration mode
{
query: "storage optimization techniques",
score_threshold: 0.3,
max_tokens: 20000 // Returns ~40 loosely related chunks
}2. get-cairo-example
检索完整的开罗代码示例。
参数:
example_id（必填）-以下之一：
- counter -简单的状态管理 - erc20 -可替换代币 - erc721 -NFT标准 - ownable-erc20 -访问控制 - pausable-erc20 -紧急停止 - reentrancy-guard -安全模式 - rollback-component -国家恢复 - debugging -调试技术
示例:
example_id: "erc20"3. list-cairo-resources
列出所有可用的文档来源和示例。
参数：不需要，只需调用工具即可。
______________________________________________________________________
嵌入
支持的提供商：
Gemini（谷歌人工智能）-默认值
- 模型:
gemini-embedding-001 - 维度: 3072 （最高质量）
- 任务类型:
RETRIEVAL_DOCUMENT对于文档，RETRIEVAL_QUERY用于查询 - 成本：2150块约0.0015美元
- 获取API密钥: https://aistudio.google.com/api-keys
Mistral AI-替代方案
- 模型:
mistral-embed - 维度: 1024 （更快、更具成本效益）
- 成本：2150块约0.0008美元
- 获取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块）
______________________________________________________________________
演出
- 初创公司：\<100ms（无初始化开销）
- 搜索：\<200ms（双子座嵌入+Qdrant查找）
- 记忆：\<50MB（与RAG系统相比重量轻）
- 存储：Qdrant中每个块约5KB（2150个块=约10.7MB）
- 摄入：下载并处理所有9个来源大约需要1-2分钟
- 增量更新：仅重新处理更改的文档
______________________________________________________________________
许可证
麻省理工学院
鸣谢
- 摄入系统：从 KasarLabs/cairo编码器 （完成逆向工程和Qdrant适配）
- 文档：9个来源，包括Cairo Coder的3个AI摘要文档+6个动态摄入的存储库
- 建筑：Roo的代码库搜索工具中的MCP服务器模式+自定义Qdrant矢量存储实现作为灵感