mcp-working-context-optimizer

An MCP (Model Context Protocol) 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:

Context Bloat & OOM: Exceeding the token limit or causing Out-Of-Memory errors on local LLM servers due to massive KV cache expansion.
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 is recommended.

# 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):

{
  "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

The agent reads the user prompt and calls set_core_objective and update_current_task.
The agent executes a tool (e.g., reading a file, running a shell command) and calls log_action to store the result.
The agent reads working-context://state to decide the next step.
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 file for details.

mcp-working-context-optimizer