内容
one-context-mcp
> 一个本地的MCP服务器，为Claude、Cline、Codex和其他AI工具提供相同的项目记忆。
`one-context-mcp` 停止了每次切换AI工具时重复设置说明的过程。它在本地的一个小型SQLite数据库中存储项目上下文，并通过MCP工具暴露出来，所有连接的助手都可以读取和更新。
- PyPI软件包：`one-ctx`
- 主CLI命令：`one-context`
- 替代CLI命令：`ctx`、`one-ctx`
- GitHub仓库：`m4vic/one-context-mcp`
- 默认合并模式：仅本地规则，无模型和API密钥
---
## 为什么存在
每个编码助手都有自己的短期上下文。当你从Claude切换到Cline，从Cline切换到Codex，或者从一个IDE会话切换到另一个IDE会话时，你通常会再次解释相同的项目：
> 这是一个FastAPI后端，PostgreSQL是数据库，`src/main.py`是入口点，我们刚刚更改了身份验证，接下来我们需要速率限制。
`one-context-mcp` 使这种解释持久且可共享。
---
## 架构
```mermaid
graph TD
classDef rootNode fill:#0d1117,stroke:#58a6ff-width:3pxc9d1d-size:16px,font-weight classDef aiNode fill:#161b22,stroke:#3fb950,stroke-width:2px,color:#c9d1d9,font-size:14 classDef bucketNode fill:#21262d,stroke:#949e,stroke-dasharray: 5 5,color:#c9d1d9;
classDef localNode fill:#1f2937,stroke:#f59e0b,stroke-width:2px,color:#f9fafb;
A([one-context MCP Server]):::rootNode
DB[(本地 SQLite:::localNode
C1[Claude 桌面端]:::aiNode
C2[Cline / VS Code]Node
C3[Codex]:::aiNode C4[其他 MCP 客户端]:::aiNode
[(项目范围 WHAT)]:::bucketNode
B2[(已完成 DONE 历史和决策)]:::bucketNode
B3工作 NOW)]:::bucketNode
B4[(重要)]:::bucketNode
B5[(用户消息 NOTESbucketNode
C1 <-->|ctx_get / ctx A
C2 <-->|ctx_get / ctx A
C3 <-->|ctx_get / ctx A
C4 <-->|MCP 工具| A --- DB
DB --- B1
B2
DB3
DB ---
DB --- B5
```
默认情况下，所有内容都是。无需帐户，无需云服务，无需向量数据库，也M API调用。
---
## 安装
### 选项1任何MCP客户端中使用 `uvx`
这是推荐的`uvx` 自动下载并运行PyPI软件包。
```json
{
"mcpServers": {
"one {
"command":x",
"argsfrom", "one-ctx", "one-context","]
}
}
编辑配置后重启M。
### 选项2pip安装
```bash install -U one-one-context stdio
```
以下命令是等效的：bash
one-context stdio
one-ctx stdio stdio
```
###3： 从源码运行git clone https://github.com/m4vic/one-context-mcp.git
cd one-context-mcp
pip install -e .
one-context stdio
```
用于本地开发的MCP配置：
```json
{
"mcpServers": {
"one-context": {
"command": "python",
"args": ["-m", "ctx "stdio"],
" "F:\\combined }
}
}
```
F:\\combinedcontext` 替换为您的本地仓库路径。
---
## MCP客户端设置
### Claude 桌面端
配置文件位置：
- WindowsAPPDATA%\Clclaude_desktop_config.json`
- macOS: `/Application Support/Claude_desktop_config.json`
```json
{
cpServers": {
"one-context": {
": "uvx",
"args": ["--fromone-ctx", "one-context", "stdio"]
}
}
```
完全aude桌面端并重新### Cline / VS打开Cline MCP设置：
```json
"mcpServers": "one-context": {
command": "uvx",
args": ["--from", "one-ctx",", "stdio"],
"disabled": false,
Approve": []
}
}
```
更改文件加载VS Code。
###
将以下内容添加到/.codex/config.toml
```toml
.one-context]
commanduvx"
args =", "one- "one-context", "```
更改MCP配置后启动新的Codex会话。
---
## 首次使用
使用稳定的项目名称。例如，在每次RT项目时都使用 `asrt`。
询问您的
```text
使用one-context。将项目asrt链接:\ASRT，然后。
```
在工作会话：
```text
asrt更新one-context包括我们更改的内容、已完成的内容、接下来要以及重要文件。
```
添加直接用户笔记：
为项目asrt添加一个one-context笔记：保持SafetyDiff作为MVP后的优先级。
## 存储内容
| 存储 目的 | 示例--------|---------|---------|
WHAT` | 项目身份、堆栈、架构、约束 | 带有PostgreSQL和async的FastAPI后端 |
| `DONE` |的工作、决策、已 | JWT身份验证已ID选择UUID |
|` | 当前任务和下一步 | 正在处理速率限制中间件 |
| `MAP` | 重要文件及其作用 | `src/auth.py` - 身份验证中间件 |
| `NOTES` | 用户编写的项目消息 | 记住在MVP后保持ASRT上下文严格 |
目被规范化和去重。当项目链接到 `repo_path` 时，文件跟踪仅限于该仓库，以防止不同项目的上下文混淆。
---
## 工具流程
```mermaid
sequenceDiagram
participant User
participant Assistant
participant MCP as one-context MCP
participant DB as 本地 SQLite
User->>Assistant: 加载项目asrt的上下文
AssistantMCP: ctx="asrt")
>DB: 读取WHAT/DONE/NOW/MAP/NOTES
DB-->>MCP: 项目快照
MCP-->>Assistant: 上下文 + git摘要
User->>Assistant: 我们更改了身份验证和测试
Assistant->>MCP: ctx_update(project="asrt", session_summary="...")
MCP->>DB: 合并并保存项目上下文
DB--CP: 更新的
MCP-->>Assistant: 已保存
```
工具
| 工具 | 目的 |
||
| `ctx_get(project)` | 加载WHAT、DONE、MAP、仓库路径和git信息 |
|_strict_get(project, repo_path)` | 仅当路径与链接的项目匹配时加载上下文 |
ctx_update(project, session_summary, tool_name)` | 将合并到项目上下文中 |
| `ctx_map(project, files, replace)` | 手动注册重要文件 |
|_note(project, message, author, merge)` | 为存储用户编写的笔记 `ctx_history(project)` | 显示一个项目的最近更新和用户笔记 |
|_link(project, repo_path)` | 创建/链接项目到根目录以实现严格的文件范围 |
| `(query)` | 搜索所有项目、更新历史和用户笔记 |
| `ctx_reset(project)` | 清除一个项目的上下文 |
| `ctx_list()` | 列出跟踪的项目 |
---
## CLI 参考
ctx status [project # 查看当前上下文或列出项目
ctx init> --path . # 创建/链接项目到仓库路径
ctx search <query> # 跨项目和
ctx reset < # 清除
ctx delete <project> # 永久删除项目
ctx list # 列项目
ctx serve --7337 # 启动HTTP/SSE服务器
ctx stdio # 启动stdio MCP服务器
```
HTTP/SSE模式：
```bash
ctx serve --host 127.0.0.1 --port 7337
```
然后将MCP客户端连接到：
```text
127.0.0.17/sse
```
---
## 合并模式
本地合并是默认的，从不调用模型。
| 模式 | 启用 | 使用模型/API？ |
|------|--------|-----------------|
| 本地 | 默认CTX_MERGE_MODE=local` | 否 | `CTXGE_MODE=auto` | 尝试配置的提供程序 |
| | `CTX_M_MODE=ollama` 和 `CTX_OLLAMA_MODEL=llama3.2` | 本地| Anthropic | `CTX_MERGEanthropic` 和 `ANTHROPIC=...` | 是 OpenAI兼容 |X_MERGE_MODE=openai` 和 `OPENAI_API_KEY=...` | 是 |
推荐的默认设置```bash
CTXGE_MODE=local
```
正常使用时，您不需要任何API密钥。
---
## 验证安装
```bash
uvx --from one-ctx --help
uvfrom one-ctx one-context stdio
```
对于检出：
```python -m compileall ctx
python -m build
python -m twine check dist/*
```
---
##
安装最新的PyPI发布版本：
```bash install -U one
```
安装特定版本：
```bash
pip install one-ctx==0.2.1
```
直接从GitHub安装：
```bash
pip install git+https://github.com/m4vic/one-context-mcp.git
```
从GitHub Releases下载源码：
```text
https://github.com/m4vic/one-context-mcp/releases
```
---
## 故障排除
### MCP客户端未显示工具
1. 确认配置中有一个顶级 `mcpServers` 对象。
2. 使用上述确切的 `uvx` 命令。
3. 完全重启Claude、Cline、Codex或MCP客户端。
4. 手动测试命令：
```bashx --from one--context --help
地源码有效，但PyPI无效
使用：
```bash
pip install one-ctx
```
然后重启MCP客户端。MCP客户端通常会缓存工具界面，直到会话刷新。
### 项目上下文混淆
使用 `ctx_link(project, repo_path)` 每个项目一次，并在每个工具中使用相同的项目名称。
示例：
```text
使用ctx_link为项目asrt设置仓库路径F:\ASRT。
```
对于更严格的读取，请要求助手调用 `ctx_strict_get repo_path)`。
与链接的项目，它将拒绝返回上下文 许可证
MIT
---
构建用于终工具之间的上下文失忆。
