accurlex-mcp-server 0.2.0 → 0.2.1

package/README.md

@@ -1,51 +1,24 @@
 # accurLex MCP Server
 
-accurLex 法律 AI 的 MCP 服务，支持 OpenClaw、VS Code GitHub Copilot、Claude Desktop 等 MCP 客户端。
+## Overview
 
-## 快速开始
-
-### 方式一：npx 直接运行（推荐）
+accurLex MCP Server 是一个面向中国法律工作流的 MCP 服务，支持法律问答、合同审查、法律文书生成等能力。通过 MCP（Model Context Protocol）协议，可在 VS Code Copilot、Claude Desktop、Cursor、Windsurf、OpenClaw 等 AI 客户端中使用。
 
-无需 clone 代码，无需手动安装依赖：
-
-```bash
-npx accurlex-mcp-server
-```
+- **npm 包名：** `accurlex-mcp-server`
+- **npm 页面：** https://www.npmjs.com/package/accurlex-mcp-server
+- **官网：** https://accurlex.com
 
-### 方式二：全局安装
+## 前置条件
 
-```bash
-npm install -g accurlex-mcp-server
-```
+- **Node.js ≥ 18** — 运行 `node --version` 确认。无需 clone 代码，无需手动安装依赖。
 
-### 方式三：从源码运行
+## 快速开始
 
-```bash
-git clone https://github.com/accurlex/accurlex-mcp-server.git
-cd accurlex-mcp-server
-npm install
-cp .env.example .env
-npm start
-```
+### 1. 配置 MCP
 
-## 客户端配置
+根据你使用的 AI 客户端，将以下配置添加到对应位置：
 
-### OpenClaw
-
-```json
-{
-  "mcpServers": {
-    "accurlex": {
-      "command": "npx",
-      "args": ["accurlex-mcp-server"]
-    }
-  }
-}
-```
-
-### VS Code GitHub Copilot
-
-在工作区 `.vscode/settings.json` 中添加：
+**VS Code Copilot** — 在工作区**根目录**创建 `.vscode/settings.json`：
 
 ```json
 {
@@ -54,277 +27,98 @@ npm start
       "accurlex": {
         "type": "stdio",
         "command": "npx",
-        "args": ["accurlex-mcp-server"]
+        "args": ["-y", "accurlex-mcp-server"],
+        "env": {
+          "ACCURLEX_PROXY_BASE_URL": "https://accurlex.com",
+          "ACCURLEX_API_BASE_URL": "https://accurlex.com/index.php"
+        }
       }
     }
   }
 }
 ```
 
-### Claude Desktop
-
-编辑 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
+**Claude Desktop** — 编辑 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
 
 ```json
 {
   "mcpServers": {
     "accurlex": {
       "command": "npx",
-      "args": ["accurlex-mcp-server"]
-    }
-  }
-}
-```
-
-## 登录认证
-
-### 方式一：使用 `accurlex_login` 工具（推荐）
-
-连接 MCP 服务后，在 AI 客户端中说：
-
-> "帮我登录 accurLex，手机号 138xxxx1234，密码 xxx"
-
-工具会返回 JWT token，按提示保存到 `.env` 文件，然后重启 AI 客户端即可。
-
-### 方式二：手动配置
-
-1. 在 https://accurlex.com 登录
-2. 打开浏览器开发者工具 → Application → localStorage → 复制 `al_jwt` 值
-3. 填入 `.env`：
-
-```env
-ACCURLEX_BILLING_PHONE=你的手机号
-ACCURLEX_BEARER_TOKEN=你的JWT令牌
-```
-
-JWT 令牌有效期 **7 天**，过期后需重新登录获取。
-
-## 可用工具
-
-| 工具 | 功能 | 计费 |
-|------|------|------|
-| `accurlex_login` | 手机号+密码登录，返回 JWT 令牌 | 免费 |
-| `accurlex_legal_qa` | 中国法律问答（deep 免费 / expert 付费） | deep=免费, expert=扣点 |
-| `accurlex_contract_review` | 合同审查 → 审查意见书（仅 normal 模式） | 扣点 |
-| `accurlex_draft_document` | 法律文书生成（起诉状/答辩状/代理词等） | 扣点 |
-| `accurlex_get_account_status` | 查询账户点数余额 | 免费 |
-| `accurlex_extract_text_from_file` | 提取本地纯文本文件内容 | 免费 |
-
-## 输入限制（与网站对齐）
-
-- 法律问答问题：**10,000 字**
-- 合同审查：合同文本 + 立场合计 **10,000 字**
-- 文书生成事实描述：**10,000 字**
-- 审查人姓名：**40 字**
-
-## 环境变量
-
-| 变量 | 必填 | 说明 |
-|------|------|------|
-| `ACCURLEX_PROXY_BASE_URL` | 是 | 流式 API 地址（默认 `https://accurlex.com`） |
-| `ACCURLEX_API_BASE_URL` | 是 | PHP API 地址（默认 `https://accurlex.com/index.php`） |
-| `ACCURLEX_BILLING_PHONE` | 付费工具需要 | 计费手机号 |
-| `ACCURLEX_BEARER_TOKEN` | 账户查询需要 | 登录后获取的 JWT 令牌 |
-| `ACCURLEX_REQUEST_TIMEOUT_MS` | 否 | 请求超时毫秒数（默认 600000 = 10 分钟） |
-
-## 当前限制
-
-- 单账户模式（凭证来自 `.env`）
-- 文件提取仅支持纯文本：`.txt`、`.md`、`.json`、`.csv`、`.text`
-- 合同审查仅支持 normal 模式（审查意见书），不支持修订版
-- 不支持 DOCX、PDF、图片 OCR（请使用网站处理这些格式）
-
-## 常见问题
-
-### PowerShell 编码问题
-
-通过 PowerShell 管道手动测试时，中文字符可能被破坏。这**不影响**正常使用（VS Code、OpenClaw、Claude Desktop 均正确处理 UTF-8）。
-
-如需命令行测试，先将 JSON 写入 UTF-8 文件：
-
-```powershell
-[System.IO.File]::WriteAllText("test.jsonl", $jsonContent, [System.Text.Encoding]::UTF8)
-Get-Content test.jsonl -Encoding UTF8 | node src/index.js
-```
-
-### "tool_unavailable" 错误
-
-缺少 `.env` 配置。确保 `ACCURLEX_PROXY_BASE_URL` 和 `ACCURLEX_API_BASE_URL` 已设置。付费工具还需要 `ACCURLEX_BILLING_PHONE`。
-
-### "insufficient_balance"（HTTP 402）
-
-账户点数不足，请到 https://accurlex.com 充值。
-
-### JWT 令牌过期
-
-重新调用 `accurlex_login` 获取新令牌，更新 `.env` 后重启即可。
-
----
-
-# accurLex MCP Server (English)
-
-Node.js MCP server that exposes accurLex legal capabilities as MCP tools.  
-Designed for use with OpenClaw, VS Code GitHub Copilot, Claude Desktop, or any MCP-compatible AI client.
-
-## Quick Start
-
-### Option A: npx (recommended)
-
-```bash
-npx accurlex-mcp-server
-```
-
-### Option B: Global install
-
-```bash
-npm install -g accurlex-mcp-server
-```
-
-### Option C: From source
-
-```bash
-git clone https://github.com/accurlex/accurlex-mcp-server.git
-cd accurlex-mcp-server
-npm install
-cp .env.example .env
-npm start
-```
-
-## Configuration
-
-### For OpenClaw
-
-```json
-{
-  "mcpServers": {
-    "accurlex": {
-      "command": "npx",
-      "args": ["accurlex-mcp-server"]
-    }
-  }
-}
-```
-
-### For VS Code GitHub Copilot
-
-Add to your workspace `.vscode/settings.json`:
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "accurlex": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["accurlex-mcp-server"]
+      "args": ["-y", "accurlex-mcp-server"],
+      "env": {
+        "ACCURLEX_PROXY_BASE_URL": "https://accurlex.com",
+        "ACCURLEX_API_BASE_URL": "https://accurlex.com/index.php"
       }
     }
   }
 }
 ```
 
-### For Claude Desktop
-
-Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
-
-```json
-{
-  "mcpServers": {
-    "accurlex": {
-      "command": "npx",
-      "args": ["accurlex-mcp-server"]
-    }
-  }
-}
-```
-
-## Authentication
-
-Two ways to authenticate:
-
-### Option A: Use the `accurlex_login` tool (recommended)
-
-After connecting the MCP server, ask the AI client:
+**Cursor** — 在项目根目录创建 `.cursor/mcp.json`，格式同 Claude Desktop。
 
-> "帮我登录 accurLex，手机号 138xxxx1234，密码 xxx"
-
-The tool will return a JWT token and instructions to save it in `.env`. Then restart the MCP server (reload the AI client window).
+**Windsurf** — 在项目根目录创建 `.windsurf/mcp.json`，格式同 Claude Desktop。
 
-### Option B: Manual configuration
+**OpenClaw** — 使用与 Claude Desktop 相同的 stdio MCP 配置结构。
 
-1. Login at https://accurlex.com
-2. Open browser DevTools → Application → localStorage → copy `al_jwt` value
-3. Fill in `.env`:
-
-```env
-ACCURLEX_BILLING_PHONE=your_phone_number
-ACCURLEX_BEARER_TOKEN=your_jwt_token
-```
+> ⚠️ **Windows 上如果遇到 `npx` 找不到的问题，将 `"command"` 改为 `"npx.cmd"`。**
 
-JWT tokens are valid for **7 days**. After expiry, re-login to get a new token.
+### 2. 重启客户端
 
-## Implemented Tools
+- VS Code：`Ctrl+Shift+P` → `Developer: Reload Window`
+- Claude Desktop：完全退出并重新打开
+- Cursor / Windsurf：重启编辑器
 
-| Tool | Description | Billing |
-|------|-------------|---------|
-| `accurlex_login` | Login with phone + password, returns JWT | free |
-| `accurlex_legal_qa` | Chinese-law legal Q&A (deep free / expert paid) | deep=free, expert=paid |
-| `accurlex_contract_review` | Contract review → 审查意见书 (normal mode only) | paid |
-| `accurlex_draft_document` | Draft legal documents (起诉状/答辩状/代理词 etc.) | paid |
-| `accurlex_get_account_status` | Query account and point balances | free |
-| `accurlex_extract_text_from_file` | Extract text from local plaintext files | free |
+### 3. 验证安装
 
-## Input Limits (aligned with website)
+在 AI 对话中发送以下消息测试（免费，无需登录）：
 
-- Legal QA question: **10,000 chars** max
-- Contract review: contract text + standpoint combined **10,000 chars** max
-- Draft document facts: **10,000 chars** max
-- Reviewer name: **40 chars** max
+> "劳动合同试用期最长不能超过多久？"
 
-## Environment Variables
+如果 AI 调用了 `accurlex_legal_qa` 工具并返回了法律分析，说明安装成功。
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ACCURLEX_PROXY_BASE_URL` | Yes | Streaming API base URL (default: `https://accurlex.com`) |
-| `ACCURLEX_API_BASE_URL` | Yes | PHP API base URL (default: `https://accurlex.com/index.php`) |
-| `ACCURLEX_BILLING_PHONE` | For paid tools | Phone number for billing identity |
-| `ACCURLEX_BEARER_TOKEN` | For account status | JWT token from login |
-| `ACCURLEX_REQUEST_TIMEOUT_MS` | No | Request timeout in ms (default: 600000) |
+### 4. 配置登录信息（使用更多能力前）
 
-## Current Limitations
+如果你需要账户查询，或希望通过登录流程获取当前账号的配置值，可以在 AI 对话中说：
 
-- Single-account per server instance (credentials from `.env`)
-- Local file extraction supports plaintext only: `.txt`, `.md`, `.json`, `.csv`, `.text`
-- Contract review only supports normal mode (审查意见书), revision mode is not available
-- DOCX, PDF, image OCR are not supported (use the website for these)
+> "帮我登录 accurLex，手机号 138xxxx1234，密码 xxx"
 
-## Troubleshooting
+登录成功后，将返回的 `ACCURLEX_BEARER_TOKEN` 和 `ACCURLEX_BILLING_PHONE` 添加到客户端配置的 `env` 字段中，然后重启客户端。
 
-### PowerShell encoding issues
+说明：
 
-When testing via PowerShell stdin pipe, Chinese characters may get corrupted. This only affects manual CLI testing — it does **not** affect normal MCP client usage (VS Code, OpenClaw, Claude Desktop all handle UTF-8 correctly).
+- `accurlex_get_account_status` 需要 `ACCURLEX_BEARER_TOKEN`
+- expert 问答、合同审查、法律文书生成按当前实现需要 `ACCURLEX_BILLING_PHONE`
 
-If you must test via CLI, write the JSON-RPC input to a UTF-8 file first:
+## 可用功能
 
-```powershell
-[System.IO.File]::WriteAllText("test.jsonl", $jsonContent, [System.Text.Encoding]::UTF8)
-Get-Content test.jsonl -Encoding UTF8 | node src/index.js
-```
+| 功能 | 工具名 | 计费 | 预期耗时 |
+|------|--------|------|---------|
+| 法律问答（免费） | `accurlex_legal_qa` (deep) | 免费 | 10-30 秒 |
+| 法律问答（专业） | `accurlex_legal_qa` (expert) | 扣点 | 10-30 秒 |
+| 合同审查 | `accurlex_contract_review` | 扣点 | 1-3 分钟 |
+| 法律文书生成 | `accurlex_draft_document` | 扣点 | 1-2 分钟 |
+| 查询账户余额 | `accurlex_get_account_status` | 免费 | 1-3 秒 |
+| 提取文件文本 | `accurlex_extract_text_from_file` | 免费 | <1 秒 |
 
-### "tool_unavailable" errors
+## 详细文档
 
-Missing `.env` configuration. Ensure `ACCURLEX_PROXY_BASE_URL` and `ACCURLEX_API_BASE_URL` are set. For paid tools, also set `ACCURLEX_BILLING_PHONE`.
+完整的工具参数、工作流、错误处理和平台特定的故障排查指南，请参阅 [.github/skills/accurlex-legal-assistant/SKILL.md](../.github/skills/accurlex-legal-assistant/SKILL.md)。
 
-### "insufficient_balance" (HTTP 402)
+## 常见问题
 
-Your account has insufficient points. Top up at https://accurlex.com.
+| 问题 | 解决方案 |
+|------|---------|
+| 工具未出现在 AI 对话中 | 确认配置文件路径正确（VS Code 必须在工作区**根目录**的 `.vscode/settings.json`），然后重启客户端 |
+| `tool_unavailable` 错误 | 环境变量未设置，检查 `env` 字段中的 `ACCURLEX_PROXY_BASE_URL` 和 `ACCURLEX_API_BASE_URL` |
+| `ENOENT` / `npx` 找不到 | Node.js 未安装或未在 PATH 中，Windows 上尝试将 `command` 改为 `npx.cmd` |
+| 合同审查“超时” | 合同审查正常需要 1-3 分钟，请耐心等待 |
+| JWT 令牌过期 | 重新调用 `accurlex_login`，更新配置中的 `ACCURLEX_BEARER_TOKEN`，重启客户端 |
 
-### JWT token expired
+## Contributing
 
-Re-run `accurlex_login` to get a new token, then update `.env` and restart.
+Contributions are welcome. Please follow the standard Git workflow.
 
-## Suggested Next Steps
+## License
 
-1. Add OAuth or SMS-based login tool for seamless credential setup
-2. Add file upload handling for DOCX, PDF, and OCR workflows
-3. Replace env-bound billing identity with per-user auth for multi-user support
+MIT License. See the LICENSE file for more details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "accurlex-mcp-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "MCP server for accurLex Chinese legal AI — legal Q&A, contract review, law lookup, document drafting",
   "keywords": ["mcp", "legal", "chinese-law", "contract-review", "accurlex", "ai"],
@@ -9,7 +9,7 @@
   "homepage": "https://accurlex.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/accurlex/accurlex-mcp-server"
+    "url": "git+https://github.com/accurlex/accurlex-mcp-server.git"
   },
   "engines": {
     "node": ">=18"