Cocoindex Claude Code

CocoIndex Claude Code

Complete knowledge base system with semantic search for Claude Code CLI

Features • Quick Start • Architecture • Usage • Docs

______________________________________________________________________

提供您的Claude Code命令行界面 语义搜索超能力 在你的当地文件。该项目整合 CocoIndex 通过模型上下文协议（MCP）使用Claude Code，实现智能文档搜索、LLM驱动的元数据提取和完整的本地知识库。

特性

• 语义搜索 -按含义查找文档，而不仅仅是关键字
• MCP集成 -通过MCP协议从Claude Code CLI直接访问
• LLM提取 -使用Claude自动提取标题、摘要和要点
• 向量数据库 -PostgreSQL与pgvector的快速相似性搜索
• 实时更新 -文档更改后会自动重新索引
• FastAPI服务器 -用于编程访问的REST API端点
• CocoInsight -用于流可视化的Web UI

建筑

graph TB
    subgraph "Claude Code CLI"
        CC[Claude Code] -->|MCP Protocol| MCP[CocoIndex MCP Server]
    end

    subgraph "CocoIndex Engine"
        MCP --> Search[Semantic Search]
        MCP --> Index[Document Indexing]
        MCP --> Extract[LLM Extraction]
    end

    subgraph "Data Layer"
        Search --> PG[(PostgreSQL + pgvector)]
        Index --> PG
        Extract --> PG
    end

    subgraph "External APIs"
        Index -->|Embeddings| OpenAI[OpenAI API]
        Extract -->|Extraction| Anthropic[Anthropic Claude]
    end

    Docs[Your Documents] -->|Watch| Index

快速开始

先决条件

• Docker 桌面版 -对于带有pgvector的PostgreSQL
• Python 3.11+ -CocoIndex要求
• OpenAI API密钥 -用于文本嵌入
• 无烟煤API密钥 -用于LLM提取（可选）

1.克隆和设置

# Clone the repository
git clone https://github.com/puneet8800/cocoindex-claude-code.git
cd cocoindex-claude-code

# Run the setup script
./scripts/setup.sh

这将：

• 通过Docker使用pgvector启动PostgreSQL
• 创建Python虚拟环境
• 安装所有依赖项
• 设置CocoIndex后端表

2.配置环境

# Copy the example environment file
cp .env.example .env

# Edit .env and add your API keys
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

3.添加您的文档

# Add markdown, text, or Python files to be indexed
cp your-docs/*.md data/documents/

4.索引文件

source .venv/bin/activate
cocoindex update main.py

5.配置克劳德代码

添加到您的 ~/.claude.json:

{
  "mcpServers": {
    "cocoindex": {
      "command": "/path/to/cocoindex-claude-code/.venv/bin/python",
      "args": ["/path/to/cocoindex-claude-code/mcp_server.py"],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgres://cocoindex:cocoindex@localhost/cocoindex"
      }
    }
  }
}

6.在克劳德代码中使用

现在在Claude Code中，您可以使用语义搜索：

> Search my documents for authentication best practices
> What documents mention API rate limiting?
> Find all content related to database migrations

运作原理

数据流

sequenceDiagram
    participant U as User
    participant CC as Claude Code
    participant MCP as MCP Server
    participant CI as CocoIndex
    participant DB as PostgreSQL
    participant OAI as OpenAI

    U->>CC: "Search for auth docs"
    CC->>MCP: cocoindex_search(query)
    MCP->>CI: search(query)
    CI->>OAI: Generate query embedding
    OAI-->>CI: Vector [1536 dims]
    CI->>DB: Vector similarity search
    DB-->>CI: Top K results
    CI-->>MCP: Formatted results
    MCP-->>CC: JSON response
    CC-->>U: Relevant document chunks

索引管道

flowchart LR
    A[📄 Documents] -->|LocalFile Source| B[Split into Chunks]
    B -->|2000 chars, 500 overlap| C[Generate Embeddings]
    C -->|text-embedding-3-small| D[Store Vectors]
    D -->|pgvector| E[(PostgreSQL)]

MCP工具可用

当连接到Claude Code时，这些工具变得可用：

用法

命令行搜索

# Activate virtual environment
source .venv/bin/activate

# Interactive search
python scripts/query.py

# Single query
python scripts/query.py "machine learning best practices"

# With result limit
python scripts/query.py -l 10 "python async patterns"

FastAPI服务器

# Start the API server
python main.py

# Or with live reloading
uvicorn main:app --reload

API终点：

• GET / -API信息
• GET /health -健康检查
• GET /flows -列出已注册的流
• GET /search?q=query&limit=5 -搜索文档
• GET /docs -Swagger用户界面

CocoInsight Web用户界面

# Start server with CocoInsight support
cocoindex server main.py -ci

# Open https://cocoindex.io and connect to localhost:49344

项目结构

cocoindex-claude-code/
├── flows/                  # CocoIndex flow definitions
│   ├── text_embedding.py   # Vector search flow (OpenAI embeddings)
│   └── llm_extraction.py   # LLM metadata extraction (Claude)
├── scripts/                # Utility scripts
│   ├── setup.sh            # Initial setup
│   ├── start.sh            # Start services
│   ├── stop.sh             # Stop services
│   └── query.py            # Interactive search CLI
├── docker/                 # Docker configuration
│   └── compose.yaml        # PostgreSQL with pgvector
├── data/documents/         # Your documents go here
├── docs/                   # Documentation
├── main.py                 # FastAPI entry point
├── mcp_server.py           # MCP server for Claude Code
├── pyproject.toml          # Python dependencies
└── .env.example            # Environment template

文档

• 入门指南 -详细的设置说明
• 建筑 -系统设计和组件
• MCP集成 -Claude代码配置
• 流程说明 -CocoIndex流程文档
• 故障排除 -常见问题和解决方案

流动

文本嵌入流程

为语义搜索的文档建立索引：

1. 从以下位置读取文件 data/documents/
2. 分割成块（2000个字符，500个重叠）
3. 使用OpenAI生成嵌入 text-embedding-3-small
4. 使用向量索引在PostgreSQL中存储

支持的文件类型： .md, .txt, .py

LLM萃取流量

使用Claude提取结构化元数据：

• 标题
• 摘要
• 要点
• 话题
• 文档类型

要求： ANTHROPIC_API_KEY 在 .env

CLI命令参考

# List all flows
cocoindex ls main.py

# Show flow details
cocoindex show main.py:TextEmbedding

# Setup backend tables
cocoindex setup main.py -f

# Update index (one-time)
cocoindex update main.py

# Update index (continuous/live)
cocoindex update main.py -L

# Evaluate without exporting
cocoindex evaluate main.py -o ./output

# Start server with CocoInsight
cocoindex server main.py -ci -L --reload

# Drop all backend tables
cocoindex drop main.py

贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• CocoIndex -为该项目提供动力的索引引擎
• 克劳德代码 -克劳德的Anthropic CLI
• pg向量 -PostgreSQL的向量相似性搜索

______________________________________________________________________

Made with ❤️ for the Claude Code community