diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 025fd7c..449cd0b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,20 +30,3 @@ jobs: run: npm run check:public - name: Package check run: npm pack --dry-run - - english-commits: - name: English-only commits - if: github.event_name == 'pull_request' - runs-on: ubuntu-latest - steps: - - name: Check out source - uses: actions/checkout@v5 - with: - fetch-depth: 0 - - name: Check commit messages are written in English - run: | - if git log --format='%s %b' "origin/${GITHUB_BASE_REF}..HEAD" \ - | grep -P '[\x{1100}-\x{11FF}\x{3130}-\x{318F}\x{AC00}-\x{D7A3}]'; then - echo "Commit messages in this repository must be written in English." - exit 1 - fi diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4ae996c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,14 @@ +# CRM 작업 지침 + +## MCP 설치 권한 정책 + +- 모든 MCP 설치는 서버가 지원하는 전체 권한을 한 번에 요청합니다. +- Meta·CRM 등 일부 기능의 권한 목록을 설치 명령에 고정하지 않습니다. +- 너드보드 공통 설치 패키지는 `@nerdlab-dev/meta-ads-mcp`입니다. CRM도 같은 패키지를 사용합니다. +- 기존 제한 권한 연결은 전체 권한으로 재로그인합니다. 기존 토큰을 임의로 확장하지 않습니다. +- 전체 권한 요청과 별개로 서버의 실시간 계정·몰·구독 권한 검사와 도구 하드게이트는 유지합니다. + +## GitHub 작성 언어 + +- 커밋 메시지와 PR 제목·본문은 한국어로 작성합니다. +- PR 본문은 짧은 해요체 문장과 개조식으로 작성합니다. diff --git a/README.md b/README.md index 0ac6061..cafca7b 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ **CRM 캠페인 세팅, AI 자동화로 5분 안에 끝내보세요.** -[](https://www.npmjs.com/package/@nerdlab-dev/crm-mcp) -[](https://www.npmjs.com/package/@nerdlab-dev/crm-mcp) +[](https://www.npmjs.com/package/@nerdlab-dev/meta-ads-mcp) +[](https://www.npmjs.com/package/@nerdlab-dev/meta-ads-mcp) [](https://github.com/nerdlab-dev/crm/actions/workflows/ci.yml) -[](https://nodejs.org) +[](https://nodejs.org) [](./LICENSE) [](https://claude.com/claude-code) @@ -20,7 +20,7 @@ CRM 캠페인 하나를 보내려면 세그먼트·쿠폰·메시지를 관리자 화면에서 일일이 클릭해야 해요. 너드보드의 호스팅 원격 MCP를 연결하면 AI 에이전트가 대신 해줘요 — **서버 설치도, 내 컴퓨터에 API 키를 둘 일도 없어요**. -이 저장소는 얇은 MIT 라이선스 설치기예요. 모든 CRM 기능은 너드보드가 운영하는 서버에서 실행돼요. +이 저장소는 CRM 사용 안내를 제공해요. 설치는 광고·CRM 공통 패키지 `@nerdlab-dev/meta-ads-mcp`로 진행해요. 모든 CRM 기능은 너드보드 서버에서 실행돼요. 별도 CRM npm 패키지는 설치하거나 배포하지 않아요. ## 무엇을 할 수 있나요 @@ -37,14 +37,14 @@ CRM 캠페인 하나를 보내려면 세그먼트·쿠폰·메시지를 관리 **Node.js 20+**와 **Claude Code** 또는 **Codex CLI**가 필요해요. 설정은 2분이면 끝나요. ```bash -npx -y @nerdlab-dev/crm-mcp@latest install +npx -y @nerdlab-dev/meta-ads-mcp@latest install ``` 두 클라이언트가 모두 설치되어 있다면 하나를 골라 주세요: ```bash -npx -y @nerdlab-dev/crm-mcp@latest install --client claude -npx -y @nerdlab-dev/crm-mcp@latest install --client codex +npx -y @nerdlab-dev/meta-ads-mcp@latest install --client claude +npx -y @nerdlab-dev/meta-ads-mcp@latest install --client codex ``` 그다음 로그인하세요: @@ -53,15 +53,33 @@ npx -y @nerdlab-dev/crm-mcp@latest install --client codex - **Codex CLI** — 아래를 실행해요: ```bash - codex mcp login \ - --scopes crm:segment:read,crm:segment:write,crm:coupon:read,crm:coupon:write,crm:campaign:read,crm:campaign:write,crm:campaign:send,crm:strategy:read,ad-asset:read,ad-asset:write \ - nerdboard-crm + codex mcp login nerdboard-meta-ads ``` -로그인 과정에서 너드보드 워크스페이스와 권한을 직접 고를 수 있어요. 구독이나 쇼핑몰 연동이 아직 없다면 너드보드가 화면에서 안내해 줘요. +로그인 과정에서 너드보드 워크스페이스를 고르고 광고·CRM·소재 전체 권한을 한 번에 승인해요. 구독이나 쇼핑몰 연동이 아직 없다면 너드보드가 화면에서 안내해 줘요. 이게 전부예요 — 이제 에이전트에게 캠페인을 부탁해 보세요. +## 전체 권한 연결 + +이미 배포된 공통 패키지를 그대로 사용해요. 기존 버전이 출력하는 `--scopes` 포함 로그인 예시 대신, 위의 `codex mcp login nerdboard-meta-ads` 명령을 사용해요. 일부 기능으로 권한을 제한하지 않아요. + +Meta 광고와 CRM은 같은 MCP 서버를 사용해요. 기본 로그인은 서버가 지원하는 광고·CRM·소재 전체 권한을 한 번에 요청해요. 설치 명령에 일부 권한을 고정하지 않아요. 실제 작업에는 계정·몰·구독 권한 검사가 적용돼요. + +기존에 일부 권한만 승인했다면 아래 명령으로 다시 로그인해요. + +```bash +codex mcp logout nerdboard-meta-ads +codex mcp login nerdboard-meta-ads +``` + +Claude Code는 `/mcp`에서 재인증해요. `invalid_scope` 오류가 계속되면 기존 OAuth 클라이언트 등록정보가 남아 있는 상태예요. 기존 연결 주소를 확인한 뒤 연결을 제거하고 아래 공통 설치 명령으로 재등록해요. Claude Code는 `/mcp`의 인증 초기화도 함께 진행해요. + +```bash +npx -y @nerdlab-dev/meta-ads-mcp@latest install +``` + 기존 `nerdboard-crm` 연결이 있다면 같은 서버를 가리키는 공통 연결을 사용하고, 기존 설정을 자동 삭제하지 않아요. + ## 동작 방식 ```mermaid @@ -71,14 +89,14 @@ flowchart LR server -- "카페24 API + 카카오 브랜드메시지" --> store["내 쇼핑몰 · 고객"] ``` -설치기는 각 제품의 공식 `mcp add` 명령으로 MCP 클라이언트에 `nerdboard-crm`을 등록해요. 모든 CRM 동작은 너드보드가 운영하는 서버에서 실행되고, 서버가 카페24 쇼핑몰과 카카오 브랜드메시지 채널을 대신 다뤄요. 사용하려면 너드보드 계정, 활성 구독, 연동된 카페24 쇼핑몰이 필요해요. +설치기는 각 제품의 공식 `mcp add` 명령으로 MCP 클라이언트에 `nerdboard-meta-ads`을 등록해요. 모든 CRM 동작은 너드보드가 운영하는 서버에서 실행되고, 서버가 카페24 쇼핑몰과 카카오 브랜드메시지 채널을 대신 다뤄요. 사용하려면 너드보드 계정, 활성 구독, 연동된 카페24 쇼핑몰이 필요해요. ## 보안과 투명성 설치기가 하는 일: - Codex CLI와 Claude Code가 설치되어 있는지 확인해요. -- `nerdboard-crm` 연결이 이미 있는지 확인해요. +- `nerdboard-meta-ads` 연결이 이미 있는지 확인해요. - 제품의 공식 `mcp add` 명령으로 연결을 등록해요. - 같은 연결이 이미 있으면 아무것도 건드리지 않아요. - 같은 이름이 다른 URL을 가리키면 덮어쓰지 않고 거부해요. @@ -99,13 +117,13 @@ flowchart LR Claude Code: ```bash -claude mcp add --transport http --scope user nerdboard-crm https://nerdboard.kr/mcp +claude mcp add --transport http --scope user nerdboard-meta-ads https://nerdboard.kr/mcp ``` Codex CLI: ```bash -codex mcp add nerdboard-crm --url https://nerdboard.kr/mcp +codex mcp add nerdboard-meta-ads --url https://nerdboard.kr/mcp ``` 원격 MCP를 지원하는 다른 클라이언트(Cursor 등)는 URL을 직접 등록하면 돼요: @@ -125,7 +143,7 @@ npm pack --dry-run ## 라이선스 -이 저장소의 CLI 소스는 [MIT 라이선스](./LICENSE)예요. 너드보드 서비스와 원격 MCP 서버는 별도의 서비스 약관을 따라요. +기존 CRM CLI 소스는 공통 설치 패키지 실행만 위임해요. 이 소스는 [MIT 라이선스](./LICENSE)예요. 너드보드 서비스와 원격 MCP 서버는 별도의 서비스 약관을 따라요. ## 상표 @@ -134,3 +152,14 @@ OpenAI와 Codex는 OpenAI의 상표예요. Claude와 Claude Code는 Anthropic, P ---
너드보드가 만들었어요
+ +## npm 설치가 실패할 때 + +CRM도 `@nerdlab-dev/meta-ads-mcp`를 설치해요. 별도 `@nerdlab-dev/crm-mcp` 패키지는 사용하지 않아요. 공통 npm 패키지를 받을 수 없는 환경에서는 같은 공개 저장소로 설치할 수 있어요. Git이 설치되어 있어야 해요. + +```bash +npx -y github:nerdlab-dev/meta-ads-mcp install --client codex +# Claude Code를 사용하면 마지막 인자를 claude로 바꿔 주세요. +``` + +npm 없이 직접 연결하려면 위의 수동 설치 명령을 사용해요. 어느 방식이든 같은 서버에서 전체 권한을 한 번에 요청해요. diff --git a/package.json b/package.json index f342768..e4b5f02 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@nerdlab-dev/crm-mcp", "version": "0.1.0", - "description": "Installer for Nerdboard's CRM remote MCP — run CRM campaigns for your Cafe24 store from Claude Code and Codex CLI", + "description": "너드보드 CRM 안내와 @nerdlab-dev/meta-ads-mcp 공통 설치기 연결", "keywords": [ "mcp", "crm", @@ -37,9 +37,6 @@ "engines": { "node": ">=20" }, - "publishConfig": { - "access": "public", - "provenance": true - }, - "license": "MIT" + "license": "MIT", + "private": true } diff --git a/scripts/check-public-content.js b/scripts/check-public-content.js index facb047..2a44dff 100644 --- a/scripts/check-public-content.js +++ b/scripts/check-public-content.js @@ -4,6 +4,7 @@ import { join } from "node:path"; import { pathToFileURL } from "node:url"; const ALLOWED_FILES = new Set([ + "AGENTS.md", ".github/assets/demo.gif", ".github/assets/header.svg", ".github/workflows/ci.yml", diff --git a/src/cli.js b/src/cli.js index e682364..e6d0015 100644 --- a/src/cli.js +++ b/src/cli.js @@ -3,7 +3,10 @@ import { createRequire } from "node:module"; const require = createRequire(import.meta.url); const { version } = require("../package.json"); -const HELP = `Nerdboard CRM MCP installer +const HELP = `Nerdboard CRM MCP 공통 설치기 연결 + +권장 설치: npx -y @nerdlab-dev/meta-ads-mcp@latest install +광고·CRM·소재 전체 권한을 한 번에 요청합니다. Usage: nerdboard-crm-mcp install [--client codex|claude] diff --git a/src/install.js b/src/install.js index 2ec4f27..8ecedeb 100644 --- a/src/install.js +++ b/src/install.js @@ -1,126 +1,21 @@ import { spawnSync } from "node:child_process"; -const CLIENTS = ["codex", "claude"]; -const SERVER_NAME = "nerdboard-crm"; -const REMOTE_URL = "https://nerdboard.kr/mcp"; -const CRM_SCOPES = [ - "crm:segment:read", - "crm:segment:write", - "crm:coupon:read", - "crm:coupon:write", - "crm:campaign:read", - "crm:campaign:write", - "crm:campaign:send", - "crm:strategy:read", - "ad-asset:read", - "ad-asset:write", -].join(","); - -const COMMANDS = { - codex: { - get: ["mcp", "get", SERVER_NAME], - add: ["mcp", "add", SERVER_NAME, "--url", REMOTE_URL], - login: `codex mcp login --scopes ${CRM_SCOPES} ${SERVER_NAME}`, - }, - claude: { - get: ["mcp", "get", SERVER_NAME], - add: [ - "mcp", - "add", - "--transport", - "http", - "--scope", - "user", - SERVER_NAME, - REMOTE_URL, - ], - login: "Run /mcp inside Claude Code and sign in with your browser.", - }, -}; - -function runCommand(command, args) { - const result = spawnSync(command, args, { encoding: "utf8" }); - return { - status: result.status, - stdout: result.stdout ?? "", - stderr: result.stderr || result.error?.message || "", - }; -} - -export function detectClients(runner) { - return CLIENTS.filter((client) => { - const result = runner(client, ["--version"]); - return result.status === 0; - }); -} - -export function selectClient(requestedClient, detectedClients) { - if (requestedClient) { - if (detectedClients.includes(requestedClient)) { - return { client: requestedClient }; - } - - return { - error: `Could not find the ${requestedClient} CLI. Please check that it is installed.`, - }; - } - - if (detectedClients.length === 1) { - return { client: detectedClients[0] }; - } - - if (detectedClients.length === 0) { - return { - error: - "Could not find Codex CLI or Claude Code. Please use the manual install steps in the README.", - }; - } - - return { - error: - "Both Codex CLI and Claude Code are installed. Please pass --client codex or --client claude.", - }; -} - -export function installMcp({ - requestedClient = null, - runner = runCommand, -} = {}) { - const selected = selectClient(requestedClient, detectClients(runner)); - if (selected.error) { - return { ok: false, message: selected.error }; - } - - const client = selected.client; - const commands = COMMANDS[client]; - const current = runner(client, commands.get); - - if (current.status === 0) { - if (current.stdout.includes(REMOTE_URL)) { - return { - ok: true, - message: `Nerdboard CRM MCP is already connected to ${client}.\n${commands.login}`, - }; - } - - return { - ok: false, - message: `The name ${SERVER_NAME} is registered with a different URL. Your existing configuration was left unchanged.`, - }; +// CRM도 공통 설치기를 사용한다. 연결 이름과 전체 권한 정책을 복제하지 않는다. +export function installMcp({ requestedClient = null, runner = spawnSync } = {}) { + if (requestedClient !== null && !["codex", "claude"].includes(requestedClient)) { + return { ok: false, message: "클라이언트는 codex 또는 claude여야 합니다." }; } - const added = runner(client, commands.add); - if (added.status !== 0) { - const exitCode = added.status ?? "unknown"; - const detail = added.stderr.trim() || "No error message was provided."; - return { - ok: false, - message: `The MCP add command failed. Exit code ${exitCode}: ${detail}`, - }; - } + const result = runner("npx", [ + "-y", + "@nerdlab-dev/meta-ads-mcp@latest", + "install", + ...(requestedClient ? ["--client", requestedClient] : []), + ], { encoding: "utf8" }); return { - ok: true, - message: `Connected Nerdboard CRM MCP to ${client}.\n${commands.login}`, + ok: result.status === 0, + message: [result.stdout, result.stderr, result.error?.message] + .filter(Boolean).join("\n").trim() || `공통 MCP 설치기 종료 코드: ${result.status ?? "알 수 없음"}`, }; } diff --git a/test/install.test.js b/test/install.test.js index 21e9224..feb9f21 100644 --- a/test/install.test.js +++ b/test/install.test.js @@ -1,167 +1,36 @@ import assert from "node:assert/strict"; import test from "node:test"; - -import { detectClients, installMcp, selectClient } from "../src/install.js"; - -const REMOTE_URL = "https://nerdboard.kr/mcp"; - -function createRunner({ - installedClients = ["codex"], - registrations = {}, - addResults = {}, -} = {}) { - const runner = (command, args) => { - runner.calls.push([command, args]); - - if (args[0] === "--version") { - return { - status: installedClients.includes(command) ? 0 : 1, - stdout: "", - stderr: "", - }; - } - - if (args[0] === "mcp" && args[1] === "get") { - const registration = registrations[command]; - return registration === undefined - ? { status: 1, stdout: "", stderr: "no such server" } - : { status: 0, stdout: registration, stderr: "" }; - } - - if (args[0] === "mcp" && args.includes("add")) { - return ( - addResults[command] ?? { status: 0, stdout: "added", stderr: "" } - ); - } - - return { status: 1, stdout: "", stderr: "unexpected command" }; - }; - runner.calls = []; - return runner; -} - -test("detects only clients whose exit code is success", () => { - const runner = (command) => ({ - status: command === "codex" ? 0 : 1, - stdout: "", - stderr: "", +import { installMcp } from "../src/install.js"; + +for (const client of [null, "codex", "claude"]) { + test(`공통 npm 패키지에 설치를 위임한다: ${client ?? "자동 선택"}`, () => { + const calls = []; + const result = installMcp({ + requestedClient: client, + runner: (command, args) => { + calls.push([command, args]); + return { status: 0, stdout: "전체 권한 로그인 안내", stderr: "" }; + }, + }); + assert.deepEqual(calls, [["npx", ["-y", "@nerdlab-dev/meta-ads-mcp@latest", "install", ...(client ? ["--client", client] : [])]]]); + assert.equal(result.ok, true); + assert.match(result.message, /전체 권한 로그인 안내/); }); +} - assert.deepEqual(detectClients(runner), ["codex"]); -}); - -test("selects Codex when only Codex is installed", () => { - assert.deepEqual(selectClient(null, ["codex"]), { client: "codex" }); -}); - -test("selects Claude when only Claude is installed", () => { - assert.deepEqual(selectClient(null, ["claude"]), { client: "claude" }); -}); - -test("requires an explicit choice when both clients are installed", () => { - const result = selectClient(null, ["codex", "claude"]); - - assert.match(result.error, /--client/); -}); - -test("points to manual install when no client is installed", () => { - const result = selectClient(null, []); - - assert.match(result.error, /manual install/); -}); - -test("fails when the requested client is not installed", () => { - const result = selectClient("claude", ["codex"]); - - assert.match(result.error, /Could not find/); -}); - -test("adds an unregistered Codex server", async () => { - const runner = createRunner(); - - const result = await installMcp({ requestedClient: "codex", runner }); - - assert.equal(result.ok, true); - assert.deepEqual(runner.calls.at(-1), [ - "codex", - ["mcp", "add", "nerdboard-crm", "--url", REMOTE_URL], - ]); - assert.match(result.message, /codex mcp login/); - assert.match(result.message, /nerdboard-crm/); -}); - -test("requests the CRM read, write, send, and asset scopes in the Codex login", async () => { - const runner = createRunner(); - - const result = await installMcp({ requestedClient: "codex", runner }); - - assert.match(result.message, /--scopes/); - assert.match(result.message, /crm:segment:read/); - assert.match(result.message, /crm:segment:write/); - assert.match(result.message, /crm:coupon:read/); - assert.match(result.message, /crm:coupon:write/); - assert.match(result.message, /crm:campaign:read/); - assert.match(result.message, /crm:campaign:write/); - assert.match(result.message, /crm:campaign:send/); - assert.match(result.message, /crm:strategy:read/); - assert.match(result.message, /ad-asset:read/); - assert.match(result.message, /ad-asset:write/); -}); - -test("adds an unregistered Claude server at user scope", async () => { - const runner = createRunner({ installedClients: ["claude"] }); - - const result = await installMcp({ requestedClient: "claude", runner }); - - assert.equal(result.ok, true); - assert.deepEqual(runner.calls.at(-1), [ - "claude", - [ - "mcp", - "add", - "--transport", - "http", - "--scope", - "user", - "nerdboard-crm", - REMOTE_URL, - ], - ]); - assert.match(result.message, /\/mcp/); -}); - -test("does not add when the same URL is already registered", async () => { - const runner = createRunner({ registrations: { codex: REMOTE_URL } }); - - const result = await installMcp({ requestedClient: "codex", runner }); - - assert.equal(result.ok, true); - assert.equal(runner.calls.some(([, args]) => args.includes("add")), false); - assert.match(result.message, /already connected/); +test("공통 설치기가 실패하면 성공으로 보고하지 않는다", () => { + const result = installMcp({ runner: () => ({ status: 7, stdout: "", stderr: "패키지 설치 실패" }) }); + assert.equal(result.ok, false); + assert.match(result.message, /패키지 설치 실패/); }); -test("does not overwrite when the same name has a different URL", async () => { - const runner = createRunner({ - registrations: { codex: "https://example.com/mcp" }, - }); - - const result = await installMcp({ requestedClient: "codex", runner }); - +test("npx를 실행할 수 없을 때 오류를 보여준다", () => { + const result = installMcp({ runner: () => ({ status: null, error: new Error("npx ENOENT") }) }); assert.equal(result.ok, false); - assert.equal(runner.calls.some(([, args]) => args.includes("add")), false); - assert.match(result.message, /left unchanged/); + assert.match(result.message, /npx ENOENT/); }); -test("returns the exit code and error when the add command fails", async () => { - const runner = createRunner({ - addResults: { - codex: { status: 7, stdout: "", stderr: "permission denied" }, - }, - }); - - const result = await installMcp({ requestedClient: "codex", runner }); - +test("지원하지 않는 클라이언트는 실행 전에 거부한다", () => { + const result = installMcp({ requestedClient: "unknown", runner: () => assert.fail("실행하면 안 됩니다") }); assert.equal(result.ok, false); - assert.match(result.message, /Exit code 7/); - assert.match(result.message, /permission denied/); });