AI导哈

语义记忆存储检索协议

Arca MCP是一个基于FastAPI和FastMCP构建的模型上下文协议服务器，通过向量嵌入提供语义记忆存储和检索功能，适用于AI代理和程序化集成。

  • by m0nochr0me
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 m0nochr0me/arca-mcp

使用说明

MCP 方舟

一种模型上下文协议（MCP）服务器，通过向量嵌入提供语义记忆存储和检索。使用FastAPI+FastMCP构建，使用LanceDB进行矢量存储，使用Google Gemini进行嵌入生成。

特性

  • 语义搜索 --使用由向量相似性搜索支持的自然语言查询来存储和检索记忆
  • 双重访问 -用于AI代理的MCP工具+用于编程集成的REST API
  • 知识图谱 --用定向、标记的边连接记忆并遍历它们
  • 多租户隔离 --命名空间范围的操作通过 X-Namespace HTTP标头
  • Bucket组织 --将内存分组到逻辑桶中进行结构化存储
  • JSON画布导出 --将水桶的记忆和联系渲染为 JSON画布 文件
  • 文件摄入 （可选附加组件） --通过 arca-ingest 包装(uv sync --extra ingest)，暴露为 POST /v1/ingest 和那个 memory/ingest 工具
  • 嵌入缓存 -用于生成嵌入的Redis-supported缓存，以最大限度地减少API调用
  • 承载令牌认证 --用于安全访问的恒定时间令牌验证

先决条件

  • Python 3.14+
  • 紫外线 包管理器
  • 瑞迪斯
  • Google API密钥（用于Gemini嵌入）

快速开始

# Clone the repository
git clone https://github.com/m0nochr0me/arca-mcp.git
cd arca-mcp

# Install dependencies
uv sync --locked

# Configure environment — create a .env with at least the required secrets
cat > .env <<'EOF'
ARCA_APP_AUTH_KEY=your-secret-bearer-token
ARCA_GOOGLE_API_KEY=your-google-api-key
EOF

# Run the server
python -m app

服务器启动于 http://0.0.0.0:4201 默认情况下，MCP接口位于 /app/mcp 和上的REST API /v1。参见 配置 对于所有可用设置。

码头工人

# Build (core, no add-ons)
docker build -t arca-mcp .

# Build with the document-ingestion add-on (txt/md only)
docker build --build-arg ARCA_INSTALL_EXTRAS=ingest -t arca-mcp .

# Build with ingestion + every format loader (PDF/DOCX/HTML/EPUB/FB2)
docker build --build-arg ARCA_INSTALL_EXTRAS=ingest-all -t arca-mcp .

# Run
docker run -p 4201:4201 \
  -e ARCA_APP_AUTH_KEY=your-secret-key \
  -e ARCA_GOOGLE_API_KEY=your-google-api-key \
  -e ARCA_REDIS_HOST=host.docker.internal \
  arca-mcp

Docker镜像使用Python 3.14 slim和UV进行依赖管理。在以下位置安装卷 ARCA_VECTOR_STORE_PATH （默认值 ./lancedb)在容器重启期间持久化数据。

ARCA_INSTALL_EXTRAS 选择一个可选项 额外的 在构建时安装： ingest 对于基本附加组件（txt/md），或 ingest-all 对于插件和所有格式解析器。构建arg需要一个额外的参数 名字 --不是a pkg[extra] 类似说明符 ingest[all].

MCP客户端配置

示例 .mcp.json 用于连接MCP客户端（例如Claude Code）：

{
  "mcpServers": {
    "arca_memory": {
      "type": "http",
      "url": "http://localhost:4201/app/mcp",
      "headers": {
        "Authorization": "Bearer <your-auth-key>",
        "X-namespace": "my_namespace"
      }
    }
  }
}

<your-auth-key> 必须匹配 ARCA_APP_AUTH_KEYThe X-namespace header将所有操作范围限定在一个租户（默认为 "default" 如果省略）。

文档

深度参考材料存在于 doc/:

  • 配置 --全部 ARCA_ 环境变量及其默认值
  • MCP工具 --the memory/* 工具参考（添加、获取、图遍历等）
  • REST API — /v1/* 端点引用 curl 例子
  • 建筑 --请求流、模块布局、关键模式、技术栈

许可证

看 许可证.

相关 MCP