内容
# 上下文工具
**一次性存储 AI 上下文，任意模型调用。** 上下文工具是一个小型
[MCP](https://modelcontextprotocol.io) 服务器，为 Claude、Cursor 和其他
MCP 客户端提供五种工具，用于保存和调用上下文 — 这样您的笔记、决策和工作记忆就可以在不同模型和会话之间移植。
它完全在您的机器上运行，并将所有内容存储在**您拥有的存储空间**中：
默认为本地 Markdown 文件，或您自己的 **Dropbox** 或 **Google Drive**。没有
Contextly 账户、服务器或云端 — 无需注册，无需付费。
> **许可证：** 在 **PolyForm Noncommercial 1.0.0** 下源代码可用。免费用于
> 个人和非商业用途。商业/企业使用需要单独的许可证 — 请参阅 [许可证](#license)。
## 工具
| 工具 | 功能 |
|---|---|
| `save_context` | 保存（或覆盖）命名上下文 |
| `append_context` | 添加到现有上下文 |
| `list_contexts` | 列出所有内容为表格（创建时间、更新时间、模型、设备、大小） |
| `recall_context` | 将存储的上下文拉回对话 |
| `search_context` | 跨所有上下文的关键字搜索，附带片段 |
## 快速开始（本地文件 — 零配置）
需要 **Node ≥ 18**。
```bash
git clone https://github.com/mehdimerai/contextly.git && cd contextly
npm install
npm test # 对本地文件存储进行烟雾测试
```
上下文以 Markdown 格式存储在 `~/.contextly/` 中。现在，将 MCP 客户端指向它。
**Claude Desktop / Claude Code** — 添加到您的 MCP 配置
（`claude_desktop_config.json` 或 `claude mcp add`）：
```json
{
"mcpServers": {
"contextly": {
"command": "node",
"args": ["/absolute/path/to/contextly/bin/contextly.js"]
}
}
}
```
**Cursor** — 在 `~/.cursor/mcp.json` 下的 `mcpServers` 中采用相同格式。
重启客户端；您将看到这五个工具。就这样 — 您正在使用本地文件。
## 使用您自己的存储空间
相同的工具，相同的 Markdown 格式 — 只需存储在您的云端。运行一次连接器，然后重启您的 MCP 客户端。
### Dropbox
1. 在 <https://www.dropbox.com/developers/apps> 上创建一个 Dropbox 应用 → **限定访问** → **应用文件夹** （这将 Contextly 限制在其自己的 `Apps/<your-app>/` 文件夹中 — 它永远无法看到您的 Dropbox 其他部分）。
2. 在应用的 **权限** 标签页上，启用 `files.content.read` 和 `files.content.write`。
3. 在 **设置** 标签页上，添加 `http://localhost:53682` 作为 **OAuth 2 重定向 URI**，并复制 **应用密钥**。
4. 连接：
```bash
node bin/contextly-auth.js dropbox # 粘贴应用密钥
```
您的浏览器打开，您批准后，一个刷新令牌保存到 `~/.contextly/config.json` 中。
### Google Drive
1. 在 [Google Cloud Console](https://console.cloud.google.com/) 中，创建一个项目并启用 **Google Drive API**。
2. 配置 OAuth 同意屏幕（外部即可；添加自己作为测试用户），然后创建一个 **OAuth 客户端 ID**，类型为 **桌面应用**。复制 **客户端 ID** 和 **客户端密钥**。
3. 连接：
```bash
node bin/contextly-auth.js gdrive # 粘贴客户端 ID + 密钥
```
在浏览器中批准。Contextly 使用狭窄的 `drive.file` 范围，因此它只能看到它创建的文件 — 所有内容都存放在一个 `Contextly` 文件夹中。
连接器将您的选择写入 `~/.contextly/config.json`；从那时起，服务器使用该后端。要切换回本地文件，请将 `store` 设置为 `"file"` 在该文件中（或删除它）。
## 工作原理
```
┌─ stores/file.js (~/.contextly Markdown 文件 — 默认)
bin/contextly.js ──┐ │
（stdio 服务器） ├──┼─ stores/dropbox.js （您的 Dropbox 应用文件夹）
lib.js （5 种工具） ──┘ │
存储接口 ───┴─ stores/gdrive.js （您的 Google Drive “Contextly” 文件夹）
列表 · 获取 · 保存 · 追加 · 搜索
config.js 选择后端（CONTEXTLY_STORE → config.json → 文件）
bin/contextly-auth.js 一次性 OAuth → 刷新令牌在 ~/.contextly/config.json 中
```
每个后端都读取和写入 **相同的 Markdown-with-frontmatter 格式** （`stores/format.js`），因此您的库是可移植的：在本地保存的上下文与在 Dropbox 或 Drive 中保存的上下文在字节上是相同的。您甚至可以将您的 `~/.contextly` 文件夹放入同步的 Dropbox/Drive 桌面文件夹中，并继续使用普通的 `file` 存储。
## 隐私
您的上下文永远不会触及 Contextly 运行的服务器 — 没有这样的服务器。数据仅存在于您的磁盘或您自己的云账户中，受到您自己的 OAuth 应用和 API 配额的限制。凭证位于 `~/.contextly/config.json` 中（仅限所有者可读）。
## 配置参考
存储通常由 `contextly-auth` 设置。所有内容都可以通过环境变量覆盖 — 请参阅 [`.env.example`](.env.example) （`CONTEXTLY_STORE`、`CONTEXTLY_DIR` 和用于 CI 的 Dropbox/Google 令牌变量）。
## 贡献
欢迎贡献 — 尤其是新的存储后端。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解布局、存储接口以及如何添加一个。
## 许可证
Contextly 在 **PolyForm Noncommercial License 1.0.0** 下 **源代码可用** — 不是 OSI “开源”许可证。
- **免费** 用于个人使用、学习、爱好项目、研究和非营利组织/学校/政府。
- **商业或企业使用需要单独的许可证。** 请联系 **mehdi.merai@gmail.com**。
