简体中文 | [English](README_EN.md)

# 聚法-法律数据智能服务 MCP Server

`jufa-mcp-server` 是聚法法律数据服务的开源 MCP 接入层。它在启动时连接聚法现有的 12 类远程 MCP Server，将当前可用工具聚合为一个本地 `stdio` Server，方便 WorkBuddy、CodeBuddy、Cursor 等兼容 MCP 的 AI 客户端统一接入。

本仓库只包含协议适配和请求转发代码，不包含聚法数据库、检索算法、计费实现或主站核心业务源码。实际法律数据由聚法托管服务提供。

## 数据能力

| 领域 | 上游路径 | 工具名前缀 |
| --- | --- | --- |
| 司法案例 | `/mcp/case` | `jufa_case_` |
| 法律法规 | `/mcp/law` | `jufa_law_` |
| 检察文书 | `/mcp/jcws` | `jufa_jcws_` |
| 合同模板 | `/mcp/contract` | `jufa_contract_` |
| 招投标 | `/mcp/tender` | `jufa_tender_` |
| 企业信息 | `/mcp/company` | `jufa_company_` |
| 商标信息 | `/mcp/trademark` | `jufa_trademark_` |
| 失信信息 | `/mcp/dishonest` | `jufa_dishonest_` |
| 专利信息 | `/mcp/patent` | `jufa_patent_` |
| 司法拍卖 | `/mcp/auction` | `jufa_auction_` |
| 开庭公告 | `/mcp/court` | `jufa_court_` |
| 行政处罚 | `/mcp/penalty` | `jufa_penalty_` |

工具定义在进程启动时通过各上游的 `tools/list` 获取。重启本服务即可同步聚法平台最新启用的工具及参数定义。

## 获取 API Key

1. 访问[聚法智能体数据平台](https://www.jufaai.com/agent)并登录。
2. 在[个人中心](https://www.jufaai.com/agent/profile)获取 API Key。
3. 使用前可查看[接入指南](https://www.jufaai.com/agent/guide)和[数据能力与积分价格](https://www.jufaai.com/agent/data)。

API Key 属于敏感凭证。请只通过环境变量配置，不要写入代码、截图、日志或 Git 提交。

## 运行要求

- Node.js 20 或更高版本
- 可访问 `https://www.jufaai.com`
- 有效的聚法 API Key 和可用账户

## 快速开始

直接运行：

```bash
JUFA_API_KEY="你的_api_key" npx -y jufa-mcp-server
```

Windows PowerShell：

```powershell
$env:JUFA_API_KEY="你的_api_key"
npx.cmd -y jufa-mcp-server
```

也可以安装到当前项目：

```bash
npm install jufa-mcp-server
JUFA_API_KEY="你的_api_key" npx jufa-mcp-server
```

或全局安装后直接运行：

```bash
npm install -g jufa-mcp-server
JUFA_API_KEY="你的_api_key" jufa-mcp-server
```

`jufa-mcp-server` 已发布到 [npm](https://www.npmjs.com/package/jufa-mcp-server)，以上命令默认使用 npm `latest` 标签对应的最新版本。启动后，进程会通过 `stdio` 等待 MCP 客户端连接。

## MCP 客户端配置

```json
{
  "mcpServers": {
    "jufa-mcp-server": {
      "command": "npx",
      "args": ["-y", "jufa-mcp-server"],
      "env": {
        "JUFA_API_KEY": "你的_api_key"
      }
    }
  }
}
```

在 WorkBuddy 中，可进入“连接器 → 自定义连接器”，按客户端支持的本地 MCP 配置方式填写上述命令和环境变量。Windows 如果提示找不到 `npx`，可将 `command` 改为 Node.js 安装目录中的 `npx.cmd` 绝对路径。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `JUFA_API_KEY` | 是 | 无 | 聚法智能体数据平台 API Key |
| `JUFA_MCP_TIMEOUT_MS` | 否 | `60000` | 单次上游请求超时，必须为正整数毫秒数 |

## 工作机制

1. 启动时依次向全部 12 类服务发送 `initialize` 和 `tools/list`。
2. 上游工具名转换为 `jufa_{领域}_{原工具名}`，避免不同领域重名。
3. 客户端调用工具时，本服务通过 `Authorization: Bearer <JUFA_API_KEY>` 转发到对应上游。
4. 上游返回的 `content`、`structuredContent` 和 `isError` 保持不变。

如果任一领域无法完成工具发现，进程会指出具体上游路径并终止，避免静默提供不完整能力。

## 计费说明

工具调用可能按照聚法智能体数据平台当前公布的积分价格扣费。鉴权、余额检查、调用日志、结果计费和业务数据处理均由聚法托管服务完成。本开源适配器不保存账户余额，也不实现或绕过计费逻辑。

## 常见问题

- `Missing JUFA_API_KEY`：没有配置 API Key，或变量值为空。
- `HTTP 401/403`：API Key 无效、停用、过期，或账户不可用。
- `HTTP 402` 或额度错误：账户余额不足，请在聚法平台查看余额和积分价格。
- `Failed to discover MCP tools`：错误信息会列出失败的 `/mcp/...` 路径；检查网络、API Key 和上游状态后重启。
- 工具清单未更新：工具元数据只在启动时同步，请重启 MCP 进程。

## 安全

请阅读 [SECURITY.md](SECURITY.md)。不要在公开 Issue 中提交 API Key、账户信息、完整法律数据响应或其他敏感信息。

## License

[Apache License 2.0](LICENSE)