# DocketBird MCP Server

This MCP server provides access to DocketBird's court case data and document management functionality.

## Requirements

- Python 3.11
- uv package manager

## Setup

1. Install uv if you haven't already:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. Create and activate a virtual environment:

```bash
uv venv
source .venv/bin/activate  # On Unix/MacOS
# OR
.venv\Scripts\activate     # On Windows
```

3. Install dependencies:

```bash
uv pip install .
```

4. Set up your environment variables:

```bash
export DOCKETBIRD_API_KEY=your_api_key_here  # On Unix/MacOS
# OR
set DOCKETBIRD_API_KEY=your_api_key_here     # On Windows
```

## Running the Server

Run the server using:

```bash
uv run docketbird_mcp.py --transport stdio  # For stdio transport
uv run docketbird_mcp.py --transport sse    # For SSE transport
```

## Available Tools

The server provides the following tools:

1. `get_case_details`: Get comprehensive details about a case including all documents
2. `download_document_by_id`: Download a specific document by its DocketBird ID
3. `list_cases`: Get a list of cases belonging to an account
4. `list_courts_and_types`: Get a comprehensive list of all available courts and case types

## Configuration Files

Make sure these files are in the same directory as the script:

- `courts.json`: Contains information about all available courts
- `case_types.json`: Contains information about different types of cases

## MCP Server Configuration

The MCP server configuration can be added to one of these locations depending on your MCP client:

- Cursor: `~/.cursor/mcp.json`
- Claude in mac: `~/Library/Application Support/Claude/claude_desktop_config.json`

* How to open Claude Desktop config file from app
  - Launch Claude Desktop application
  - Navigate to the application menu and select Settings
  - Select Developer from the left navigation panel
  - Click the Edit Config button
  - Your system will automatically open the configuration file in your default text editor

1. Install uv if you haven't already:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Add the following configuration to the appropriate file:

_For macOS:_

```json
{
  "mcpServers": {
    "docketbird-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "PATH_TO_THE_SERVER/docketbird-mcp",
        "python",
        "docketbird_mcp.py"
      ],
      "env": {
        "DOCKETBIRD_API_KEY": "YOUR_KEY"
      }
    }
  }
}
```

_For Windows:_

```json
{
  "mcpServers": {
    "docketbird-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "PATH_TO_SERVER\\docketbird-mcp",
        "python",
        "docketbird_mcp.py"
      ],
      "env": {
        "DOCKETBIRD_API_KEY": "YOUR_KEY"
      }
    }
  }
}
```

Be sure to replace:

- PATH_TO_THE_SERVER with the actual path to where you cloned the DocketBird MCP repository (for macOS)
- PATH_TO_SERVER with the actual path to where you cloned the DocketBird MCP repository (for Windows)
- YOUR_KEY with your actual DocketBird API key

## Deployment

The DocketBird MCP server can be deployed to a cloud server using Docker and GitHub Actions. The deployment process is defined in the `.github/workflows/deploy.yml` file.

### Docker Deployment

The server is containerized using Docker. You can build and run the Docker image locally with the desired transport type:

```bash
# Build for ARM architecture (M1/M2 Mac)
docker buildx build --platform linux/arm64 -t docketbird-mcp-arm:latest --load .

# Build for AMD architecture (standard servers)
docker buildx build --platform linux/amd64 -t docketbird-mcp:latest --load .

# Run locally with stdio transport
docker run -d \
  --name docketbird-mcp-stdio \
  --restart=always \
  -e DOCKETBIRD_API_KEY="your_api_key_here" \
  -e TRANSPORT_TYPE="stdio" \
  docketbird-mcp-arm:latest /app/start.sh

# Run locally with SSE transport
docker run -d \
  --name docketbird-mcp-sse \
  --restart=always \
  -e DOCKETBIRD_API_KEY="your_api_key_here" \
  -e TRANSPORT_TYPE="sse" \
  docketbird-mcp-arm:latest /app/start.sh
```

### Validating Deployment

To validate that your deployment is working correctly:

1. Check that the container is running:

```bash
docker ps | grep docketbird-mcp
```

2. Verify the container logs:

```bash
docker logs docketbird-mcp
```

The logs should show:

```
Starting DocketBird MCP server...
API Key set: your_...
Running python docketbird_mcp.py
```

3. Test the connection from your MCP client using the configuration from this README.

If the container isn't running, you can troubleshoot by checking:

- Docker image exists: `docker images | grep docketbird`
- Container logs for errors: `docker logs docketbird-mcp`
- Server logs: Check if there are any permission or network issues

## DocketBird Agent Prototype

A prototype agent has been created to interact with the deployed DocketBird MCP server. This agent provides a user-friendly interface for querying case information and document details.

### Features

- Interactive command-line interface
- Natural language querying for case information
- Connects to the deployed DocketBird MCP server

### Setup and Running

1. Ensure you have the OpenAI API key set as an environment variable:

```bash
export OPENAI_API_KEY=your_openai_api_key_here  # On Unix/MacOS
# OR
set OPENAI_API_KEY=your_openai_api_key_here     # On Windows
```

2. Navigate to the project directory and run the agent:

```bash
cd agents
python db_agent_prototype.py
```

3. The agent will display a welcome banner and prompt you for your first query.

4. Example queries:
   - "Please retrieve details for txnd-3:2007-cv-01697"
   - "What documents are available in this case?"
   - "When was the last filing in this case?"

### Requirements

The agent requires:

- OpenAI API key (for GPT-4.1 model)
- Internet connection to access the deployed MCP server
- Python dependencies: pydantic_ai, termcolor, python-dotenv

Note: This is a prototype that uses the already deployed DocketBird MCP server at http://165.227.221.151:8040/sse.