Metadata-Version: 2.4
Name: devnors-mcp
Version: 0.1.0
Summary: Devnors Data MCP Server —— 一个 API Key 让 AI 调用所有数据（法律等官方权威数据）
Author: Devnors
License: MIT
Project-URL: Homepage, https://data.devnors.com
Project-URL: Documentation, https://data.devnors.com/console/docs
Keywords: devnors,data,mcp,legal,agent,llm,claude,cursor
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: devnors-data>=0.1.0
Dynamic: license-file

# Devnors Data MCP Server

一个 API Key，让 Claude / Cursor 等 AI 助手直接调用 Devnors Data 的高质量数据（法律等多领域官方权威数据，每条出处可回溯）。

## 安装

> PyPI 正式发布进行中（打 `mcp-v*` tag 触发，见 [docs/RELEASE.md](../docs/RELEASE.md)）。发布后：

```bash
pip install devnors-mcp
```

发布前可用源码安装（从仓库根目录，MCP 依赖 SDK）：

```bash
pip install -e ./sdk -e ./mcp_server
```

## 在 Claude Desktop / Cursor 接入

在 MCP 配置（Claude Desktop 的 `claude_desktop_config.json` 或 Cursor 的 `~/.cursor/mcp.json`）加入：

```json
{
  "mcpServers": {
    "devnors-data": {
      "command": "devnors-mcp",
      "env": {
        "DEVNORS_API_KEY": "devnors_sk_live_xxx"
      }
    }
  }
}
```

填入 API Key 即可，其余由 Agent 自己操作：它会先用 `list_capabilities` 自发现能调什么、怎么调、出错怎么办，再按需检索。

API Key 在 [开发者控制台](https://data.devnors.com/console) 创建。

### 环境变量

| 变量 | 必填 | 说明 |
|---|---|---|
| `DEVNORS_API_KEY` | 是 | API Key（`devnors_sk_...`），控制台创建 |
| `DEVNORS_DATA_BASE_URL` | 否 | 覆盖服务地址，默认 `https://data.devnors.com`（私有化/自测时用） |

## 提供的工具

| 工具 | 说明 |
|---|---|
| `list_capabilities` | 自发现：拉取 `/capabilities.json`，返回可调 domain/type、filters、字段、示例、错误码 |
| `legal_case_search` | 检索裁判文书（官方公开，出处可回溯） |
| `legal_law_search` | 检索现行法律法规条文 |
| `data_query` | 统一入口：任意 `domain` + `type` + `filters` 查询 |

## 计费与错误处理

按次调用计费，成功返回含 `units`（消耗 tokens）与 `request_id`。失败返回结构化错误，Agent 可据此自纠：

| `code` | 含义 | `retryable` | 建议动作 |
|---|---|---|---|
| `unauthorized` | Key 无效/缺失 | 否 | 检查 `DEVNORS_API_KEY` |
| `insufficient_balance` | 余额不足 | 否 | 前往控制台充值 |
| `rate_limited` | 触发限流 | 是 | 按 `Retry-After` 退避后重试 |
| `invalid_capability` | domain/type 无效 | 否 | 用 `list_capabilities` 查可用组合 |
| `not_implemented` | 该域规划中 | 否 | 改用 live 域 |
| `unavailable` / `upstream_error` | 上游暂不可用 | 是 | 短暂退避后重试 |

`retryable=是` 的错误（`429`/`5xx`）由底层 SDK 自动有界退避重试，MCP 层不再叠加；重试耗尽仍失败才回传上表错误。

## 故障排查

- **报 `unauthorized`**：确认 `DEVNORS_API_KEY` 已设且未吊销；控制台可重建 Key。
- **连接超时/`unavailable`**：确认能访问 `DEVNORS_DATA_BASE_URL`（默认公网 `data.devnors.com`）；私有化部署需显式设置该变量。
- **报障对账**：把错误里的 `request_id` 提供给支持，可精确定位单次调用。
