# 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:
```bash
uv sync
```
2. Activate the virtual environment (if needed):
```bash
source .venv/bin/activate # On macOS/Linux
# or
.venv\Scripts\activate # On Windows
```
## Running the Server
Run the MCP server:
```bash
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:
```json
{
"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:
```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:
```bash
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:
```bash
uv run ruff check .
```
- Run type checking:
```bash
uv run pyright
```
- Format code:
```bash
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
