企查查法律数据 MCP OAuth 插件（DeepSeek Harness）

One-click OAuth connect to 企查查 (Qichacha) 法律数据 MCP inside DeepSeek Harness. DeepSeek Harness에서 원클릭 OAuth 인증으로 企查查 법률 데이터 MCP에 연결합니다（법규 법조 / 사법 판례）。

기능 / Features

• 🔑 원클릭 OAuth 연결: Authorization Code + PKCE(S256), 동적 클라이언트 등록(client_secret 없음), 브라우저를 자동으로 열어 企查查 인증 페이지로 이동, loopback 콜백 자동 완료

• 🌐 한 번의 인증으로 모든 Server 사용 가능: 하나의 access_token / refresh_token으로 企查查 법률 데이터 MCP SERVER(legal-regulation 법규 / legal-case 판례, 총 2개)를 커버합니다. 플러그인은 token의 실제 인증 범위에 따라 동적으로 마운트합니다——법규+판례를 모두 개통한 계정은 2개, 법규만 개통한 계정은 1개.

• 🔄 자동 갱신: access_token 만료 전에 자동으로 refresh(token 순환), 실패 시에만 재인증 필요

• 💾 안전한 영속화: token은 DSH 스토리지 도메인(~/.dsh/storages, 디렉터리 0700)에 저장되며, Host를 재시작하면 연결이 자동으로 복구됩니다.

• 🛠 대화로 관리: qcc_legal_oauth_connect / qcc_legal_oauth_status / qcc_legal_oauth_disconnect 세 가지 도구 내장

• 🚪 원클릭 연결 해제: OAuth revoke를 호출하여 refresh_token을 폐기하고 MCP 도구를 비활성화합니다.

• 🧩 기업 데이터 플러그인과 공존 가능: 도구 이름, 스토리지 도메인, 항목 id가 「企查查 MCP OAuth 插件」(company/risk/...)과 완전히 독립적이므로 동시에 설치할 수 있습니다.

Related MCP server: lark-mcp

설치 / Install

전제 조건: DeepSeek Harness(dsh CLI, web profile), Node ≥ 20.

🤖 Agent가 설치하도록 하기(가장 간편, 명령줄에 익숙하지 않은 사용자에게 권장)

아래 링크를 DeepSeek Harness 대화에 직접 보내세요(먼저 dshmarket 플러그인 마켓에서 「企查查法律数据」를 검색하여 원클릭 설치하는 것을 권장합니다. 마켓 직접 설치가 실패하면 링크를 Agent에게 보내 대신 설치하게 할 수도 있습니다):

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

Agent가 이 README에 따라 다음 명령을 실행합니다(직접 실행해도 됩니다):

# 方式一：一键脚本（自动安装 + 注册 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

참고: 설치 시 peer dependencies 경고는 무시해도 됩니다——@deepseek-ai/* 등의 피어 의존성은 DSH web profile에 내장되어 있으므로(host 의존성) 별도로 설치할 필요가 없습니다. 설치 완료 후 반드시 dsh web을 재시작해야 적용됩니다.

방식 A: npm 설치

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

# 2. 重启 dsh web

자동 등록되지 않은 경우: ~/.dsh/profiles/web/package.json의 dsh.profile.bundles에 수동으로 "qcc-dsh-mcp-legal-oauth"를 추가하고(@deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app와 나란히), 다시 시작하세요.

방식 B: GitHub 직접 설치

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

방식 C: 소스 코드 / 로컬 디버깅

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

플러그인 패키지에는 cordis.patch.yml(bundle patch)이 포함되어 있습니다. dsh plugin add가 의존성 설치와 bundles 등록을 자동으로 완료하고 플러그인 행이 자동으로 병합되므로 어떤 파일도 수동으로 수정할 필요가 없습니다.

사용 / Usage

재시작 후 플러그인이 자동으로 OAuth 인증을 시작합니다(기본 활성화, 활성 상태이고 유효한 인증이 없으면 企查查 인증 페이지가 자동으로 열립니다). 자동으로 트리거되지 않으면 대화에 다음을 입력하세요:

연결 성공 후 다음 도구를 바로 사용할 수 있습니다(예시):

• mcp__legal-regulation__*: regulation_search(법규 키워드 검색), regulation_detail(법규 전문), regulation_detail_article(법조문 원문) 등

• mcp__legal-case__*: case_search(판례 키워드 검색), case_detail(판례 전체 문서) 등

• 출처 추적 도구: 법규 출처 추적 / 판례 출처 추적(인용 검증 + 클릭 가능한 하이퍼링크)

원리 / How it works

《企查查 MCP OAuth 접속 문서》(Authorization Code + PKCE, 공개 인터페이스 버전)를 엄격히 준수하며, 기업 데이터 MCP 플러그인과 동일한 인증 서버를 공유합니다:

1. MCP Protected Resource Metadata 발견 → 2. OAuth Server Metadata 발견(endpoint는 모두 동적으로 읽어오며 하드코딩하지 않음)

2. 동적 클라이언트 등록(client_id, 90일 자동 갱신) → 4. 인증 페이지 열기(scope=mcp:tools)

3. loopback 콜백에서 state 검증 → 6. 인증 코드 + code_verifier로 token 교환

4. token이 실제로 인증한 resource(JWT claim)를 파싱하고, ctx.loader를 통해 인증된 @deepseek-ai/dsh-mcp-client 항목에 Bearer header를 주입(법규+판례 2개 / 법규만 1개) → 8. 만료 전 자동 갱신(순환)

자세한 내용은 docs/OAUTH-IMPLEMENTATION.md를 참조하세요.

도구 목록과 호출 예시는 docs/TOOLS.md를 참조하세요.

구성 / Configuration

플러그인 행은 ~/.dsh/profiles/web/cordis.patch.yml에 있습니다(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）

clientName 관련: OAuth 프로토콜의 client_name으로, 企查查가 access_token의 client_name claim에 기록하며 백엔드 대시보드 브랜드 식별에 사용됩니다(企查查 측에서 이름의 공백/하이픈/밑줄을 제거하고 소문자로 변환한 뒤, deepseekharness* 접두사 기준으로 활성화 소스 deepseekharness로 정규화합니다). 기본값 DeepSeek Harness - QCC Legal MCP는 이미 해당 접두사를 충족합니다. 사용자 지정이 필요하면 DeepSeek Harness 접두사를 유지하세요. 그렇지 않으면 백엔드에서 「기타(미등록)」로 분류되어 브랜드 활성화가 올바르게 집계되지 않습니다.

보안 설명 / Security

• token은 ~/.dsh/storages(0700)에만 기록되며, git에 들어가지 않고 대화 기록에도 남지 않습니다

• 연결 중 loader가 항목 구성을 profile 설정 파일에 다시 기록합니다(token 포함). 권장: chmod 600 ~/.dsh/profiles/web/cordis.yml; ~/.dsh를 어떤 저장소에도 추가하지 마세요.

• Bearer token은 인증된 컬렉션 내의 정확한 resource URL에만 전송됩니다.

• 연결 해제 시 revoke를 호출하여 refresh_token을 폐기합니다.

• 완전히 제거하려면: qcc_legal_oauth_disconnect 실행 후 bundles에서 패키지 이름을 제거하고 dsh plugin --profile web remove qcc-dsh-mcp-legal-oauth를 실행하세요.

알려진 제한 사항 / Limitations

• 플러그인은 기본적으로 2개의 법률 데이터 SERVER(legal-regulation 법규 / legal-case 판례)를 관리합니다. 계정 token이 그중 하나만 인증할 수 있으므로, 플러그인은 token의 실제 인증 범위에 따라 동적으로 마운트합니다(2개 / 1개).

• 기업 데이터 SERVER(company/risk/ipr/operation/history/executive)는 별도의 「企查查 MCP OAuth 插件」(qcc-dsh-mcp-oauth)이 관리하며, 본 플러그인은 중복 관리하지 않습니다. 두 플러그인은 동시에 설치할 수 있습니다.

• 서드파티 플러그인은 DSH 설정 페이지 카드를 등록할 수 없습니다(apiproxy allowlist 제한). 관리 진입점은 대화 도구입니다.

• 콜백은 로컬 loopback 주소를 사용하므로 데스크톱에 적합합니다. SaaS/Web 콜백 주소는 사전에 企查查와 화이트리스트를 확인해야 합니다.

• 정적 API Key(Bearer YOUR_API_KEY) 직접 연결은 企查查의 별도 직접 연결 채널에 속하므로 본 플러그인의 역할이 아닙니다. 정적 Key가 필요하면 일반 mcp-client 구성으로 바로 사용하면 됩니다.

개발 / Development

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

테스트 범위: PKCE, 메타데이터 발견, 동적 등록, 전체 인증 코드 흐름(loopback), refresh 순환, revoke, 플러그인 수준 통합(연결/멱등성/자동 갱신/연결 해제/재시작 복구/token 인증 범위별 동적 마운트).

플러그인 마켓 등재 및 검색 키워드 / Marketplace

본 플러그인은 다음 채널을 통해 발견 및 설치할 수 있습니다:

1. dsh-plugin topic(공식 권장 발견 채널): DeepSeek Harness 공식은 GitHub dsh-plugin topic을 통해 플러그인을 발견하도록 권장하며, 본 저장소는 이미 해당 topic을 지정했습니다. dsh-plugin-marketplace 등 커뮤니티 마켓이 이를 기반으로 자동 등재하며, 검색은 GitHub 저장소 검색(저장소 이름 / 설명 / topic)을 사용합니다. 등재는 즉시 이루어지지만 수동 검토는 없습니다.

2. dshmarket(커뮤니티 플러그인 마켓, 수동 선별 + PR 게이트 심사): 데이터 소스는 awesome-dsh-plugin 선별 목록이며, 목록 내 소스만 설치합니다. 본 플러그인은 이미 등재 PR(data/plugins/duhu2000__qcc-mcp-legal-oauth.yml)을 제출했으며, 병합 후 「설정 → 플러그인 마켓」에서 「企查查法律数据」를 찾아보고 검색하여 원클릭 설치할 수 있습니다. 설치 방법: 공식 CLI가 dsh plugin add <package> 범용 설치를 지원하며, dshmarket은 이에 따라 dsh plugin --profile web add dshmarket을 제공합니다.

중국어 / 영어 검색을 위해 다음 키워드를 포함했습니다:

• 중국어: 企查查、法律产品、法律数据、法规、案例(저장소 설명과 선별 목록 zh 설명에 기록)

• 영어: qcc, qichacha, legal, law, legal-tech, legal-data, regulation, case(저장소 이름 / 설명 / topic / npm keywords에 기록)

License

MIT