Personal Koi MCP

个人KOI MCP服务器

通过模型上下文协议（MCP）进行个人知识管理。使用语义搜索搜索您的电子邮件、黑曜石保险库和克劳德代码会话。

这有什么作用

快速开始

1.先决条件

• 运行在端口8351上的个人KOI API
• 端口8091上的BGE嵌入服务器
• PostgreSQL数据库 personal_koi

此本地堆栈不共享Octo的数据库。它使用自己的KOI后端部署和 personal_koi DB，即使后端来自同一个数据库 koi-processor 生物区域节点使用的代码库家族。

# Start the backend
~/.config/personal-koi/start.sh

2.配置克劳德代码

添加 ~/.mcp.json:

{
  "mcpServers": {
    "personal-koi": {
      "command": "node",
      "args": ["/Users/darrenzal/projects/personal-koi-mcp/dist/index.js"],
      "env": {
        "KOI_API_ENDPOINT": "http://localhost:8351",
        "KOI_BACKEND_URL": "http://localhost:8351",
        "MCP_SERVER_NAME": "personal-koi"
      }
    }
  }
}

启用 ~/.claude/settings.local.json:

{
  "enabledMcpjsonServers": ["personal-koi"]
}

3.重新启动克劳德代码

可用工具

知识搜索

示例：

search(query="hackathon", source="email")
search(query="regen network carbon credits")

保险库操作

会话搜索

KOI联盟共享（P2P+共享）

钥匙 share_document args：

• recipient --节点别名或节点名称（例如 shawn, cowichan)
• recipient_type — peer （默认）或 commons
• mode — root_only, root_plus_required，或 context_pack
• context_depth --遍历深度（1-4）

例子：

share_document({
  document_path: "projects/koi-protocol-comparison.md",
  recipient: "cowichan",
  recipient_type: "commons",
  mode: "context_pack",
  context_depth: 2
})

实体解析

情境解决方案 （1.5级）：

• 通过 context.organizations 和 context.project 为了消除歧义
• 按实体 associated_people/associated_organizations 领域
• 名称变体的语音匹配（Sean→ 肖恩）
• 2跳关系路径：Person→ Org → 项目

// Example: Resolve ambiguous name with context
vault_ingest_extraction({
  path: "Meetings/My Meeting.md",
  entities: [{
    name: "Sean Anderson",
    type: "Person",
    associated_organizations: ["Symbiocene Labs"]
  }],
  context: {
    organizations: ["Symbiocene Labs"],
    project: "Gaia AI"
  }
})
// Result: Resolves to "Shawn Anderson" @ 93.4% confidence

任务管理

动态查询

这 koi_query 该工具支持任意SELECT查询 $1,$2 参数化值。深度防御：客户端SELECT/WITH预验证、服务器端表白名单、只读事务、5秒超时、参数化强制。需要 QUERY_ENDPOINT_ENABLED=true 在后端(POST /sql 端点）。

索赔引擎

测试：

npm run test:claims  # 8-tool MCP smoke test via handleKoiApiTool()

建筑

此本地设置是一个3存储库堆栈：

• koi-sensors 用于数据摄取(email, claude_sessions、保险库/传感器管道）
• koi-processor 用于存储和查询端点 http://localhost:8351
• personal-koi-mcp 用于Claude Code使用的MCP工具

这里的后端是生物区域节点使用的相同KOI后端代码库的单独部署。共享的是代码和API契约，而不是活动数据库或运行时实例。

运行手册： docs/LOCAL_STACK_RUNBOOK.md

┌─────────────────────────────────────────────────────────────────┐
│                     Personal KOI System                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────┐                ┌────────────────────────┐ │
│  │  personal-koi    │ ◀─────────────▶│  Personal KOI API      │ │
│  │  MCP Server      │                │  (port 8351)           │ │
│  └──────────────────┘                └────────────────────────┘ │
│                                               │                  │
│                                               ▼                  │
│                                      ┌────────────────────────┐ │
│                                      │  PostgreSQL            │ │
│                                      │  personal_koi DB       │ │
│                                      │  - koi_memories        │ │
│                                      │  - koi_embeddings      │ │
│                                      │  - email_metadata      │ │
│                                      │  - session_chunks      │ │
│                                      └────────────────────────┘ │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Data Ingestion                         │   │
│  ├──────────────────────────────────────────────────────────┤   │
│  │                                                           │   │
│  │  ┌──────────────┐  Periodic (30 min)  ┌───────────────┐  │   │
│  │  │ Email Sensor │ ──────────────────▶ │ koi_memories  │  │   │
│  │  └──────────────┘                     └───────────────┘  │   │
│  │                                                           │   │
│  │  ┌──────────────┐  Real-time (fswatch)                   │   │
│  │  │ File Watcher │ ─────────────────────────────────────▶ │   │
│  │  └──────────────┘                                        │   │
│  │                                                           │   │
│  │  ┌──────────────┐  On-demand                             │   │
│  │  │Session Sensor│ ─────────────────────────────────────▶ │   │
│  │  └──────────────┘                                        │   │
│  │                                                           │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

电子邮件同步系统

电子邮件通过两种机制保持更新：

定期同步（launchd）

• 每30分钟跑一次
• 从获取新电子邮件 ~/Mail/Gmail/ （通过mbsync发送邮件目录）
• 生成BGE嵌入并存储在PostgreSQL中

# Check status
launchctl list com.personal-koi.email-sensor

# View logs
tail -f ~/projects/RegenAI/koi-sensors/sensors/email/email_sensor.log

实时监视器（launchd）

• 监视Maildir以获取新文件
• 新电子邮件到达时立即触发索引

# Check status
launchctl list com.personal-koi.email-watcher

手动同步

要手动触发同步，请执行以下操作：

cd ~/projects/RegenAI/koi-sensors/sensors/email
./venv/bin/python email_sensor.py

发展

# Install dependencies
npm install

# Build
npm run build

# Run directly
npm start

相关项目

• koi处理器 -后端API和处理
• koi传感器 -电子邮件和保险库传感器
• regen-koi-mcp -原始再生网络KOI MCP（这是一个分叉）

与摄政王koi mcp的区别

许可证

麻省理工学院