{"_id":"@10xtf/11st-seller-mcp","name":"@10xtf/11st-seller-mcp","dist-tags":{"latest":"0.0.12"},"versions":{"0.0.12":{"name":"@10xtf/11st-seller-mcp","version":"0.0.12","description":"MCP server exposing 11st (11번가) Seller Open API as 144 individual tools (stdio transport).","license":"Apache-2.0","type":"module","engines":{"node":">=20"},"bin":{"11st-seller-mcp":"bin/11st-seller-mcp.js"},"scripts":{"codegen":"tsx scripts/codegen.ts","build":"npm run codegen && tsup","dev":"tsx src/index.ts","test":"vitest run","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm test","release":"npm version patch &&npm run build && chmod +x bin/11st-seller-mcp.js && npm pack --dry-run && npm publish --access public --tag latest"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","fast-xml-parser":"^4.4.0","iconv-lite":"^0.6.3","zod":"^3.23.0"},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.3.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^2.1.0"},"_id":"@10xtf/11st-seller-mcp@0.0.12","gitHead":"ea69ff7984135ceccdfecd2f6cc1e51cc5308097","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-tordS087hXWC3WMZgF5TbUpsPI3ajEepcxT+3qlDtt9cSGpHr0qGkqgEqTHlovNYWDdxUUepIhyOFRBD10SrLQ==","shasum":"b35b7a3bfe8e0e8702a0b6d2e349a41152b981d0","tarball":"https://registry.npmjs.org/@10xtf/11st-seller-mcp/-/11st-seller-mcp-0.0.12.tgz","fileCount":4,"unpackedSize":747982,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCGFPHQSAi81ZisYt1d/WABOspMYafAW2Ub5FtfHAiA5QIgNnai3ediN+OcqDVzVJuTP2uMCpOcDJJJgOcdMFMGLkA="}]},"_npmUser":{"name":"jutaekim","email":"jutaekim@10xtf.ai"},"directories":{},"maintainers":[{"name":"jutaekim","email":"jutaekim@10xtf.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/11st-seller-mcp_0.0.12_1777537516791_0.4611274270483783"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T08:25:16.667Z","0.0.12":"2026-04-30T08:25:16.946Z","modified":"2026-04-30T08:25:17.125Z"},"maintainers":[{"name":"jutaekim","email":"jutaekim@10xtf.ai"}],"description":"MCP server exposing 11st (11번가) Seller Open API as 144 individual tools (stdio transport).","license":"Apache-2.0","readme":"# @10xtf/11st-seller-mcp\n\n11번가(11st) Seller Open API를 **144개의 개별 MCP 도구**로 노출하는 MCP 서버입니다. stdio 전송 방식을 사용하며, 다양한 AI 코딩 도구(Claude Code, Cursor, Gemini, GitHub Copilot 등)에서 바로 호출할 수 있습니다.\n\n> 도구 이름과 설명(description)은 영문으로 제공되지만, 파라미터 설명과 11st API 응답 페이로드는 한국어 그대로 유지됩니다(11st API 자체가 한국어 우선이기 때문). EUC-KR XML 응답은 UTF-8 JSON으로 자동 디코딩되어 반환됩니다.\n\n---\n\n## 사전 준비\n\n1. **Node.js 20 이상** (`node --version`으로 확인)\n2. **11번가 OpenAPI 키**: [셀러오피스](https://soffice.11st.co.kr/)에서 발급\n3. 환경 변수 `ELEVENST_OPENAPI_KEY` 에 해당 키 지정\n\n설치 방식은 모두 동일하게 `npx -y @10xtf/11st-seller-mcp@latest` 명령을 사용합니다. 글로벌 설치 없이 항상 최신 버전을 받아 실행합니다.\n\n---\n\n## MCP 클라이언트별 설치 방법\n\n### 1. Claude Code\n\nClaude Code는 `claude mcp add` CLI 또는 설정 파일 편집 두 가지 방법을 지원합니다.\n\n#### 방법 A — CLI 사용 (권장)\n\n```bash\nclaude mcp add 11st-seller \\\n  --env ELEVENST_OPENAPI_KEY=여기에_API_키_입력 \\\n  -- npx -y @10xtf/11st-seller-mcp@latest\n```\n\n스코프를 지정하려면 `-s user`(전역) 또는 `-s project`(현재 프로젝트의 `.mcp.json`)를 추가합니다.\n\n```bash\nclaude mcp add 11st-seller -s user \\\n  --env ELEVENST_OPENAPI_KEY=... \\\n  -- npx -y @10xtf/11st-seller-mcp@latest\n```\n\n#### 방법 B — 설정 파일 직접 편집\n\n- 사용자 전역: `~/.claude.json`\n- 프로젝트 단위: 프로젝트 루트의 `.mcp.json`\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"11st-seller\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@10xtf/11st-seller-mcp@latest\"],\n      \"env\": {\n        \"ELEVENST_OPENAPI_KEY\": \"여기에_API_키_입력\"\n      }\n    }\n  }\n}\n```\n\n확인: Claude Code 안에서 `/mcp` 명령으로 등록된 MCP 서버 상태를 볼 수 있습니다.\n\n---\n\n### 2. Cursor\n\nCursor는 `mcp.json` 설정 파일을 사용합니다.\n\n- 사용자 전역: `~/.cursor/mcp.json`\n- 프로젝트 단위: 프로젝트 루트의 `.cursor/mcp.json`\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"11st-seller\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@10xtf/11st-seller-mcp@latest\"],\n      \"env\": {\n        \"ELEVENST_OPENAPI_KEY\": \"여기에_API_키_입력\"\n      }\n    }\n  }\n}\n```\n\n저장 후 **Cursor → Settings → MCP** 패널에서 `11st-seller`가 `green/connected` 상태인지 확인합니다. 도구 목록에서 144개의 도구가 보이면 정상입니다.\n\n---\n\n### 3. Gemini (Gemini CLI / Code Assist)\n\nGemini CLI는 `~/.gemini/settings.json`(전역) 또는 프로젝트의 `.gemini/settings.json`에 MCP 서버를 등록합니다.\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"11st-seller\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@10xtf/11st-seller-mcp@latest\"],\n      \"env\": {\n        \"ELEVENST_OPENAPI_KEY\": \"여기에_API_키_입력\"\n      },\n      \"timeout\": 30000,\n      \"trust\": false\n    }\n  }\n}\n```\n\n설정 후 `gemini` 실행 → `/mcp` 명령으로 서버 상태와 도구 목록을 확인할 수 있습니다.\n\n---\n\n### 4. GitHub Copilot (VS Code의 Copilot Chat — Agent Mode)\n\nGitHub Copilot의 **Agent Mode**는 워크스페이스 단위의 `.vscode/mcp.json` 파일을 통해 MCP 서버를 인식합니다.\n\n프로젝트 루트에 `.vscode/mcp.json` 파일을 생성합니다.\n\n```jsonc\n{\n  \"servers\": {\n    \"11st-seller\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@10xtf/11st-seller-mcp@latest\"],\n      \"env\": {\n        \"ELEVENST_OPENAPI_KEY\": \"여기에_API_키_입력\"\n      }\n    }\n  }\n}\n```\n\n> Copilot 설정 파일은 **`mcpServers`가 아닌 `servers`** 키를 사용한다는 점에 주의하세요. 또한 각 서버마다 `\"type\": \"stdio\"`를 명시해야 합니다.\n\n전역 등록을 원하면 VS Code의 `settings.json`에 다음을 추가합니다.\n\n```jsonc\n{\n  \"github.copilot.chat.mcp.servers\": {\n    \"11st-seller\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@10xtf/11st-seller-mcp@latest\"],\n      \"env\": {\n        \"ELEVENST_OPENAPI_KEY\": \"여기에_API_키_입력\"\n      }\n    }\n  }\n}\n```\n\nVS Code Copilot Chat 패널을 **Agent** 모드로 전환한 뒤 도구 아이콘에서 `11st-seller` 의 144개 도구가 노출되는지 확인합니다.\n\n---\n\n## 환경 변수\n\n| 이름                    | 필수 | 기본값                         | 설명                                                       |\n| ----------------------- | ---- | ------------------------------ | ---------------------------------------------------------- |\n| `ELEVENST_OPENAPI_KEY`  | 예   | —                              | 11번가 OpenAPI 키 (셀러오피스에서 발급).                    |\n| `ELEVENST_API_BASE`     | 아니오 | `https://api.11st.co.kr/rest` | 베이스 URL 오버라이드(프록시/스테이징용).                  |\n| `ELEVENST_TIMEOUT_MS`   | 아니오 | `30000`                        | 요청별 타임아웃(ms).                                       |\n| `MCP_LOG_LEVEL`         | 아니오 | `info`                         | `debug` \\| `info` \\| `warn` \\| `error`. 로그는 stderr 출력.|\n\n---\n\n## 동작 개요\n\n- **Transport**: stdio 전용\n- **Encoding**: 11번가 응답 XML(EUC-KR)을 `iconv-lite`로 디코딩 후 `fast-xml-parser`로 파싱. POST/PUT 본문은 EUC-KR XML로 다시 인코딩.\n- **Validation**: 모든 입력은 `zod` 스키마로 검증되며, 실패 시 `isError: true` 와 함께 사람이 읽을 수 있는 메시지를 반환.\n- **Errors**: 11번가의 `result_code`(`0`=결과 없음, `2`=조회 범위 초과, `1000`=점검 등)를 메시지로 매핑. HTTP 401/403 발생 시 API 키 점검 힌트 출력.\n- **Retry**: HTTP 429 / 5xx / 네트워크 오류는 500ms 후 1회 자동 재시도(요청당 최대 1회).\n\n---\n\n## 도구 이름 규칙\n\n도구 이름은 11번가 REST URL을 기반으로 `domain_action` 형식의 snake_case 로 생성됩니다.\n\n| 11st URL                                           | Method | Tool name                    |\n| -------------------------------------------------- | ------ | ---------------------------- |\n| `/cateservice/category`                            | GET    | `cate_category`              |\n| `/prodmarketservice/prodmarket/stocks`             | POST   | `prodmarket_stocks`          |\n| `/settlement/settlementList/[startTime]/[endTime]` | GET    | `settlement_settlement_list` |\n| `/ordservices/complete/[ordNo]`                    | GET    | `ord_complete`               |\n\n이름·설명 오버라이드는 [`scripts/name-map.ts`](scripts/name-map.ts) (apiSeq → metadata) 와 [`src/tools/overrides`](src/tools/overrides) 에서 관리합니다. 수정 후에는 `npm run codegen` 을 실행해야 합니다.\n\n---\n\n## 개발\n\n```bash\nnpm install\nnpm run codegen   # docs/11st_api_doc/*.md → src/tools/generated/*.ts\nnpm run typecheck\nnpm test          # vitest\nnpm run dev       # tsx src/index.ts\nnpm run build     # tsup → bin/11st-seller-mcp.js\n```\n\n로컬 패키지로 e2e 스모크 테스트를 하려면:\n\n```bash\nnpm pack\nELEVENST_OPENAPI_KEY=... npx ./10xtf-11st-seller-mcp-0.0.1.tgz\n```\n\n---\n\n## 트러블슈팅\n\n| 증상                                         | 원인 / 해결                                                                                       |\n| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| 도구 목록이 비어 있음                        | API 키 미설정 또는 stdout에 로그가 섞여 들어가는 경우. `MCP_LOG_LEVEL=debug` 로 stderr 확인.       |\n| `HTTP 401` / `HTTP 403`                      | `ELEVENST_OPENAPI_KEY` 가 잘못되었거나 만료. 셀러오피스에서 키 재발급.                              |\n| `result_code: 1000`                          | 11번가 점검 시간. 잠시 후 재시도.                                                                  |\n| Copilot에서 서버가 안 보임                   | `mcp.json` 의 키가 `mcpServers` 가 아닌 `servers` 인지 확인. `\"type\": \"stdio\"` 누락 여부 확인.    |\n| `npx` 실행 지연                              | 처음 1회는 패키지를 받아오느라 느릴 수 있음. CI 등에서는 `npm i -g @10xtf/11st-seller-mcp@latest` 후 `command: 11st-seller-mcp` 사용 권장. |\n\n---\n\n## License\n\nApache-2.0. [LICENSE](LICENSE) 참고.\n","readmeFilename":"README.md","_rev":"1-8ad994dc53310f2813d3f22f476cdc06"}