tianhuil/agent-state

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

1. Install dependencies:

   uv sync
   

2. 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

1. Open Claude Desktop settings:

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

2. Add the MCP server configuration:

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

3. 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

4. Restart Claude Desktop for the changes to take effect.

Setting up MCP in Cursor (OpenCode)

1. Open Cursor settings:

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

2. Search for "MCP" in the settings

3. Add the MCP server configuration in your settings JSON:

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

4. 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

5. 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:

1. Find the path to your virtual environment's Python:

   which uv run python  # Shows the resolved path
   

2. 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