@thinkdata/mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 > ThinkERD MCP Server — AI agents can query your database schema
 
-외부 AI 에이전트(Cursor, Windsurf, Claude Desktop 등)가 ThinkERD의 ERD 스키마를 실시간으로 조회하고, 스키마 변경을 제안할 수 있는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 서버입니다.
+외부 AI 에이전트(Cursor, Windsurf, Claude Code, Claude Desktop 등)가 ThinkERD의 ERD 스키마를 실시간으로 조회하고, 스키마 변경을 제안할 수 있는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 서버입니다.
 
 ## 주요 기능
 
@@ -15,15 +15,13 @@
 
 ### 1. 토큰 발급
 
-ThinkERD 캔버스 → **IDE 연동(MCP)** 버튼 → **토큰 발급**
+ThinkERD 캔버스 설정(My Settings) → **Developer & API** 탭 → **새 토큰 생성**
 
-또는 API로 직접 발급:
-```bash
-curl -X POST https://app.thinkdata.dev/api/tokens \
-  -H "Authorization: Bearer <YOUR_JWT>" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "My MCP Token", "scopes": ["read", "write"]}'
-```
+토큰 발급은 Pro 이상 플랜에서 가능합니다.
+
+스코프는 **필요한 만큼만** 주십시오. `read`만 있는 토큰으로는 쓰기 도구
+(`propose_schema_change`)를 호출할 수 없습니다. 워크스페이스를 지정해 발급하면
+그 워크스페이스 밖의 리소스는 조회되지 않습니다.
 
 ### 2. IDE 설정
 
@@ -33,7 +31,7 @@ curl -X POST https://app.thinkdata.dev/api/tokens \
   "mcpServers": {
     "thinkerd": {
       "command": "npx",
-      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://app.thinkdata.dev", "--token", "<YOUR_TOKEN>"]
+      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io", "--token", "<YOUR_TOKEN>"]
     }
   }
 }
@@ -45,19 +43,45 @@ curl -X POST https://app.thinkdata.dev/api/tokens \
   "mcpServers": {
     "thinkerd": {
       "command": "npx",
-      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://app.thinkdata.dev", "--token", "<YOUR_TOKEN>"]
+      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io", "--token", "<YOUR_TOKEN>"]
     }
   }
 }
 ```
 
+#### Claude Code (레포 루트 `.mcp.json`)
+
+CLI로 붙이는 것이 가장 간단합니다:
+
+```bash
+claude mcp add --scope user thinkerd -- npx -y @thinkdata/mcp-server \
+  --api-url https://api.thinkerd.io --token <YOUR_TOKEN>
+```
+
+스코프는 셋입니다 — `local`(기본, 나만·이 프로젝트만) · `project`(레포 루트 `.mcp.json`, 팀 공유) · `user`(내 모든 프로젝트). 팀과 공유하려면 레포 루트 `.mcp.json`에 직접 적습니다:
+
+```json
+{
+  "mcpServers": {
+    "thinkerd": {
+      "command": "npx",
+      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io"]
+    }
+  }
+}
+```
+
+> ⚠️ **Claude Code는 Claude Desktop의 `claude_desktop_config.json`을 읽지 않습니다.** 이름이 비슷해 그쪽 경로를 따라가는 경우가 있는데, JSON 형식은 같아도 파일이 다릅니다.
+>
+> 그리고 `.mcp.json`은 보통 **버전 관리에 올라갑니다.** 위 예시가 `--token`을 빼고 있는 이유입니다 — 토큰은 `THINKERD_TOKEN` 환경변수로 넘기십시오([환경변수](#환경변수)). 설정 파일에 평문으로 적으면 그대로 커밋됩니다.
+
 #### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
 ```json
 {
   "mcpServers": {
     "thinkerd": {
       "command": "npx",
-      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://app.thinkdata.dev", "--token", "<YOUR_TOKEN>"]
+      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io", "--token", "<YOUR_TOKEN>"]
     }
   }
 }
@@ -71,6 +95,15 @@ AI 채팅에서 다음과 같이 요청하세요:
 - *"ThinkERD 다이어그램의 DDL을 PostgreSQL로 생성해줘"*
 - *"ThinkERD 스키마를 검증해서 문제가 있는지 확인해줘"*
 
+## 원격 연결
+
+현재는 **stdio 트랜스포트만** 지원합니다(Cursor·Windsurf·Claude Code·Claude Desktop 등 로컬 호스트).
+
+`--sse` 모드는 0.2.0에서 제거했습니다. 구현이 모듈 스코프에 트랜스포트 하나만
+두고 있어 **두 번째 클라이언트가 첫 번째의 연결을 끊었고**, MCP 스펙에서도 SSE는
+Streamable HTTP로 대체되는 폐기 경로입니다. 원격 연결은 호스티드 방식으로 별도
+제공할 예정입니다.
+
 ## Resources (읽기 전용)
 
 | Resource URI | 설명 |
@@ -83,19 +116,39 @@ AI 채팅에서 다음과 같이 요청하세요:
 
 ## Tools (액션 실행)
 
+정본은 [`src/toolManifest.ts`](./src/toolManifest.ts)이며 `toolContract.test.ts`가 등록 목록과 대조합니다. 도구를 추가·삭제하면 매니페스트와 이 표를 함께 고쳐야 합니다.
+
+### 스키마 조회
+
+| Tool | 설명 |
+|---|---|
+| `get_entity` | 엔터티의 컬럼·타입·PK/FK 상세 조회 |
+| `search_entities` | 이름(논리명·물리명)으로 엔터티 검색 |
+| `generate_ddl` | DDL 생성 (PostgreSQL·MySQL·Oracle·MSSQL·SQLite) |
+| `validate_schema` | PK 누락·미연결 FK·비표준 네이밍 점검 |
+| `harvest_schema_semantics` | 물리 테이블에서 논리명·설명·관계를 역공학 추론 |
+| `propose_schema_change` | 스키마 변경 제안 (사용자 승인이 필요한 Draft로 전송) |
+| `get_business_dictionary` | 표준 단어·용어 사전 검색 → 논리명-물리명 매핑 가이드 |
+| `analyze_legacy_sql` | 레거시 SQL을 분석해 등장 테이블의 업무 의미·연관 관계 반환 |
+
+### 의미 계층 · 온톨로지
+
 | Tool | 설명 |
 |---|---|
-| `get_entity` | 엔터티 상세 조회 |
-| `search_entities` | 엔터티 이름 검색 |
-| `generate_ddl` | DDL 생성 (5개 DBMS 지원) |
-| `validate_schema` | 스키마 검증 |
-| `propose_schema_change` | 스키마 변경 제안 (Draft) |
+| `get_project_context` | **업무 용어가 섞인 질문에는 이것을 먼저.** 자연어 질문으로 프로젝트 전체에서 관련 엔터티를 찾는다 |
+| `semantic_search` | 업무 용어로 엔터티·컬럼 검색 (동의어·설명·논리명 매칭, 매칭 유형 반환) |
+| `get_business_context` | 한 엔터티의 업무 의미·동의어·코드값·관계 전체 |
+| `generate_sql` | 한 다이어그램의 물리 스키마만 보고 SQL 작성용 컨텍스트 반환 |
+| `find_join_path` | 두 엔터티 간 최적 JOIN 경로 (BFS 최단 경로 + 중간 테이블·관계명) |
+| `get_project_summary` | 엔터티·관계 수, 주제영역 구성, RDF 트리플 수 등 전체 요약 |
+| `query_ontology` | 온톨로지 그래프에 SPARQL 직접 실행 (고급) |
+| `check_metadata_quality` | 메타데이터 풍부도 분석 + 개선 필요 엔터티 제안 |
 
 ## 환경변수
 
 | 변수 | 설명 | 기본값 |
 |---|---|---|
-| `THINKERD_API_URL` | ThinkERD API URL | `https://app.thinkdata.dev` |
+| `THINKERD_API_URL` | ThinkERD API URL | `https://api.thinkerd.io` |
 | `THINKERD_TOKEN` | Personal Access Token | — |
 
 ## 보안

package/dist/client.d.ts

@@ -48,8 +48,15 @@ export interface DictionaryWord {
     id: string;
     logicalName: string;
     physicalName: string;
+    /**
+     * 사내에서 이 단어를 부르는 다른 말.
+     *
+     * 사용자가 가장 많이 채우는 필드인데 온톨로지 `skos:altLabel`에는 실리지 않으므로,
+     * **이 창구가 사내 표준 어휘가 외부 AI에 닿는 유일한 경로다.**
+     */
+    synonyms?: string[];
+    /** `'classifier'` | `'modifier'` — 컬럼이 아니라 `word_type`의 값이다 */
     classifier?: string;
-    isForbidden?: boolean;
 }
 export declare class ThinkERDClient {
     private readonly baseUrl;
@@ -83,5 +90,15 @@ export declare class ThinkERDClient {
         status: string;
     }>;
     private postRequest;
+    /** 자연어 질문 → 관련 엔터티 컨텍스트 (Graph RAG) */
+    getProjectContext(projectId: string, question: string): Promise<any>;
+    /** 두 엔터티 간 JOIN 경로 탐색 */
+    findJoinPath(projectId: string, from: string, to: string): Promise<any>;
+    /** 프로젝트 전체 스키마 요약 */
+    getProjectSummary(projectId: string): Promise<any>;
+    /** 메타데이터 풍부도 품질 보고 */
+    checkMetadataQuality(projectId: string): Promise<any>;
+    /** SPARQL 직접 실행 */
+    queryOntology(projectId: string, query: string): Promise<any>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}