DocketBird MCP Server

DocketBird MCP 服务

此 MCP 服务可访问 DocketBird 的法院案件数据和文档管理功能。

要求

• Python 3.11
• uv 包管理器

设置

1. 如果尚未安装 uv，请先安装：

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

2. 创建并激活虚拟环境：

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

3. 安装依赖项：

uv pip install .

4. 设置环境变量：

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

运行服务

使用以下命令运行服务：

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

可用工具

此服务提供以下工具：

1. get_case_details：获取案件的全面详情，包括所有文档
2. download_document_by_id：通过 DocketBird ID 下载指定文档
3. list_cases：获取属于某个账户的案件列表
4. list_courts_and_types：获取所有可用法院和案件类型的完整列表

配置文件

确保以下文件与脚本位于同一目录：

• courts.json：包含所有可用法院的信息
• case_types.json：包含不同案件类型的信息

MCP 服务配置

根据使用的 MCP 客户端，可将 MCP 服务配置添加到以下位置之一：

• Cursor：~/.cursor/mcp.json
• Mac 上的 Claude：~/Library/Application Support/Claude/claude_desktop_config.json

• 如何从应用中打开 Claude Desktop 配置文件
  • 启动 Claude Desktop 应用
  • 前往应用菜单并选择“设置”
  • 在左侧导航面板中选择“开发者”
  • 点击“编辑配置”按钮
  • 系统会自动使用默认文本编辑器打开配置文件

1. 如果尚未安装 uv，请先安装：

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

将以下配置添加到相应文件中：

对于 macOS：

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

对于 Windows：

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

请务必替换：

• PATH_TO_THE_SERVER：替换为克隆 DocketBird MCP 仓库的实际路径（适用于 macOS）
• PATH_TO_SERVER：替换为克隆 DocketBird MCP 仓库的实际路径（适用于 Windows）
• YOUR_KEY：替换为实际的 DocketBird API 密钥

部署

可使用 Docker 和 GitHub Actions 将 DocketBird MCP 服务部署到云服务器。部署流程定义在 .github/workflows/deploy.yml 文件中。

Docker 部署

此服务使用 Docker 进行容器化。你可以使用所需的传输类型，在本地构建并运行 Docker 镜像：

# 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

验证部署

请按照以下步骤验证部署是否正常运行：

1. 检查容器是否正在运行：

docker ps | grep docketbird-mcp

2. 查看容器日志：

docker logs docketbird-mcp

日志应显示：

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

3. 使用本 README 中的配置，从 MCP 客户端测试连接。

如果容器未运行，可通过检查以下内容进行排查：

• Docker 镜像是否存在：docker images | grep docketbird
• 容器日志中是否有错误：docker logs docketbird-mcp
• 服务日志：检查是否存在权限或网络问题

DocketBird Agent 原型

我们创建了一个原型 Agent，用于与已部署的 DocketBird MCP 服务交互。此 Agent 提供了一个易于使用的界面，用于查询案件信息和文档详情。

功能

• 交互式命令行界面
• 使用自然语言查询案件信息
• 连接到已部署的 DocketBird MCP 服务

设置和运行

1. 确保已将 OpenAI API 密钥设置为环境变量：

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. 前往项目目录并运行 Agent：

cd agents
python db_agent_prototype.py

3. Agent 会显示欢迎横幅，并提示你输入第一个查询。

4. 查询示例：

   • “请检索 txnd-3:2007-cv-01697 的详情”
   • “此案件有哪些可用文档？”
   • “此案件最近一次提交是什么时候？”

要求

Agent 需要：

• OpenAI API 密钥（用于 GPT-4.1 模型）
• 互联网连接，以访问已部署的 MCP 服务
• Python 依赖项：pydantic_ai、termcolor、python-dotenv

注意：这是一个原型，使用了已部署的 DocketBird MCP 服务：http://165.227.221.151:8040/sse。