Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 0 additions & 17 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
14 changes: 14 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# CRM 작업 지침

## MCP 설치 권한 정책

- 모든 MCP 설치는 서버가 지원하는 전체 권한을 한 번에 요청합니다.
- Meta·CRM 등 일부 기능의 권한 목록을 설치 명령에 고정하지 않습니다.
- 너드보드 공통 설치 패키지는 `@nerdlab-dev/meta-ads-mcp`입니다. CRM도 같은 패키지를 사용합니다.
- 기존 제한 권한 연결은 전체 권한으로 재로그인합니다. 기존 토큰을 임의로 확장하지 않습니다.
- 전체 권한 요청과 별개로 서버의 실시간 계정·몰·구독 권한 검사와 도구 하드게이트는 유지합니다.

## GitHub 작성 언어

- 커밋 메시지와 PR 제목·본문은 한국어로 작성합니다.
- PR 본문은 짧은 해요체 문장과 개조식으로 작성합니다.
61 changes: 45 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

**CRM 캠페인 세팅, AI 자동화로 5분 안에 끝내보세요.**

[![npm version](https://img.shields.io/npm/v/%40nerdlab-dev%2Fcrm-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/@nerdlab-dev/crm-mcp)
[![npm downloads](https://img.shields.io/npm/dm/%40nerdlab-dev%2Fcrm-mcp)](https://www.npmjs.com/package/@nerdlab-dev/crm-mcp)
[![npm version](https://img.shields.io/npm/v/%40nerdlab-dev%2Fmeta-ads-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/@nerdlab-dev/meta-ads-mcp)
[![npm downloads](https://img.shields.io/npm/dm/%40nerdlab-dev%2Fmeta-ads-mcp)](https://www.npmjs.com/package/@nerdlab-dev/meta-ads-mcp)
[![CI](https://github.com/nerdlab-dev/crm/actions/workflows/ci.yml/badge.svg)](https://github.com/nerdlab-dev/crm/actions/workflows/ci.yml)
[![Node.js ≥ 20](https://img.shields.io/node/v/%40nerdlab-dev%2Fcrm-mcp?logo=nodedotjs&logoColor=white)](https://nodejs.org)
[![Node.js ≥ 20](https://img.shields.io/node/v/%40nerdlab-dev%2Fmeta-ads-mcp?logo=nodedotjs&logoColor=white)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

[![Works with Claude Code](https://img.shields.io/badge/Works_with-Claude_Code-4A4A4A?style=flat-square)](https://claude.com/claude-code)
Expand All @@ -20,7 +20,7 @@

CRM 캠페인 하나를 보내려면 세그먼트·쿠폰·메시지를 관리자 화면에서 일일이 클릭해야 해요. 너드보드의 호스팅 원격 MCP를 연결하면 AI 에이전트가 대신 해줘요 — **서버 설치도, 내 컴퓨터에 API 키를 둘 일도 없어요**.

이 저장소는 얇은 MIT 라이선스 설치기예요. 모든 CRM 기능은 너드보드가 운영하는 서버에서 실행돼요.
이 저장소는 CRM 사용 안내를 제공해요. 설치는 광고·CRM 공통 패키지 `@nerdlab-dev/meta-ads-mcp`로 진행해요. 모든 CRM 기능은 너드보드 서버에서 실행돼요. 별도 CRM npm 패키지는 설치하거나 배포하지 않아요.

## 무엇을 할 수 있나요

Expand All @@ -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
```

그다음 로그인하세요:
Expand All @@ -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
Expand All @@ -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을 가리키면 덮어쓰지 않고 거부해요.
Expand All @@ -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을 직접 등록하면 돼요:
Expand All @@ -125,7 +143,7 @@ npm pack --dry-run

## 라이선스

이 저장소의 CLI 소스는 [MIT 라이선스](./LICENSE)예요. 너드보드 서비스와 원격 MCP 서버는 별도의 서비스 약관을 따라요.
기존 CRM CLI 소스는 공통 설치 패키지 실행만 위임해요. 이 소스는 [MIT 라이선스](./LICENSE)예요. 너드보드 서비스와 원격 MCP 서버는 별도의 서비스 약관을 따라요.

## 상표

Expand All @@ -134,3 +152,14 @@ OpenAI와 Codex는 OpenAI의 상표예요. Claude와 Claude Code는 Anthropic, P
---

<p align="center"><a href="https://nerdboard.kr">너드보드</a>가 만들었어요</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 없이 직접 연결하려면 위의 수동 설치 명령을 사용해요. 어느 방식이든 같은 서버에서 전체 권한을 한 번에 요청해요.
9 changes: 3 additions & 6 deletions package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -37,9 +37,6 @@
"engines": {
"node": ">=20"
},
"publishConfig": {
"access": "public",
"provenance": true
},
"license": "MIT"
"license": "MIT",
"private": true
}
1 change: 1 addition & 0 deletions scripts/check-public-content.js
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
5 changes: 4 additions & 1 deletion src/cli.js
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
131 changes: 13 additions & 118 deletions src/install.js
Original file line number Diff line number Diff line change
@@ -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 ?? "알 수 없음"}`,
};
}
Loading