MCP 方舟
一种模型上下文协议(MCP)服务器,通过向量嵌入提供语义记忆存储和检索。使用FastAPI+FastMCP构建,使用LanceDB进行矢量存储,使用Google Gemini进行嵌入生成。
特性
- 语义搜索 --使用由向量相似性搜索支持的自然语言查询来存储和检索记忆
- 双重访问 -用于AI代理的MCP工具+用于编程集成的REST API
- 多租户隔离 --命名空间范围的操作通过
X-NamespaceHTTP标头 - Bucket组织 --将内存分组到逻辑桶中进行结构化存储
- 嵌入缓存 -用于生成嵌入的Redis-supported缓存,以最大限度地减少API调用
- 承载令牌认证 --用于安全访问的恒定时间令牌验证
先决条件
- Python 3.14+
- 紫外线 包管理器
- 瑞迪斯
- Google API密钥(用于Gemini嵌入)
快速开始```bash
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`.
#### 添加内存```bash
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"}'
``````json
{
"status": "Memory added",
"memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
搜索记忆```bash
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}'
``````json
{
"status": "Memory retrieved",
"results": [
{
"memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"content": "User prefers dark mode",
"bucket": "preferences"
}
]
}
#### 删除内存```bash
curl -X DELETE http://localhost:4201/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project"
``````json
{
"status": "Memory deleted"
}
清空一个桶```bash
curl -X DELETE "http://localhost:4201/v1/memories?bucket=preferences" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project"
``````json
{
"status": "Memories cleared"
}
#### 列出桶```bash
curl http://localhost:4201/v1/buckets \
-H "Authorization: Bearer $TOKEN" \
-H "X-Namespace: my_project"
``````json
{
"buckets": ["default", "preferences", "work"]
}
其他终点
| 方法 | 路径 | 描述 |
|---|---|---|
GET |
/ |
指数——回报 { "message": "OK" } |
GET |
/health |
健康检查——返回状态、版本、正常运行时间、执行ID |
GET |
/docs |
交互式OpenAPI文档 |
* |
/app/mcp |
MCP可流式传输http端点 |
码头工人```bash
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-mcp
Docker镜像使用Python 3.14 slim和UV进行依赖管理。
## MCP客户端配置
示例 `.mcp.json` 用于连接MCP客户端(例如Claude Code):```json
{
"mcpServers": {
"arca_memory": {
"type": "http",
"url": "http://localhost:4201/app/mcp",
"headers": {
"Authorization": "Bearer ",
"X-namespace": "my_namespace"
}
}
}
}
建筑```text
┌─ /app/mcp → FastMCP Auth → MCP Tool Handler ─┐
Request → FastAPI ├→ Gemini Embedding (Redis cache) → LanceDB
└─ /v1/* → Bearer Auth → REST Router ───────┘
↑
X-Namespace header (multi-tenancy)
### 模块布局```text
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)
技术栈
- 快速API --ASGI web框架
- FastMCP --模型上下文协议服务器框架
- 兰斯数据库 --无服务器矢量数据库
- 谷歌双子座 --嵌入生成(
gemini-embedding-001) - 瑞迪斯 --嵌入缓存层
- 派丹蒂克 --设置和数据验证
- 紫外线 --Python包管理器
- 洛古鲁 --日志记录
