one-ctx 0.2.1

Local MCP server that shares project context across Claude, Cline, Codex, and other AI tools.

one-context-mcp

One local MCP server that gives Claude, Cline, Codex, and other AI tools the same project memory.

one-context-mcp stops the repeated setup explanation every time you switch AI tools. It stores project context locally in a small SQLite database and exposes it through MCP tools that every connected assistant can read and update.

• PyPI package: one-ctx
• Main CLI command: one-context
• Alternate CLI commands: ctx, one-ctx
• GitHub repo: m4vic/one-context-mcp
• Default merge mode: local rules only, no model and no API key

---

Why It Exists

Every coding assistant has its own short-term context. When you move from Claude to Cline, from Cline to Codex, or from one IDE session to another, you usually explain the same project again:

This is a FastAPI backend, PostgreSQL is the database, src/main.py is the entry point, we just changed auth, and next we need rate limiting.

one-context-mcp makes that explanation persistent and shared.

---

Architecture

graph TD
    classDef rootNode fill:#0d1117,stroke:#58a6ff,stroke-width:3px,color:#c9d1d9,font-size:16px,font-weight:bold;
    classDef aiNode fill:#161b22,stroke:#3fb950,stroke-width:2px,color:#c9d1d9,font-size:14px;
    classDef bucketNode fill:#21262d,stroke:#8b949e,stroke-dasharray: 5 5,color:#c9d1d9;
    classDef localNode fill:#1f2937,stroke:#f59e0b,stroke-width:2px,color:#f9fafb;

    A([one-context MCP Server]):::rootNode
    DB[(Local SQLite DB)]:::localNode

    C1[Claude Desktop]:::aiNode
    C2[Cline / VS Code]:::aiNode
    C3[Codex]:::aiNode
    C4[Other MCP Clients]:::aiNode

    B1[(WHAT\nProject scope)]:::bucketNode
    B2[(DONE\nHistory and decisions)]:::bucketNode
    B3[(NOW\nCurrent work)]:::bucketNode
    B4[(MAP\nImportant files)]:::bucketNode
    B5[(NOTES\nUser messages)]:::bucketNode

    C1 <-->|ctx_get / ctx_update| A
    C2 <-->|ctx_get / ctx_update| A
    C3 <-->|ctx_get / ctx_update| A
    C4 <-->|MCP tools| A

    A --- DB
    DB --- B1
    DB --- B2
    DB --- B3
    DB --- B4
    DB --- B5

Everything is local by default. No account, no cloud service, no vector database, and no LLM API call is required.

---

Install

Option 1: Use uvx in any MCP client

This is the recommended setup. uvx downloads and runs the PyPI package automatically.

{
  "mcpServers": {
    "one-context": {
      "command": "uvx",
      "args": ["--from", "one-ctx", "one-context", "stdio"]
    }
  }
}

Restart the MCP client after editing the config.

Option 2: Install with pip

pip install -U one-ctx
one-context stdio

These commands are equivalent:

one-context stdio
one-ctx stdio
ctx stdio

Option 3: Run from source

git clone https://github.com/m4vic/one-context-mcp.git
cd one-context-mcp
pip install -e .
one-context stdio

For local development MCP config:

{
  "mcpServers": {
    "one-context": {
      "command": "python",
      "args": ["-m", "ctx.cli", "stdio"],
      "cwd": "F:\\combinedcontext"
    }
  }
}

Replace F:\\combinedcontext with your local repo path.

---

MCP Client Setup

Claude Desktop

Config file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "one-context": {
      "command": "uvx",
      "args": ["--from", "one-ctx", "one-context", "stdio"]
    }
  }
}

Fully quit Claude Desktop and reopen it.

Cline / VS Code

Open Cline MCP settings and add:

{
  "mcpServers": {
    "one-context": {
      "command": "uvx",
      "args": ["--from", "one-ctx", "one-context", "stdio"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Reload VS Code after changing the file.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.one-context]
command = "uvx"
args = ["--from", "one-ctx", "one-context", "stdio"]

Start a fresh Codex session after changing MCP config.

---

First Use

Use a stable project name. For example, use asrt every time you refer to the ASRT project.

Ask your assistant:

Use one-context. Link project asrt to F:\ASRT, then load context.

At the end of a work session:

Update one-context for project asrt with what we changed, what is done, what is next, and important files.

To add a direct user note:

Add a one-context note for project asrt: Keep SafetyDiff as priority after MVP.

---

What Gets Stored

Bucket	Purpose	Example
WHAT	Project identity, stack, architecture, constraints	FastAPI backend with PostgreSQL and async SQLAlchemy
DONE	Completed work, decisions, solved issues	JWT auth implemented, UUID user IDs chosen
NOW	Current task and next steps	Working on rate limiting middleware
MAP	Important files and what they do	src/auth.py - auth middleware
NOTES	User-authored project messages	Remember to keep ASRT context strict

MAP entries are normalized and deduplicated. When a project is linked to a repo_path, file tracking is scoped to that repo so context from different projects does not get mixed.

---

Tool Flow

sequenceDiagram
    participant User
    participant Assistant
    participant MCP as one-context MCP
    participant DB as Local SQLite

    User->>Assistant: Load context for project asrt
    Assistant->>MCP: ctx_get(project="asrt")
    MCP->>DB: Read WHAT/DONE/NOW/MAP/NOTES
    DB-->>MCP: Project snapshot
    MCP-->>Assistant: Context + git summary

    User->>Assistant: We changed auth and tests
    Assistant->>MCP: ctx_update(project="asrt", session_summary="...")
    MCP->>DB: Merge and save project context
    DB-->>MCP: Updated snapshot
    MCP-->>Assistant: Saved

---

MCP Tools

Tool	Purpose
ctx_get(project)	Load WHAT, DONE, NOW, MAP, repo path, and git info
ctx_strict_get(project, repo_path)	Load context only when the current workspace path matches the linked project
ctx_update(project, session_summary, tool_name)	Merge a session summary into project context
ctx_map(project, files, replace)	Register important files manually
ctx_note(project, message, author, merge)	Store a user-authored note for one project
ctx_history(project, limit)	Show recent updates and user notes for one project
ctx_link(project, repo_path)	Create/link a project to a workspace root for strict file scoping
ctx_search(query)	Search all projects, update history, and user notes
ctx_reset(project)	Clear one project's context
ctx_list()	List tracked projects

---

CLI Reference

ctx status [project]          # View current context or list projects
ctx init <project> --path .   # Create/link project to repo path
ctx search <query>            # Search across projects and history
ctx reset <project>           # Clear a project's context
ctx delete <project>          # Permanently delete a project
ctx list                      # List all projects
ctx serve --port 7337         # Start HTTP/SSE server
ctx stdio                     # Start stdio MCP server

HTTP/SSE mode:

ctx serve --host 127.0.0.1 --port 7337

Then connect MCP clients to:

http://127.0.0.1:7337/sse

---

Merge Modes

Local merge is the default and never calls a model.

Mode	Enable	Uses model/API?
Local	Default or CTX_MERGE_MODE=local	No
Auto	CTX_MERGE_MODE=auto	Tries configured providers
Ollama	CTX_MERGE_MODE=ollama and CTX_OLLAMA_MODEL=llama3.2	Local model
Anthropic	CTX_MERGE_MODE=anthropic and ANTHROPIC_API_KEY=...	Yes
OpenAI compatible	CTX_MERGE_MODE=openai and OPENAI_API_KEY=...	Yes

Recommended default:

CTX_MERGE_MODE=local

You do not need any API key for normal use.

---

Verify Installation

uvx --from one-ctx one-context --help
uvx --from one-ctx one-context stdio

For a local source checkout:

python -m compileall ctx
python -m build
python -m twine check dist/*

---

Release Downloads

Install the latest PyPI release:

pip install -U one-ctx

Install a specific version:

pip install one-ctx==0.2.1

Install directly from GitHub:

pip install git+https://github.com/m4vic/one-context-mcp.git

Download source from GitHub Releases:

https://github.com/m4vic/one-context-mcp/releases

---

Troubleshooting

MCP client does not show tools

1. Confirm the config has a top-level mcpServers object.
2. Use the exact uvx command shown above.
3. Fully restart Claude, Cline, Codex, or the MCP client.
4. Test the command manually:

uvx --from one-ctx one-context --help

Local source works but PyPI does not

Use:

pip install -U one-ctx

Then restart the MCP client. MCP clients often cache tool surfaces until a fresh session.

Project context is mixed

Use ctx_link(project, repo_path) once per project and keep the same project name in every tool.

Example:

Use ctx_link for project asrt with repo_path F:\ASRT.

For stricter reads, ask the assistant to call ctx_strict_get(project, repo_path). It refuses to return context if the folder does not match the linked project.

---

License

MIT

---

Built to end context amnesia across AI tools.