Complemento MCP OAuth de datos legales de 企查查 (DeepSeek Harness)

One-click OAuth connect to 企查查 (Qichacha) 法律数据 MCP inside DeepSeek Harness. Conexión OAuth con un clic al MCP de datos legales de 企查查 en DeepSeek Harness (regulaciones y artículos legales / casos judiciales).

Funciones / Características

• 🔑 Conexión OAuth con un clic: Authorization Code + PKCE(S256), registro dinámico del cliente (sin client_secret), apertura automática del navegador hacia la página de autorización de 企查查 y finalización automática mediante callback loopback.

• 🌐 Una autorización, disponible en todos los servidores: un único access_token / refresh_token cubre los servidores MCP de datos legales de 企查查 (legal-regulation regulaciones / legal-case casos, 2 en total); el complemento monta dinámicamente según el alcance real de autorización del token: 2 para cuentas con regulaciones y casos, 1 para cuentas solo con regulaciones.

• 🔄 Actualización automática: refresh automático antes de que expire el access_token (rotación de token); solo se requiere reautorización si falla.

• 💾 Persistencia segura: el token se almacena en el dominio de almacenamiento de DSH (~/.dsh/storages, directorio 0700); al reiniciar el Host la conexión se restaura automáticamente.

• 🛠 Gestión mediante conversación: incluye tres herramientas integradas: qcc_legal_oauth_connect / qcc_legal_oauth_status / qcc_legal_oauth_disconnect.

• 🚪 Desconexión con un clic: llama a OAuth revoke para revocar el refresh_token y desactiva las herramientas MCP.

• 🧩 Coexiste con el complemento de datos empresariales: los nombres de herramientas, el dominio de almacenamiento y los ids de entrada son completamente independientes del «Complemento MCP OAuth de 企查查» (company/risk/...), por lo que pueden instalarse simultáneamente.

Related MCP server: just-one-mcp

Instalación

Requisitos previos: DeepSeek Harness (CLI dsh, perfil web), Node ≥ 20.

🤖 Instalación mediante el agente (la más sencilla, recomendada para usuarios que no dominan la línea de comandos)

Envía el siguiente enlace directamente a tu conversación de DeepSeek Harness (se recomienda buscar primero «企查查法律数据» en el mercado de complementos dshmarket e instalarlo con un clic; si la instalación directa desde el mercado falla, envía también el enlace al agente para que lo instale por ti):

帮我安装这个插件 https://github.com/duhu2000/qcc-mcp-legal-oauth

El agente ejecutará los siguientes comandos según este README (también puedes ejecutarlos tú mismo):

# 方式一：一键脚本（自动安装 + 注册 bundle + 提示重启）
bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/qcc-mcp-legal-oauth/main/install.sh)

# 方式二：手动两步
dsh plugin --profile web add qcc-dsh-mcp-legal-oauth   # 安装依赖并自动注册 bundle
# 重启 dsh web

Nota: las advertencias de peer dependencies durante la instalación pueden ignorarse: las dependencias pares como @deepseek-ai/* las proporciona el perfil web de DSH (dependencias del host) y no requieren instalación adicional; después de la instalación debe reiniciar dsh web para que surta efecto.

Opción A: instalación mediante npm

# 1. 安装插件到 profile（声明了 dsh.bundle 的包会被 dsh plugin add 自动注册到 bundles）
dsh plugin --profile web add qcc-dsh-mcp-legal-oauth

# 2. 重启 dsh web

Si no se registra automáticamente: añada manualmente "qcc-dsh-mcp-legal-oauth" a dsh.profile.bundles en ~/.dsh/profiles/web/package.json (junto a @deepseek-ai/dsh-base y @deepseek-ai/dsh-web-app) y reinicie.

Opción B: instalación directa desde GitHub

dsh plugin --profile web add github:duhu2000/qcc-mcp-legal-oauth
# 再重启 dsh web

Opción C: código fuente / depuración local

git clone https://github.com/duhu2000/qcc-mcp-legal-oauth.git
cd qcc-mcp-legal-oauth
dsh plugin --profile web add "link:$(pwd)"      # 或 pnpm add "file:$(pwd)"
# 再重启 dsh web

El paquete del complemento incluye cordis.patch.yml (bundle patch); dsh plugin add realiza automáticamente la instalación de dependencias y el registro de bundles, y la línea del complemento se integra automáticamente sin necesidad de modificar ningún archivo manualmente.

Uso

Después de reiniciar, el complemento inicia automáticamente la autorización OAuth (activada por defecto: cuando está activo y no hay una autorización válida, abre automáticamente la página de autorización de 企查查); si no se activa automáticamente, escribe en la conversación:

Una vez conectado, las siguientes herramientas están disponibles directamente (ejemplos):

• mcp__legal-regulation__*: regulation_search (búsqueda por palabras clave de regulaciones), regulation_detail (texto completo de la regulación), regulation_detail_article (texto original del artículo), etc.

• mcp__legal-case__*: case_search (búsqueda por palabras clave de casos), case_detail (documento completo del caso), etc.

• Herramientas de trazabilidad: trazabilidad de regulaciones / trazabilidad de casos (verificación de citas + enlaces en los que se puede hacer clic).

Cómo funciona

Sigue estrictamente el «Documento de integración OAuth del MCP de 企查查» (Authorization Code + PKCE, versión de interfaz pública) y comparte el mismo servidor de autorización que el complemento MCP de datos empresariales:

1. Descubrir los metadatos de recursos protegidos del MCP → 2. Descubrir los metadatos del servidor OAuth (todos los endpoints se leen dinámicamente, sin codificación fija).

2. Registrar el cliente dinámicamente (client_id, renovación automática cada 90 días) → 4. Abrir la página de autorización (scope=mcp:tools).

3. Validar state en el callback loopback → 6. Intercambiar el código de autorización + code_verifier por el token.

4. Analizar el resource realmente autorizado por el token (claim JWT) e inyectar el encabezado Bearer a través de ctx.loader en las entradas autorizadas de @deepseek-ai/dsh-mcp-client (2 para regulaciones y casos / 1 solo para regulaciones) → 8. Refresco automático antes de la expiración (rotación).

Ver detalles en docs/OAUTH-IMPLEMENTATION.md.

La lista de herramientas y ejemplos de invocación se detallan en docs/TOOLS.md.

Configuración

La línea del complemento se encuentra en ~/.dsh/profiles/web/cordis.patch.yml (visible después de la integración del bundle):

- id: qcc-legal-mcp-oauth
  name: 'qcc-dsh-mcp-legal-oauth'
  config:
    issuer: 'https://agent.qcc.com'                 # OAuth 授权服务器
    clientName: 'DeepSeek Harness - QCC Legal MCP'  # OAuth 客户端名（授权页展示 + 后台品牌识别依据）
    refreshSkewMs: 300000                            # 过期前提前刷新（ms）
    openBrowser: true                                # 自动打开浏览器（false = 仅打印授权 URL）
    autoConnectOnActivate: true                      # 激活且无授权时自动打开授权页（false = 手动触发）
    persistTokens: true                              # 持久化 token（false = 仅内存）
    mcpEntryPrefix: 'mcp-qcc'                        # 受管 mcp-client 条目 id 前缀（条目：mcp-qcc-legal-regulation / mcp-qcc-legal-case）

Acerca de clientName: es el client_name del protocolo OAuth; 企查查 lo escribe en el claim client_name del access_token y se utiliza para identificación de marca en el panel de administración (el lado de 企查查 elimina espacios/guiones/guiones bajos del nombre, lo convierte a minúsculas y lo normaliza como fuente de activación deepseekharness según el prefijo deepseekharness*). El valor predeterminado DeepSeek Harness - QCC Legal MCP ya coincide con ese prefijo. Si desea personalizarlo, mantenga el prefijo DeepSeek Harness; de lo contrario, el panel lo clasificará como «Otros (no registrado)» y no podrá contabilizar correctamente las activaciones de marca.

Seguridad

• El token solo se escribe en ~/.dsh/storages (0700), no entra en git ni en el historial de conversación.

• Durante la conexión, loader escribe la configuración de la entrada de vuelta al archivo de configuración del perfil (incluido el token). Se recomienda: chmod 600 ~/.dsh/profiles/web/cordis.yml; no agregue ~/.dsh a ningún repositorio.

• El token Bearer solo se envía a las URL de resource exactas dentro del conjunto autorizado.

• Al desconectar, se llama a revoke para revocar el refresh_token.

• Para eliminar por completo: después de qcc_legal_oauth_disconnect, retire el nombre del paquete de los bundles y ejecute dsh plugin --profile web remove qcc-dsh-mcp-legal-oauth.

Limitaciones conocidas

• El complemento gestiona por defecto 2 servidores de datos legales (legal-regulation regulaciones / legal-case casos); el token de la cuenta puede autorizar solo uno de ellos, y el complemento monta dinámicamente según el alcance real de autorización del token (2 / 1).

• Los servidores de datos empresariales (company/risk/ipr/operation/history/executive) son gestionados por el «Complemento MCP OAuth de 企查查» independiente (qcc-dsh-mcp-oauth); este complemento no los gestiona de forma redundante. Ambos complementos pueden instalarse simultáneamente.

• Los complementos de terceros no pueden registrar tarjetas en la página de configuración de DSH (limitación de la allowlist de apiproxy); la entrada de gestión son las herramientas de conversación.

• El callback utiliza una dirección loopback local, adecuada para escritorio; para SaaS/Web, la dirección de callback debe confirmarse previamente con 企查查 en la lista blanca.

• La conexión directa con una API Key estática (Bearer YOUR_API_KEY) pertenece a otro canal de conexión directa de 企查查 y no es responsabilidad de este complemento; si necesita una Key estática, basta con usar la configuración normal de mcp-client.

Desarrollo

npm install          # 需要 host 依赖时（见 docs/INSTALL.md）
npm run lint         # 语法检查
npm test             # 单元 + 集成测试（含 mock OAuth 服务器全流程）

Cobertura de pruebas: PKCE, descubrimiento de metadatos, registro dinámico, flujo completo de código de autorización (loopback), rotación de refresh, revoke, integración a nivel de complemento (conexión/idempotencia/refresco automático/desconexión/restauración tras reinicio/montaje dinámico según la autorización del token).

Inclusión en el mercado de complementos y palabras clave de búsqueda

Este complemento se puede descubrir e instalar a través de los siguientes canales:

1. Topic dsh-plugin (canal de descubrimiento recomendado oficialmente): DeepSeek Harness recomienda oficialmente descubrir complementos mediante el topic dsh-plugin de GitHub; este repositorio ya tiene ese topic. Mercados comunitarios como dsh-plugin-marketplace lo recopilan automáticamente; la búsqueda utiliza la búsqueda de repositorios de GitHub (nombre del repositorio / descripción / topic). La inclusión es inmediata pero sin revisión humana.

2. dshmarket (mercado de complementos comunitario, selección manual + revisión mediante PR): la fuente de datos es la lista seleccionada de awesome-dsh-plugin; solo se instalan fuentes incluidas en la lista. Este complemento ya ha enviado el PR de inclusión (data/plugins/duhu2000__qcc-mcp-legal-oauth.yml); una vez fusionado, se puede explorar en «Configuración → Mercado de complementos», buscar «企查查法律数据» e instalarlo con un clic. Método de instalación: la CLI oficial admite la instalación genérica con dsh plugin add <package>, y dshmarket ofrece dsh plugin --profile web add dshmarket en consecuencia.

Para facilitar la búsqueda en chino / inglés, se han cubierto las siguientes palabras clave:

• Chino: 企查查, 法律产品, 法律数据, 法规, 案例 (escritas en la descripción del repositorio y en la descripción zh de la lista seleccionada).

• Inglés: qcc, qichacha, legal, law, legal-tech, legal-data, regulation, case (escritas en el nombre del repositorio / descripción / topic / palabras clave npm).

Licencia

MIT