Longbow MCP

长弓MCP

一个现代的MCP（模型上下文协议）服务器，具有跨客户端持久内存的实时UI，由Longbow分布式向量数据库及其官方Python SDK提供支持。

特性

• MCP协议：通过stdio和SSE传输实现完整的MCP
• 向量搜索：使用Longbow SDK+句子转换器进行语义记忆搜索
• 混合搜索：矢量+文本搜索与可配置阿尔法混合相结合
• 筛选的搜索：使用元数据谓词过滤器进行矢量搜索
• 按ID搜索：寻找与现有记忆相似的记忆
• 图的运算：内存之间的有向关系边和图遍历
• 实时用户界面：具有Three.js光线行进着色器背景的WebSocket桥
• 设计系统：午夜翡翠-黑曜石、翡翠、赛博石灰玻璃形态
• 一个命令部署: docker compose up -d 开始一切

建筑

graph TD
    %% --- Color Definitions for Dark/Light Mode Compatibility ---
    %% Using a "Nord" style palette for professional, non-clashing look.
    %% Dark desaturated fills with light text ensures readability on both backgrounds.

    %% Standard functional nodes (Dark Blue-Gray fill, Light Blue stroke)
    classDef node_std fill:#3b4252,stroke:#81a1c1,stroke-width:1px,color:#eceff4;

    %% Container/Subgraph (Transparent fill is safest to adapt to background color, light stroke)
    classDef container fill:none,stroke:#d8dee9,stroke-width:2px,stroke-dasharray: 5 5,color:#eceff4;

    %% Database Node (Deeper Gray fill, Cyan stroke)
    classDef db_node fill:#2e3440,stroke:#88c0d0,stroke-width:2px,color:#eceff4,rx:5,ry:5;

    %% UI Node (Muted Purple/Gray fill, Purple stroke)
    classDef ui_node fill:#4c566a,stroke:#b48ead,stroke-width:2px,color:#eceff4;

    %% Ensure connecting lines are light enough to see on dark backgrounds
    linkStyle default stroke:#d8dee9,stroke-width:2px,fill:none;

    %% --- Diagram Structure ---
    subgraph Longbow_MCP [Longbow MCP]
        direction TB
        
        %% Top Row Components
        stdio[MCP stdio
Protocol]:::node_std
        fastapi[FastAPI
+ WebSocket]:::node_std
        
        %% Middle Row Components
        sse[MCP SSE
Transport]:::node_std
        memory[MemoryStore
Longbow]:::node_std
        
        %% Database Component
        %% Using the cylinder shape [()]
        vectordb[(Longbow Vector DB
Arrow Flight gRPC
Data:3000 Meta:3001)]:::db_node

        %% Internal Connections
        stdio  fastapi
        fastapi --> memory
        sse  memory
        memory --> vectordb
    end

    %% External Client
    client[React + Vite UI
Three.js Shader
Bento-Grid HUD]:::ui_node

    %% External Connection using thick arrow ==>
    fastapi ==>|WebSocket| client

    %% Apply Container Class
    class Longbow_MCP container

快速开始

# Clone the repository
git clone https://github.com/TerminallyLazy/longbow-mcp.git
cd longbow-mcp

# Run everything with Docker Compose
docker compose up -d

服务

MCP工具

服务器通过stdio和SSE传输提供这些MCP工具：

核心工具

• add_memory --通过语义嵌入存储新记忆
• search_memories --语义向量相似度搜索（KNN）
• list_memories --列出所有带分页的内存
• delete_all_memories --清除内存存储

搜索工具

• hybrid_search_memories --混合矢量+文本搜索与阿尔法混合(alpha=1.0 纯矢量， alpha=0.0 纯文本）
• search_similar_memory --通过ID查找与现有记忆相似的记忆
• filtered_search_memories --使用元数据谓词过滤器进行矢量搜索（例如。 {"field":"client_id","op":"eq","value":"web-ui"})

图形工具

• add_memory_edge --在两个记忆之间添加有向关系边（带谓词和权重）
• traverse_memory_graph --从起始内存遍历图形（可配置跳数、衰减、方向）

MCP客户端配置

克劳德代码（stdio）

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "longbow-mcp": {
      "command": "python",
      "args": ["server/mcp_server.py"],
      "cwd": "/path/to/longbow-mcp"
    }
  }
}

代理零/SSE客户

MCP SSE传输可在 http://localhost:8765/sse 对于支持服务器发送事件的任何MCP客户端。

在主机上运行的Agent Zero：

{
  "mcpServers": {
    "longbow-mcp": {
      "description": "Persistent vector memory with semantic, hybrid, filtered search and graph operations",
      "url": "http://localhost:8765/sse"
    }
  }
}

Docker中运行的Agent Zero（在Mac/Windows上）：

当你的MCP客户端在自己的Docker容器中运行时， localhost 指的是容器自己的网络，而不是主机。使用 host.docker.internal 要访问主机映射端口：

{
  "mcpServers": {
    "longbow-mcp": {
      "description": "Persistent vector memory with semantic, hybrid, filtered search and graph operations",
      "url": "http://host.docker.internal:8765/sse"
    }
  }
}

Docker中运行的Agent Zero（在Linux上）：

Linux需要额外的主机条目。将此添加到您的Agent Zero服务中 docker-compose.yml:

extra_hosts:
  - "host.docker.internal:host-gateway"

然后使用相同的 host.docker.internal:8765 上面的URL。

共享Docker网络（替代方案）：

如果Longbow MCP和您的客户端都使用Docker Compose，您可以将它们放在同一个网络上。将此添加到客户的 docker-compose.yml:

networks:
  default:
    name: mcp-memory_mcp-network
    external: true

然后直接按服务名称连接：

{
  "mcpServers": {
    "longbow-mcp": {
      "description": "Persistent vector memory with semantic, hybrid, filtered search and graph operations",
      "url": "http://mcp-sse:8765/sse"
    }
  }
}

克劳德桌面版

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "longbow-mcp": {
      "command": "bash",
      "args": ["/path/to/longbow-mcp/run_mcp_server.sh"]
    }
  }
}

API终点

健康与信息

# Health check
curl http://localhost:8000/health

# Memory statistics
curl http://localhost:8000/stats

# Longbow dataset metadata (record count, byte size)
curl http://localhost:8000/dataset/info

内存CRUD

# Add memory
curl -X POST http://localhost:8000/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "TensorFlow is a machine learning framework",
    "metadata": {"category": "ai"}
  }'

# List memories
curl http://localhost:8000/memories

# Delete all
curl -X DELETE http://localhost:8000/memories

搜索

# Vector KNN search
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "machine learning", "top_k": 5}'

# Hybrid search (vector + text blend)
curl -X POST http://localhost:8000/search/hybrid \
  -H "Content-Type: application/json" \
  -d '{"query": "neural networks", "top_k": 5, "alpha": 0.7}'

# Search by memory ID (find similar)
curl -X POST http://localhost:8000/search/by-id \
  -H "Content-Type: application/json" \
  -d '{"memory_id": "550e8400-e29b-41d4-a716-446655440000", "top_k": 5}'

# Filtered search (vector + metadata predicates)
curl -X POST http://localhost:8000/search/filtered \
  -H "Content-Type: application/json" \
  -d '{
    "query": "deep learning",
    "top_k": 5,
    "filters": [{"field": "client_id", "op": "eq", "value": "web-ui"}]
  }'

图

# Add relationship edge
curl -X POST http://localhost:8000/graph/edge \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "uuid-1",
    "target_id": "uuid-2",
    "predicate": "related_to",
    "weight": 0.9
  }'

# Traverse graph from a memory
curl -X POST http://localhost:8000/graph/traverse \
  -H "Content-Type: application/json" \
  -d '{
    "start_id": "uuid-1",
    "max_hops": 3,
    "weighted": true
  }'

坚持

# Trigger manual snapshot
curl -X POST http://localhost:8000/snapshot

WebSocket操作

连接到 ws://localhost:8000/ws 并发送JSON消息：

UI组件

• Three背景.tsx -光线行进着色器（对内存计数做出反应）
• 内存HUD.tsx -主便当网格仪表板
• 记忆卡.tsx -具有发光效果的个人记忆
• 搜索面板.tsx -语义搜索界面
• 添加内存表单.tsx -使用元数据创建内存
• 使用Memory Bridge.ts -WebSocket挂钩用于实时更新

设计系统

午夜翡翠主题：

• 背景：#050505（黑曜石）
• 初级：#5EF7A6（祖母绿）
• 口音：#FFFF21（Cyber Lime）
• 排版：Space Grotesk
• 风格：玻璃造型、便当格、霓虹灯

文件结构

longbow-mcp/
├── docker-compose.yml         # Services orchestration
├── run_mcp_server.sh          # MCP stdio runner
├── run_mcp_sse.sh             # MCP SSE runner
├── setup.sh                   # Local dev setup
├── server/
│   ├── Dockerfile.server      # Python container
│   ├── requirements.txt       # Dependencies (Longbow SDK)
│   ├── models.py             # Pydantic models
│   ├── memory_store.py       # Longbow SDK vector storage
│   ├── mcp_tools.py          # Shared MCP tool definitions & handlers
│   ├── mcp_server.py         # MCP stdio protocol
│   ├── mcp_server_sse.py     # MCP SSE protocol
│   └── api.py                # FastAPI + WebSocket + REST
└── ui/
    ├── Dockerfile.ui          # Node container
    ├── nginx.conf            # Reverse proxy
    ├── package.json          # Dependencies
    ├── tailwind.config.js    # Design system
    ├── vite.config.ts        # Build config
    └── src/
        ├── main.tsx          # Entry point
        ├── App.tsx           # Main app
        ├── hooks/
        │   └── useMemoryBridge.ts
        ├── components/
        │   ├── ThreeBackground.tsx
        │   ├── MemoryHUD.tsx
        │   ├── MemoryCard.tsx
        │   ├── SearchPanel.tsx
        │   └── AddMemoryForm.tsx
        └── styles/
            └── index.css

手动启动（无Docker）

# Terminal 1: Start Longbow (requires Longbow installed)
longbow serve

# Terminal 2: Start API server
cd server
pip install -r requirements.txt
uvicorn api:app --host 0.0.0.0 --port 8000

# Terminal 3: Start MCP SSE server
cd server
python mcp_server_sse.py

# Terminal 4: Start UI dev server
cd ui
npm install
npm run dev

技术栈

后端：

• Python 3.11
• 快速API
• Longbow SDK(longbowclientsdk)——Longbow矢量数据库的官方Python客户端
• Longbow（Apache Arrow Flight gRPC）——矢量存储、图形、混合搜索
• 句子变换器（全MiniLM-L6-v2）--384个dim嵌入
• MCP SDK（标准IO+SSE传输）
• Starlette（SSE服务器）
• 双向通信

前端：

• 反应18
• TypeScript
• 快5
• Three.js（raymarching）
• Tailwind CSS
• Lucide图标

基础设施：

• 码头工人
• Docker Compose
• Nginx

许可证

麻省理工学院