内容
# 克劳德-大西洋-MCP
自主托管的MCP服务器，为克劳德提供持久记忆，涵盖对话中的**实体**、**观察**、**历史**和基于时间 **提醒**，采用轻量级的Node/SQLite后端，您可以自行运行。
将克劳德指向它作为MCP连接器，它就能记住您从一个对话到下一个对话的内容：正在进行的项目、决策及其理由、关于您和您的设置的事实，以及在未来某个日期重新浮现的事情。
## 为什么
克劳德在对话结束时忘记一切。大西洋是一个小巧、稳定、持久的记忆层，您从头到尾都拥有——无需第三方服务，无需供应商锁定。它是一个单一的Node进程，由一个SQLite文件支持。可以在家用服务器、VPS或笔记本电脑上运行。
## 数据模型
| 概念 | 描述 |
|---------|-----------|
| **实体** | 您希望克劳德跟踪的主题或项目（例如“家庭网络”，“Q3规划”）。具有名称和一行摘要。 |
| **观察** | 附加到实体的单个事实（“于2026-06-01切换路由器到6E频段”）。记忆的原子单位。 |
| **历史事件** | 已记录到时间轴中以供以后回忆的重大事件。 |
| **提醒** | 具有`trigger_date`的笔记。一旦日期到来，它将在对话开始时自动浮现，直到被取消。 |
| **部分** | 顶级命名空间——两个固定值之一，`工作`和`个人`。每个工具调用都采用`section`参数，因此两个上下文永远不会相互影响。 |
## 工具
服务器暴露了13种MCP工具：
**阅读**
- `get_landscape` — 指定部分的所有内容：所有具有观察的实体，以及任何到期的提醒。在对话开始时调用以获取信息。
- `search` — 跨实体、观察和历史的关键词搜索。
- `get_entity` — 按名称获取一个实体及其观察。
- `get_history` — 已记录事件的时间轴。
**写入**
- `upsert_entity` — 创建或更新实体的名称/摘要。
- `add_observation` — 将事实附加到实体。
- `remove_observation` — 删除过时或已完成的事实。
- `remove_entity` — 删除实体及其观察。
- `log_event` — 将重大事件记录到历史中。
**提醒**
- `create_reminder` — 具有`trigger_date`（和可选实体链接）的笔记。
- `list_reminders` — 所有提醒，或仅当前到期的提醒。
- `dismiss_reminder` — 将提醒标记为已处理（它将停止浮现）。
- `remove_reminder` — 彻底删除提醒。
## 要求
- 带有内置SQLite支持的Node.js（`node:sqlite`）——Node 22+。
- Docker（可选，推荐用于部署）。
**没有原生依赖**——存储是内置的`node:sqlite`模块，因此无需编译。
## 快速入门（Docker）
```bash
git clone https://github.com/dcazman/Claude-Atlas-MCP.git
cd Claude-Atlas-MCP
cp .env.example .env # 设置令牌
docker compose up -d --build
```
服务器监听 **7784** 端口。数据通过挂载的卷持久存储到 `./data`（单个SQLite文件）。
## 快速入门（裸Node）
需要 Node 22+（用于内置 `node:sqlite`）。
```bash
npm install
cp .env.example .env # 设置令牌
npm start # 或：node src/server.js
```
## 连接克劳德
大西洋通过 `POST /atlas-mcp` 上的流式HTTP使用MCP。将服务器的URL和令牌添加为连接器：
```
https://<您的主机>/atlas-mcp?token=<您的秘密>
```
令牌是 `ATLAS_TOKEN` `caller:secret` 对的 **秘密** 部分（见下文）。您也可以将其作为 `X-Atlas-Token` 头或 `Bearer` 令牌传递，而不是查询字符串。
URL中没有 `section` —— 每个工具都采用 `section` 参数（`工作` 或 `个人`），而给定对话应默认为哪一个最好在您的克劳德项目自定义指令中设置（例如 *“您的Atlas部分是个人”*）。`GET /health` 端点可用于活动检查。
在实际使用中，您希望它位于HTTPS后面——一个反向代理或隧道（Cloudflare Tunnel、Tailscale、nginx等）在容器前面。令牌是唯一的身份验证，**请勿在没有TLS的情况下公开暴露端口**。
连接后，一个良好的习惯是让克劳德在每次对话开始时调用 `get_landscape`，并在更改时保持条目更新（`upsert_entity` / `add_observation` / `log_event` / `remove_observation`）——您可以将该内容编码到连接器的指令字段或项目的自定义指令中。
## 安全
大西洋的内置身份验证是一个单一的共享令牌——在私有网络或隧道后面很好，但如果您将其暴露在互联网上，则很薄弱。对于实际的访问控制，请在前面放置一个专用的身份验证网关，而不是加强此服务器本身。
[**mcp-auth-proxy**](https://github.com/sigbit/mcp-auth-proxy) 是一个适用于MCP服务器的即插即用OAuth 2.1 / OIDC网关——无需对大西洋进行代码更改：
- 针对您自己的IdP（Google、GitHub、Okta、Auth0、Azure AD、Keycloak、任何OIDC提供商）进行身份验证，并带有可选密码。
- 通过精确匹配或通配符（例如`*@yourcompany.com`）授权用户。
- 终止TLS并将HTTP传输作为原样代理，通过克劳德、克劳德代码、ChatGPT、Copilot和Cursor进行验证。
大致上，您需要将其指向大西洋的HTTP端点：
```bash
./mcp-auth-proxy \
--external-url https://<您的域名> \
--tls-accept-tos \
-- http://localhost:7784/atlas-mcp
```
参见其 [文档](https://github.com/sigbit/mcp-auth-proxy) 以获取IdP设置和配置。（不隶属于——只是自托管MCP服务器（如本服务器）的干净适配。）
## 配置
通过 `.env` 设置（参见 `.env.example`）：
| 变量 | 目的 |
|----------|---------|
| `ATLAS_TOKEN` | **必填。** 一个或多个 `caller:secret` 对，以逗号分隔（例如 `claude:changeme`）。如果请求的令牌与任何一个秘密匹配，则请求将被授权。使用 `node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"` 生成一个。 |
| `PORT` | 监听端口（默认为 `7784`）。 |
| `ATLAS_DB_PATH` | SQLite文件的路径（默认为 `src/` 相对于 `../data/atlas.db`；Docker镜像使用 `/app/data/atlas.db`）。 |
## 安全
参见 [SECURITY.md](SECURITY.md) 获取威胁模型、部署强化说明以及如何报告漏洞。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
