@keke1933/vibe-dictionary-mcp 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +109 -23
  2. package/dist/index.js +9574 -1127
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -6,57 +6,143 @@
6
6
 
7
7
  | 도구 | 입력 | 결과 |
8
8
  | --- | --- | --- |
9
- | `search_techniques` | 선택 사항: `query`, `domain`, `category`, `limit`, `offset` | 기법 ID·이름·분류·요약과 페이지 정보 |
10
- | `get_technique` | 필수: `id` | 기법 상세·키워드·`promptSnippet` 원문 |
9
+ | `search_techniques` | 선택: `query`, `domain`, `category`, `target`, `trigger`, `locale`, `limit`, `offset` | 요약·사용 상황·검색 근거·점수·페이지 정보 |
10
+ | `get_technique` | 필수: `id`, 선택: `locale` | 기법 상세·별칭·키워드·해당 언어의 `promptSnippet` 원문 |
11
11
 
12
- `query`를 생략하면 전체 목록을 조회한다. 공백으로 나눈 검색어를 모두 포함하는 항목을 찾으며, 영문 대소문자를 구분하지 않는다. 검색 대상은 한·영 이름, 효과 태그, 키워드, 요약과 프롬프트다. 문장 의미를 추론하는 검색은 아니므로 `마그네틱`, `magnetic`, `카드`, `SVG`처럼 짧은 검색어를 사용한다.
12
+ 두 도구의 `locale`은 `ko`(기본) 또는 `en`이다. 이름·요약·태그·사용 상황·프롬프트를 선택 언어로 반환하며, 호환성을 위해 `titleKo`·`titleEn`은 두 이름을 유지한다. 검색 언어는 출력 언어와 독립적이므로 한국어로 검색한 뒤 영어 프롬프트를 받을 수 있다.
13
13
 
14
- 도메인은 `ui`(UI), `motion`(그래픽), `layout`(레이아웃), `style`(스타일), `video`(모션 영상)다. 카테고리 ID는 도구의 입력 스키마와 검색 결과에서 확인한다. 도메인·카테고리 필터를 함께 지정하면 둘 다 만족해야 한다. 검색 결과는 카탈로그 순서이며 관련도 순위는 제공하지 않는다.
14
+ 검색은 한영 이름·별칭·효과 키워드·사용 상황·요약·프롬프트를 대상으로 한다. 대소문자를 구분하지 않으며, 동의어를 연결하고 이름·별칭·사용 상황을 본문보다 우선한다. 모든 단어의 일치를 요구하지 않고 검색어 충족 비율로 후보를 좁힌다. `마그네틱`, `mouse tilt card`, `클릭한 곳에서 물결 퍼지는 버튼`처럼 구체적인 효과와 대상을 사용한다. 의미를 추론하는 AI 검색은 아니므로 모호한 문장은 핵심 단어로 바꾸고, 상위 후보의 요약·사용 상황을 비교한다.
15
15
 
16
- 검색 결과의 `total`은 필터와 검색 조건에 맞는 전체 개수다. 기본 페이지 크기는 20, 최대는 50이며 `nextOffset`을 다음 요청의 `offset`으로 보내면 이어서 조회한다. `nextOffset: null`이면 마지막 페이지다. 일치 항목이 없으면 빈 목록을 반환한다. 잘못된 입력과 존재하지 않는 상세 ID는 MCP 오류 결과를 반환한다.
16
+ 도메인은 `ui`(UI), `motion`(그래픽), `layout`(레이아웃), `style`(스타일), `video`(모션 영상)다. 카테고리·대상·입력 ID는 도구 스키마에서 확인한다. 모든 필터는 함께 만족해야 한다. `target: "button"`, `trigger: "pointer-move"`처럼 필수 조건만 지정한다. 제목에 scroll/drag/audio가 있어도 실제 데모는 클릭·타이머 시연일 수 있으므로 `triggers`와 원문을 확인한다.
17
17
 
18
- 검색 결과에는 프롬프트 전문을 넣지 않는다. 선택한 기법을 `get_technique`로 조회하면 웹과 같은 원문을 받을 수 있다. MCP 자체는 조합·클립보드 접근·프로젝트 파일 수정·UI 생성·외부 API 호출을 수행하지 않는다. 구현은 연결한 코딩 에이전트가 사용자 요청에 따라 수행한다.
18
+ 검색어가 있으면 관련도순이며 `score`는 정렬용 수치로 적합성 확률이 아니다. `matchedOn`은 일치한 필드명(`title`, `alias`, `keyword`, `useCase`, `target`, `trigger`, `summary`, `prompt`)이다. `query`를 생략하면 카탈로그 순서로 목록을 조회한다. 일치가 없으면 빈 목록을 반환한다.
19
19
 
20
- ## 현재 연결 방법
20
+ `total`은 전체 일치 개수다. 기본 페이지 크기는 20, 최대 50이며 처음 후보를 좁힐 때는 `limit: 5`를 권장한다. `nextOffset`을 다음 요청의 `offset`으로 보내 이어서 조회한다. `nextOffset: null`이면 마지막 페이지다. 잘못된 입력과 존재하지 않는 상세 ID는 MCP 오류 결과를 반환한다.
21
21
 
22
- npm 이름은 `@keke1933/vibe-dictionary-mcp`다. npm 공개 게시와 Trusted Publisher 설정은 별도로 완료해야 한다. 게시 전에는 저장소에서 다음 명령으로 로컬 빌드를 사용한다.
22
+ 검색 결과에는 프롬프트 전문을 넣지 않는다. 선택한 ID를 `get_technique`로 조회하면 웹과 같은 언어의 원문을 받는다. MCP는 조합·클립보드·파일 수정·UI 생성·외부 API 호출을 수행하지 않는다.
23
+
24
+ ### English usage
25
+
26
+ Search with concrete effect words or a use case, compare a few summaries, then retrieve only the selected prompt:
27
+
28
+ ```json
29
+ {"query":"a button that follows the mouse cursor","target":"button","trigger":"pointer-move","locale":"en","limit":5}
30
+ ```
31
+
32
+ Then call `get_technique`:
33
+
34
+ ```json
35
+ {"id":"magnetic-hover","locale":"en"}
36
+ ```
37
+
38
+ Search matches both Korean and English regardless of output locale. Scores indicate relative ranking, not confidence. Unknown or unsuitable results require reformulating the query or clarifying the request. Tools return reference text only and never modify your project.
39
+
40
+ These capabilities describe the current source. An installed, pinned npm version does not automatically pick up local source changes. For local verification, build the repository and register `node <repository>/apps/mcp/dist/index.js` with your MCP client, then restart that server.
41
+
42
+ ## npm 패키지로 Codex에 연결
43
+
44
+ 공개 패키지는 [@keke1933/vibe-dictionary-mcp](https://www.npmjs.com/package/@keke1933/vibe-dictionary-mcp)다. 저장소 복제·로컬 빌드·웹 서버 실행 없이 사용할 수 있다. Node.js 22.12 이상과 npm, `codex` CLI를 먼저 설치하고 터미널에서 다음 명령이 동작하는지 확인한다. MCP 자체에는 API 키나 npm 로그인이 필요 없다. Codex는 별도로 사용할 수 있도록 설정되어 있어야 한다.
23
45
 
24
46
  ```sh
25
- npm ci
26
- npm run build:mcp
47
+ node --version
48
+ npm --version
49
+ codex --version
27
50
  ```
28
51
 
29
- Codex에는 빌드 결과의 **실제 절대 경로**로 등록한다. 아래 자리표시자는 자신의 경로로 바꾼다. `node`가 Codex의 PATH에 없다면 Node 실행 파일도 절대 경로로 지정한다.
52
+ ### 1. npx로 등록하기
53
+
54
+ **macOS / Linux**
55
+
56
+ ```sh
57
+ codex mcp add vibe-dictionary -- npx -y --registry=https://registry.npmjs.org/ @keke1933/vibe-dictionary-mcp@0.1.2
58
+ ```
59
+
60
+ **Windows (PowerShell)**
61
+
62
+ ```powershell
63
+ codex mcp add vibe-dictionary -- cmd /d /c npx -y --registry=https://registry.npmjs.org/ @keke1933/vibe-dictionary-mcp@0.1.2
64
+ ```
65
+
66
+ `npx`가 지정한 패키지를 npm 캐시에 설치해 실행한다. `-y`는 다운로드 확인 질문에 자동 동의하는 옵션이다. 별도 전역 패키지 설치는 필요 없으며, 프로젝트의 `package.json`에도 의존성을 추가하지 않는다. Windows는 `.cmd`를 실행할 수 있도록 `cmd /d /c`로 감싼다. `/d`는 cmd의 AutoRun 명령을 사용하지 않게 한다.
67
+
68
+ 명령은 Codex의 **사용자 전역 MCP 설정**을 등록하므로 다른 프로젝트에서도 사용할 수 있다. 기본 파일은 `~/.codex/config.toml`이고, Windows는 `%USERPROFILE%\.codex\config.toml`이다. `CODEX_HOME`이 설정되어 있으면 그 폴더의 `config.toml`을 사용한다. 기존 `vibe-dictionary` 등록이 있다면 실행 명령이 갱신된다.
69
+
70
+ ### 2. 연결과 실제 도구 호출 확인하기
30
71
 
31
72
  ```sh
32
- codex mcp add vibe-dictionary -- node "/absolute/path/to/vibe-dictionary/apps/mcp/dist/index.js"
33
73
  codex mcp get vibe-dictionary
34
74
  ```
35
75
 
36
- 현재 사용 중인 Codex 세션에 도구가 나타나지 않으면 앱의 MCP 서버 재시작 기능을 사용하거나 새 세션에서 확인한다. 다음과 같이 요청하고 실제 도구 호출과 반환된 `promptSnippet`을 확인한다.
76
+ 실행 인수에 `@keke1933/vibe-dictionary-mcp@0.1.2`이 있고 등록이 활성화되었는지 확인한다. 이 명령은 설정을 보여줄 뿐 서버의 실제 연결 성공을 보장하지는 않는다. 앱의 MCP 서버를 재시작하거나 새 Codex 세션에서 다음과 같이 요청한다.
37
77
 
38
78
  > vibe-dictionary MCP에서 마그네틱 기법을 검색한 뒤 magnetic-hover의 프롬프트 원문을 가져와 줘. 코드는 수정하지 마.
39
79
 
40
- 다른 MCP 클라이언트도 `stdio` 서버로 등록하고 명령을 `node`, 인수를 같은 빌드 파일의 절대 경로로 지정하면 된다. 설정 형식은 클라이언트별로 다르다. 표준 출력은 MCP 통신 전용이므로 등록 명령을 `npm run start`로 감싸지 않는다.
80
+ 실제 `search_techniques` 호출에 `magnetic-hover`가 반환되고, 이어지는 `get_technique` 호출에 `promptSnippet` 원문이 포함되면 정상이다. 터미널 Codex에서는 `/mcp`로 활성 MCP 목록도 확인할 수 있다.
41
81
 
42
- ## 데이터와 배포
82
+ ### config.toml을 직접 작성하는 경우
43
83
 
44
- 기법 데이터와 검색 함수는 내부 패키지 `@vibe-dictionary/catalog`로 웹과 공유하며 빌드 시 실행 파일에 포함된다. 카탈로그는 빌드 전용 의존성이므로 사용자 설치 시 별도로 가져오지 않는다. 실행 중에는 웹 접속·API 키·네트워크 연결이 필요 없다. 패키지 다운로드와 의존성 설치 시에는 네트워크가 필요하다. 카탈로그 변경은 재빌드하고 MCP 프로세스를 재시작해야 반영된다. npm 배포 이후에는 새 패키지 버전도 게시해야 한다.
84
+ CLI 등록 대신 아래 설정을 같은 파일의 기존 내용과 합칠 수 있다. 같은 이름의 테이블을 중복으로 만들지 않는다.
45
85
 
46
- 저장소에서 `npm test`는 웹 회귀 테스트와 빌드된 MCP의 실제 stdio 연결 테스트를 함께 실행한다. `npm run build`는 웹과 MCP 전체 빌드, `npm run build:web`은 웹만, `npm run build:mcp`는 MCP만 빌드한다.
86
+ **macOS / Linux**
47
87
 
48
- 저장소 루트에서 다음 명령으로 배포 파일을 검증할 수 있다. 실행 파일·이 문서·LICENSE·패키지 메타데이터 4개만 포함하는지 검사하고, tarball을 임시 경로에 설치해 도구 목록과 모든 기법·프롬프트 원문을 대조한다. 설치에는 npm 레지스트리 연결이 필요하다. 최종 tarball 경로를 출력하며, 임시 설치 폴더는 정리한다.
88
+ ```toml
89
+ [mcp_servers.vibe-dictionary]
90
+ command = "npx"
91
+ args = ["-y", "--registry=https://registry.npmjs.org/", "@keke1933/vibe-dictionary-mcp@0.1.2"]
92
+ ```
93
+
94
+ **Windows**
95
+
96
+ ```toml
97
+ [mcp_servers.vibe-dictionary]
98
+ command = "cmd"
99
+ args = ["/d", "/c", "npx", "-y", "--registry=https://registry.npmjs.org/", "@keke1933/vibe-dictionary-mcp@0.1.2"]
100
+ ```
101
+
102
+ 다른 MCP 클라이언트도 `stdio` 전송 방식으로 위 `command`와 `args`를 등록하면 된다. 클라이언트마다 설정 형식은 다르다.
103
+
104
+ ### 선택 사항: npm 전역 설치 후 연결
105
+
106
+ 실행 파일을 직접 설치해 관리하고 싶다면 `npx` 방식 대신 전역 설치를 사용할 수 있다. 다음 명령으로 패키지를 설치한다.
107
+
108
+ ```sh
109
+ npm install --global @keke1933/vibe-dictionary-mcp@0.1.2 --registry=https://registry.npmjs.org/
110
+ ```
111
+
112
+ 설치 후 **macOS / Linux**에서는 다음과 같이 등록한다.
49
113
 
50
114
  ```sh
51
- npm run check:package
115
+ codex mcp add vibe-dictionary -- vibe-dictionary-mcp
52
116
  ```
53
117
 
54
- 공개 게시가 완료된 버전은 MCP 클라이언트에서 `npx` 실행 파일과 `-y`, `@keke1933/vibe-dictionary-mcp@<게시된 버전>` 인수로 실행할 수 있다. 예를 들어 터미널 실행 명령은 `npx -y @keke1933/vibe-dictionary-mcp@0.1.0`이다. 실제 게시 전에는 이 명령으로 패키지를 받을 수 없다. 클라이언트의 실행 파일 검색 방식과 Windows의 `.cmd` 처리에 맞춰 설정한다.
118
+ **Windows (PowerShell)**에서는 다음과 같이 등록한다.
119
+
120
+ ```powershell
121
+ codex mcp add vibe-dictionary -- cmd /d /c vibe-dictionary-mcp
122
+ ```
123
+
124
+ npm 전역 실행 파일 폴더가 Codex의 `PATH`에 있어야 한다. `npx` 등록과 전역 설치 등록 중 하나만 사용하며, 같은 이름으로 등록하면 실행 방식이 갱신된다.
125
+
126
+ ### 버전 변경과 연결 해제
127
+
128
+ 예제는 재현 가능한 실행을 위해 버전을 `0.1.2`로 고정한다. 새 버전을 사용하려면 원하는 버전이 npm에 공개되었는지 확인한 후 등록 명령의 버전을 바꿔 다시 실행하고 MCP를 재시작한다. 전역 설치 방식은 `npm install --global`의 버전을 바꿔 재설치한다. 새 버전 게시만으로 기존 설정의 버전이 자동으로 바뀌지는 않는다.
129
+
130
+ ```sh
131
+ codex mcp remove vibe-dictionary
132
+ ```
133
+
134
+ 위 명령은 Codex 연결 설정을 제거한다. 선택 사항으로 전역 설치했던 패키지까지 제거하려면 `npm uninstall --global @keke1933/vibe-dictionary-mcp`를 실행한다.
135
+
136
+ ### 연결이 안 될 때
55
137
 
56
- 저장소 관리자는 GitHub Actions의 `Publish MCP to npm`을 `master`에서 수동 실행한다. 입력한 버전은 이미 커밋된 MCP 버전과 같아야 하며, GitHub `npm` environment와 npm Trusted Publisher를 사전에 설정한다. 최초 1회 패키지 생성·2FA 게시와 설정값은 저장소의 `docs/npm-publishing.md`를 참고한다. npm 토큰을 GitHub Secrets에 추가할 필요는 없다.
138
+ - `node`, `npm`, `npx`를 찾지 못하면 Node.js 설치와 `PATH`를 확인하고 Codex 앱을 다시 시작한다. 버전 관리자나 사용자 지정 설치 경로를 사용한다면 Codex도 해당 실행 파일을 찾을 수 있어야 한다.
139
+ - Windows에서 실행 형식 오류가 나면 위 `cmd /d /c` 설정을 사용한다. PowerShell이 `npm.ps1` 실행을 막는 경우 설치·버전 확인 명령은 `npm.cmd`로 실행할 수 있다.
140
+ - 최초 다운로드가 기본 시작 제한인 10초를 넘으면 `[mcp_servers.vibe-dictionary]` 아래에 `startup_timeout_sec = 60`을 추가하고 재시작한다. 설정 파일 전체를 덮어쓰지 않는다.
141
+ - 다운로드 오류나 `E404`가 나면 npm 레지스트리 접근과 지정 버전의 공개 여부를 확인한다. 패키지 설치·확인 과정은 네트워크를 사용할 수 있지만, 실행된 MCP의 검색·조회는 외부 API를 호출하지 않는다.
142
+ - 터미널에서 MCP만 직접 실행했을 때 출력 없이 대기하는 것은 stdio 요청을 기다리는 동작이다. 실제 연결 확인은 Codex의 도구 호출로 진행한다.
57
143
 
58
144
  ## 라이선스
59
145
 
60
- MCP 코드와 번들에 포함된 기법 데이터·프롬프트는 [MIT License](LICENSE)를 따른다. 제3자 의존성은 각각의 라이선스를 따른다.
146
+ 이 패키지의 코드·기법·프롬프트는 [MIT License](LICENSE)를 따른다. 제3자 의존성은 각각의 라이선스를 따른다.
61
147
 
62
- 연결 방식의 근거: [MCP 공식 SDK](https://ts.sdk.modelcontextprotocol.io/server), [Codex 공식 MCP 문서](https://developers.openai.com/codex/mcp).
148
+ 연결 방식의 근거: [Codex 공식 MCP 문서](https://developers.openai.com/codex/mcp), [npm npx 문서](https://docs.npmjs.com/cli/v11/commands/npx/), [npm 전역 설치 문서](https://docs.npmjs.com/downloading-and-installing-packages-globally/).