MCP 方舟
一种模型上下文协议（MCP）服务器，通过向量嵌入提供语义记忆存储和检索。使用FastAPI+FastMCP构建，使用LanceDB进行矢量存储，使用Google Gemini进行嵌入生成。
特性
- 语义搜索 --使用由向量相似性搜索支持的自然语言查询来存储和检索记忆
- 双重访问 -用于AI代理的MCP工具+用于编程集成的REST API
- 多租户隔离 --命名空间范围的操作通过
X-NamespaceHTTP标头 - Bucket组织 --将内存分组到逻辑桶中进行结构化存储
- 嵌入缓存 -用于生成嵌入的Redis-supported缓存，以最大限度地减少API调用
- 承载令牌认证 --用于安全访问的恒定时间令牌验证
先决条件
- Python 3.14+
- 紫外线 包管理器
- 瑞迪斯
- Google API密钥（用于Gemini嵌入）
快速开始
# Clone the repository
git clone https://github.com/your-org/arca-mcp.git
cd arca-mcp
# Install dependencies
uv sync --locked
# Configure environment
cp .env.example .env
# Edit .env with your ARCA_GOOGLE_API_KEY and ARCA_APP_AUTH_KEY
# Run the server
python -m app服务器启动于 http://0.0.0.0:4201 默认情况下，MCP可在 /app/mcp 和REST API /v1.
配置
所有设置都是通过环境变量配置的 ARCA_ 前缀，或通过 .env 文件。
|变量|类型|默认值|描述| | - | - | - | - | | ARCA_APP_HOST | str | 0.0.0.0 |服务器绑定地址| | ARCA_APP_PORT | int | 4201 |服务器端口| | ARCA_APP_WORKERS | int | 1 |Uvicorn工人人数| | ARCA_APP_AUTH_KEY | str | 必需的 |MCP身份验证的承载令牌| | ARCA_TRANSPORT | str | streamable-http |MCP传输(stdio, http, sse, streamable-http) | | ARCA_DEBUG | bool | false |启用调试模式| | ARCA_LOG_MESSAGE_MAX_LEN | int | 2000 |最大日志消息长度| | ARCA_GOOGLE_API_KEY | str | 必需的 |Gemini嵌入的Google API密钥| | ARCA_EMBEDDING_MODEL | str | gemini-embedding-001 |Gemini嵌入模型名称| | ARCA_EMBEDDING_DIMENSION | int | 3072 |嵌入向量维度| | ARCA_VECTOR_STORE_PATH | str | ./lancedb |LanceDB存储目录| | ARCA_REDIS_HOST | str | localhost |Redis主机| | ARCA_REDIS_PORT | int | 6379 |Redis端口| | ARCA_REDIS_DB_CACHE | int | 4 |缓存的Redis数据库编号| | ARCA_REDIS_PASSWORD | str | null |Redis密码（可选）| | ARCA_CACHE_TTL | int | 3600 |默认缓存TTL（秒）（1小时）| | ARCA_CACHE_TTL_LONG | int | 604800 |以秒为单位的长缓存TTL（7天，用于嵌入）|
MCP工具
所有工具都安装在 memory 命名空间。操作的作用域为通过提供的命名空间 X-namespace HTTP标头（默认为 "default").
memory/add
使用向量嵌入将内容存储在内存中。
|参数|类型|必填|说明| | - | - | - | - | | content | str |是|要存储的内容| | bucket | str \| null |no |存储桶名称（默认为 "default") | | connected_nodes | list[str] \| null |创建时没有要链接的节点的UUID| | relationship_types | list[str] \| null |否|并行关系标签 connected_nodes |
退货： { "status": "Memory added", "memory_id": "" }
memory/get
通过语义相似性搜索检索记忆。
|参数|类型|必填|说明| | - | - | - | - | | query | str |是|自然语言搜索查询| | bucket | str \| null |否|按桶过滤| | top_k | int |no |结果数（默认值： 5) |
退货： { "status": "Memory retrieved", "results": [...] }
memory/delete
按UUID删除特定内存。
|参数|类型|必填|说明| | - | - | - | - | | memory_id | str |yes |要删除的内存的UUID|
退货： { "status": "Memory deleted" }
memory/clear
清空桶里的所有记忆。
|参数|类型|必填|说明| | - | - | - | - | | bucket | str \| null |no |要清除的Bucket（默认为 "default") |
退货： { "status": "Memories cleared" }
memory/list_buckets
列出当前命名空间中的所有bucket。
参数： 无
退货： { "buckets": ["default", "work", ...] }
memory/connect
在两个内存节点之间创建有向边。
|参数|类型|必填|说明| | - | - | - | - | | source_id | str |yes |源节点的UUID| | target_id | str |yes |目标节点的UUID| | relationship_type | str |是|边缘标签（例如。 "related_to", "depends_on") |
退货： { "status": "Memories connected" }
memory/disconnect
删除两个节点之间的一条或所有有向边。
|参数|类型|必填|说明| | - | - | - | - | | source_id | str |yes |源节点的UUID| | target_id | str |yes |目标节点的UUID| | relationship_type | str \| null |否|如果提供，仅删除此边缘标签；否则，移除所有边缘|
退货： { "status": "Memories disconnected" }
memory/traverse
从节点开始遍历知识图。
|参数|类型|必填|说明| | - | - | - | - | | memory_id | str |yes |起始节点的UUID| | relationship_type | str \| null |no |筛选此边标签的遍历| | depth | int |no |跳数（默认值： 1) |
退货： { "status": "Graph traversed", "results": [...] } --每个结果包括 _depth 现场。
REST API
所有REST端点都位于 /v1，要求a Authorization: Bearer header，并接受可选 X-Namespace 标题（默认为 "default").
交互式API文档可在 /docs 当服务器正在运行时。
|方法|路径|描述| | - | - | - | | POST | /v1/memories |添加内存| | POST | /v1/memories/search |语义相似度搜索| | DELETE | /v1/memories/{memory_id} |删除特定内存| | DELETE | /v1/memories?bucket=... |桶里的清晰记忆| | GET | /v1/buckets |列出所有桶| | POST | /v1/memories/connect |在两个节点之间创建有向边| | POST | /v1/memories/disconnect |删除两个节点之间的边| | GET | /v1/memories/{memory_id}/connected |从节点遍历知识图|
例子
所有示例都假设服务器运行在 localhost:4201.更换 $TOKEN 与你的 ARCA_APP_AUTH_KEY.
添加内存
curl -X POST http://localhost:4201/v1/memories \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project" \
-H "Content-Type: application/json" \
-d '{"content": "User prefers dark mode", "bucket": "preferences"}'{
"status": "Memory added",
"memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}搜索记忆
curl -X POST http://localhost:4201/v1/memories/search \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project" \
-H "Content-Type: application/json" \
-d '{"query": "what theme does the user like?", "top_k": 3}'{
"status": "Memory retrieved",
"results": [
{
"memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"content": "User prefers dark mode",
"bucket": "preferences"
}
]
}删除内存
curl -X DELETE http://localhost:4201/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project"{
"status": "Memory deleted"
}清空一个桶
curl -X DELETE "http://localhost:4201/v1/memories?bucket=preferences" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project"{
"status": "Memories cleared"
}列出桶
curl http://localhost:4201/v1/buckets \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project"{
"buckets": ["default", "preferences", "work"]
}其他终点
|方法|路径|描述| | - | - | - | | GET | / |指数——回报 { "message": "OK" } | | GET | /health |健康检查——返回状态、版本、正常运行时间、执行ID| | GET | /docs |交互式OpenAPI文档| | * | /app/mcp |MCP可流式传输http端点|
码头工人
# Build
docker build -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-mcpDocker镜像使用Python 3.14 slim和UV进行依赖管理。
MCP客户端配置
示例 .mcp.json 用于连接MCP客户端（例如Claude Code）：
{
"mcpServers": {
"arca_memory": {
"type": "http",
"url": "http://localhost:4201/app/mcp",
"headers": {
"Authorization": "Bearer ",
"X-namespace": "my_namespace"
}
}
}
}建筑
┌─ /app/mcp → FastMCP Auth → MCP Tool Handler ─┐
Request → FastAPI ├→ Gemini Embedding (Redis cache) → LanceDB
└─ /v1/* → Bearer Auth → REST Router ───────┘
↑
X-Namespace header (multi-tenancy)模块布局
app/
├── __main__.py # Uvicorn entry point
├── main.py # FastAPI app, lifespan, MCP mount, REST router
├── api/
│ ├── deps.py # Shared dependencies (auth, namespace extraction)
│ └── memory.py # REST API router for memory operations
├── context/
│ └── memory.py # MCP tool definitions (add, get, delete, clear, list_buckets)
├── core/
│ ├── config.py # Pydantic BaseSettings with ARCA_ env prefix
│ ├── db.py # LanceDB async connection management
│ ├── cache.py # Redis cache wrapper
│ ├── ai.py # Google Gemini AI client
│ └── log.py # Loguru logging configuration
├── schema/
│ ├── memory.py # REST API request/response models
│ └── status.py # Response models (HealthCheckResponse, IndexResponse)
└── util/
├── embeds.py # Embedding generation with Redis caching
└── memory.py # Core memory CRUD against LanceDB (PyArrow schema)