# mcp-working-context-optimizer

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server designed to optimize the working context of AI agents. It prevents context bloat and the "Lost in the Middle" phenomenon by distilling action histories into concise summaries while maintaining a clear core objective.

## 🌟 The Problem it Solves

Current autonomous AI agents (like AutoGPT, Cline, or custom smolagents) tend to append all tool execution logs and error messages directly into their context window. 
This naive approach quickly leads to:

1. **Context Bloat & OOM**: Exceeding the token limit or causing Out-Of-Memory errors on local LLM servers due to massive KV cache expansion.
2. **Lost in the Middle**: The agent gets distracted by recent, verbose error logs and forgets the original, overarching objective.

## 💡 The Solution: Dual-Track Memory

This MCP server acts as an external "Working Memory" for the agent. It enforces a structured context containing:

- **Current Task**: The immediate next step or user instruction.
- **Core Objective**: The ultimate goal (never truncated, always focused).
- **Summarized History**: A compressed version of past events.
- **Recent Actions**: Raw logs of the last few steps (auto-truncated to prevent bloat).

When the recent actions limit is reached, the server proactively prompts the agent to summarize the history and clear the logs, keeping the context perfectly optimized.

## 🚀 Installation

Ensure you have Python 3.10 or higher. Using [`uv`](https://github.com/astral-sh/uv) is recommended.

```bash
# Clone the repository
git clone [https://github.com/your-username/mcp-working-context-optimizer.git](https://github.com/your-username/mcp-working-context-optimizer.git)
cd mcp-working-context-optimizer

# Install via uv (or pip)
uv pip install -e .
```

## ⚙️ Usage / Configuration

To use this with an MCP client (like Claude Desktop, Cursor, or Cline), add the following to your MCP settings file (e.g., `mcp_config.json` or `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "working-context-optimizer": {
      "command": "mcp-working-context-optimizer"
    }
  }
}
```

*(Note: If using `uv`, you might need to specify the absolute path to the executable or run via `uvx` depending on your environment).*

## 🛠️ Provided Tools & Resources

### Resources

- `working-context://state`: Returns the optimized Markdown representation of the current working context. The agent should read this when losing track of the context or starting a new task.

### Tools

- `set_core_objective(objective: str)`: Sets the primary goal and constraints.
- `update_current_task(task: str)`: Sets the immediate, short-term focus.
- `log_action(action: str, result: str)`: Logs a tool action and its result. Extremely long results are automatically truncated to 2000 characters.
- `compress_history(new_summary: str)`: Used by the agent to update the summarized history and clear the recent action logs, freeing up context space.

## 🤖 Agent Workflow Example

1. The agent reads the user prompt and calls `set_core_objective` and `update_current_task`.
2. The agent executes a tool (e.g., reading a file, running a shell command) and calls `log_action` to store the result.
3. The agent reads `working-context://state` to decide the next step.
4. If `working-context://state` returns a warning that the recent actions limit is reached, the agent calls `compress_history` to summarize the past actions, thereby keeping its own context window clean.

## 📄 License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.