Agent State MCP Server

A Model Context Protocol (MCP) server built with FastMCP that provides agent state and log management tools for long-lived agents that may be interrupted and resumed.

Features

State management tools for tracking agent progress
Log management tools for maintaining append-only event history
Built with FastMCP for easy MCP server development
Type-safe Python code with proper type hints

Setup

Prerequisites

Python 3.14+
uv package manager

Installation

Install dependencies:
```
uv sync
```

Activate the virtual environment (if needed):

source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate  # On Windows

Running the Server

Run the MCP server:

uv run python main.py

Setting up MCP in Claude Desktop

Open Claude Desktop settings:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the MCP server configuration:

{
  "mcpServers": {
    "agent-state": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "[install directory]/agent-state/main.py"
      ]
    }
  }
}

Important: Update the paths in the configuration:
- Replace [install directory]/agent-state with the absolute path to this project on your system
- Ensure the path uses forward slashes on all platforms
Restart Claude Desktop for the changes to take effect.

Setting up MCP in Cursor (OpenCode)

Open Cursor settings:
- Press Cmd+, (macOS) or Ctrl+, (Windows/Linux) to open settings
- Or go to File > Preferences > Settings
Search for "MCP" in the settings

Add the MCP server configuration in your settings JSON:

{
  "mcp.servers": {
    "agent-state": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "[install directory]/agent-state/main.py"
      ]
    }
  }
}

Important: Update the paths in the configuration:
- Replace [install directory]/agent-state with the absolute path to this project on your system
- Use forward slashes for paths even on Windows
Restart Cursor for the changes to take effect.

Alternative: Using the virtual environment directly

If you prefer to use the virtual environment's Python directly:

Find the path to your virtual environment's Python:

which uv run python  # Shows the resolved path

Use that path in your MCP configuration instead of uv run python.

Development

Code Quality

Run linting:
```
uv run ruff check .
```
Run type checking:
```
uv run pyright
```
Format code:
```
uv run ruff format .
```

Project Structure

main.py - Main MCP server with agent state and log management tools
AGENTS.md - Coding style guidelines for this project
pyproject.toml - Project configuration and dependencies

License

MIT

Setting up MCP in Claude Desktop

Open Claude Desktop settings:

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

Add the MCP server configuration:

{
  "mcpServers": {
    "agent-state": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "[install directory]/agent-state/main.py"
      ]
    }
  }
}

Important: Update the paths in the configuration:

Replace [install directory]/agent-state with the absolute path to this project on your system
Ensure the path uses forward slashes on all platforms

Restart Claude Desktop for the changes to take effect.

Setting up MCP in Cursor (OpenCode)

Open Cursor settings:

Press Cmd+, (macOS) or Ctrl+, (Windows/Linux) to open settings
Or go to File > Preferences > Settings

Search for "MCP" in the settings

Add the MCP server configuration in your settings JSON:

{
  "mcp.servers": {
    "agent-state": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "[install directory]/agent-state/main.py"
      ]
    }
  }
}

Important: Update the paths in the configuration:

Replace [install directory]/agent-state with the absolute path to this project on your system
Use forward slashes for paths even on Windows

Restart Cursor for the changes to take effect.

Development

Code Quality

Run linting:

uv run ruff check .

Run type checking:

uv run pyright

Format code:

uv run ruff format .

Project Structure

main.py - Main MCP server with agent state and log management tools

AGENTS.md - Coding style guidelines for this project

pyproject.toml - Project configuration and dependencies