内容
# 法律网格 MCP 服务器
提供人工智能代理访问美国立法数据的强大工具，基于 OpenStates API v3。
## 实时部署
**公共 MCP 服务器**：https://pk-dev-Lawmesh.hf.space/mcp
该服务器已部署在 Hugging Face Spaces 上，可立即与任何兼容 MCP 的客户端一起使用。
## 可用工具
法律网格提供了四种全面的工具，用于查询美国立法信息：
### 1. `list_jurisdictions`
检索所有可用的美国司法管辖区（州、领地、联邦区），可选过滤。
**参数：**
- `classification`（可选）：按类型过滤（"state", "municipality", "country"）
- `include`（可选）：附加数据（"organizations", "legislative_sessions", "latest_runs"）
- `page`, `per_page`：分页支持
### 2. `get_jurisdiction`
获取特定司法管辖区的详细元数据。
**参数：**
- `jurisdiction`（必填）：州缩写、全名或 OpenStates ID
- `include`（可选）：要包含的附加数据
### 3. `get_people`
搜索立法者、州长和政府官员。
**参数：**
- `jurisdiction`, `name`, `id`：过滤条件（至少一个必填）
- `org_classification`：角色过滤（"upper", "lower", "executive"）
- `district`：地区过滤
- `include`：附加传记数据
- 分页支持
### 4. `get_bills`
搜索立法议案、决议和文件。
**参数：**
- `jurisdiction`, `session`, `chamber`：基本过滤器
- `identifier`：特定议案编号
- `classification`：议案类型（"bill", "resolution"）
- `subject`, `sponsor`：内容和发起人过滤器
- `q`：全文搜索
- `updated_since`, `created_since`, `action_since`：日期过滤器
- `include`：附加数据（投票、行动、文件等）
- `sort`：排序选项
- 分页支持
## 架构
法律网格构建于：
- **FastMCP**：现代 MCP 服务器框架
- **Streamable HTTP Transport**：针对 Web 部署进行了优化
- **OpenStates API v3**：美国立法数据的权威来源
- **Async 架构**：高性能并发请求处理
```
┌─────────────────┐ HTTP/MCP ┌─────────────────┐ HTTPS/API ┌─────────────────┐
│ MCP 客户端 │ <-------------> │ 法律网格服务器 │ <-------------> │ OpenStates API │
│ （Claude 等） │ │ （FastMCP） │ │ （v3） │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## 使用 MCP 客户端快速入门
### 示例：Python MCP 客户端
```python
import asyncio
from mcp import create_client_session
from mcp.client.transports.http import create_http_transport
async def main():
# 连接到部署的法律网格服务器
transport = create_http_transport("https://pk-dev-Lawmesh.hf.space/mcp")
async with create_client_session(transport) as session:
# 列出可用工具
tools = await session.list_tools()
print("可用工具：", [tool.name for tool in tools.tools])
# 示例：获取加利福尼亚州司法管辖区
result = await session.call_tool("list_jurisdictions", {
"classification": "state",
"per_page": 10
})
print("司法管辖区：", result.content)
# 示例：搜索加利福尼亚州关于教育的议案
bills = await session.call_tool("get_bills", {
"jurisdiction": "ca",
"subject": "education",
"per_page": 5
})
print("教育议案：", bills.content)
if __name__ == "__main__":
asyncio.run(main())
```
### 示例：与 Claude Desktop 一起使用
将以下内容添加到您的 Claude Desktop MCP 配置中：
```json
{
"mcpServers": {
"lawmesh": {
"url": "https://pk-dev-Lawmesh.hf.space/mcp"
}
}
}
```
## 本地开发设置
### 先决条件
1. **Python 3.13+**
2. **OpenStates API 密钥**：在 [OpenStates.org](https://openstates.org/api/) 获取
3. **环境设置**
### 安装
1. **克隆仓库：**
```bash
git clone <repository-url>
cd Lawmesh
```
2. **安装依赖项：**
```bash
# 使用 pip
pip install -r requirements.txt
# 或使用 uv（推荐）
uv sync
```
3. **环境配置：**
创建 `.env` 文件：
```bash
# .env
OPENSTATES_API_KEY=your_openstates_api_key_here
```
4. **运行服务器：**
```bash
# 开发模式
python app.py
# 或使用 uvicorn
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```
服务器将在以下地址可用：`http://localhost:7860/mcp`
### 本地测试
使用 MCP Inspector 测试本地服务器：
```bash
npx @modelcontextprotocol/inspector http://localhost:7860/mcp
```
## Docker 部署
### 使用附带的 Dockerfile：
```bash
# 构建镜像
docker build -t lawmesh-mcp .
# 运行并设置环境变量
docker run -p 7860:7860 -e OPENSTATES_API_KEY=your_key_here lawmesh-mcp
```
### Docker Compose：
```yaml
# docker-compose.yml
version: '3.8'
services:
lawmesh:
build: .
ports:
- "7860:7860"
environment:
- OPENSTATES_API_KEY=${OPENSTATES_API_KEY}
env_file:
- .env
```
## 依赖项
`pyproject.toml` 中的核心依赖项：
- **fastmcp>=2.12.3**：MCP 服务器框架
- **httpx>=0.28.1**：用于 API 调用的异步 HTTP 客户端
- **uvicorn>=0.36.0**：ASGI 服务器
- **python-dotenv>=1.1.1**：环境变量管理
- **mcp[cli]>=1.14.1**：MCP 协议支持
## 安全性和配置
### 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `OPENSTATES_API_KEY` | 是 | 您的 OpenStates API 密钥 |
| `PORT` | 否 | 服务器端口（默认：7860） |
| `HOST` | 否 | 服务器主机（默认：0.0.0.0） |
### API 密钥安全性
- 永远不要将 API 密钥提交到版本控制中
- 使用环境变量或安全的秘密管理
- 对于 Hugging Face Spaces：配置为存储库秘密
## 用例
- **政治研究**：跟踪立法和投票模式
- **政府透明度**：访问公共立法记录
- **公民参与**：为公民参与构建工具
- **学术研究**：研究美国政治进程
- **新闻和媒体**：自动立法监控
- **法律研究**：访问议案文本和立法历史
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 提交拉取请求
## 许可证
该项目是开源的。请查看 LICENSE 文件了解详情。
## 支持
- **问题**：通过 GitHub Issues 报告错误和功能请求
- **文档**：OpenStates API v3 文档，网址为 [docs.openstates.org](https://docs.openstates.org/api-v3/)
- **MCP 协议**：在 [modelcontextprotocol.io](https://modelcontextprotocol.io/) 上了解更多信息
---
**使用 FastMCP 和 OpenStates API 构建 ❤️**
