Content
# Agent Context MCP Server
A portable, tool-agnostic memory and code structure graph for agentic AI coding tools (OpenCode, Antigravity, Claude Code, etc.).
## 🧠 The Problem
Agentic AI tools typically keep their memory locked inside a single session. When you run out of context tokens or switch to a different AI tool, you lose:
- What you were currently working on (tasks, pending steps).
- Why past technical decisions were made.
- The structural architecture of the codebase.
## 🚀 The Solution
The **Agent Context Server** is an MCP (Model Context Protocol) server that tracks working context and code structure in a lightweight, local SQLite database (`.agentctx/context.db`). It provides a single, portable memory that follows the *project* rather than the *tool*.
You can start a task in one AI tool, hit a context limit, open a completely different AI tool, and resume exactly where you left off.
## ✨ Features
* **Working Context Engine:** Tracks active tasks, decisions, progress logs, and open questions across sessions.
* **Code Structure Graph:** Uses `tree-sitter` to parse and map `Python`, `JavaScript`, and `TypeScript` files, extracting classes, functions, and methods without sending your code to external APIs.
* **Incremental Indexing:** Smart content-hashing ensures only modified files are re-indexed.
* **Project Export:** Built-in tools to instantly zip and backup your agent's memory state.
* **Fully Local & Private:** No LLM calls inside the server; all state is kept entirely locally via SQLite.
## 🛠️ Prerequisites
* [Python 3.10+](https://www.python.org/)
* [uv](https://docs.astral.sh/uv/) (Fast Python package and project manager)
## 📦 Installation
1. Clone this repository to your machine:
```bash
git clone (replace with your own repo URL once you push this to GitHub)
cd agent-context-mcp-server
```
2. The project uses `uv` for dependency management. The required packages (`mcp`, `tree-sitter`, `tree-sitter-python`, `tree-sitter-javascript`, `tree-sitter-typescript`) will be automatically managed when you run the server.
## ⚙️ MCP Configuration
To use this server with your preferred agentic AI tool (like Google Antigravity, OpenCode, or Claude Code), add the following to your MCP configuration settings:
```json
{
"mcpServers": {
"agent-context-server": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/agent-context-mcp-server",
"run",
"server.py"
]
}
}
}
```
> **Note:** Replace `/absolute/path/to/agent-context-mcp-server` with the actual path where you cloned this repository. The server will dynamically create the `.agentctx/` directory in whatever project folder your AI agent is currently working in.
---
## 🧰 Available Tools
Once connected, your AI agent will have access to the following tools:
### Working Context
* **`start_task(title)`**: Creates a new working context task.
* **`log_progress(task_id, entry, entry_type)`**: Appends a progress log (`step_done`, `error_hit`, `next_step`, `note`).
* **`log_decision(task_id, decision, reason, symbol_ref)`**: Logs technical decisions and the reasoning behind them.
* **`add_question(question)` / `resolve_question(question_id)`**: Manages open questions.
* **`resume(task_id?)`**: Retrieves the full state of the active task to seamlessly pick up work.
* **`list_tasks(status?)`**: Lists active, done, blocked, or abandoned tasks.
### Structure Graph
* **`graph.index(path, languages?)`**: Parses a file (`.py`, `.js`, `.ts`, `.jsx`, `.tsx`) and extracts structural symbols.
* **`graph.get_symbol(name)`**: Retrieves a specific symbol's file path and line numbers.
* **`graph.trace_calls(symbol_name, direction)`**: Traces inbound or outbound function calls within the same file.
* **`graph.get_architecture()`**: Returns a high-level overview of the parsed codebase, including files, symbol counts, and root entry points.
### Lifecycle
* **`project.export()`**: Zips the entire `.agentctx/` directory for safe backup and sharing.
---
## 📄 License
* **MIT License**
