@crmforall/connector 0.1.2 → 0.1.4

package/dist/contracts.d.ts

@@ -16,6 +16,8 @@ export declare const MCP_TOOL: {
     readonly IMPORT_PROSPECTS: "import_prospects";
     readonly REGISTER_ENTRY_POINT: "register_entry_point";
     readonly TRACK_ENGAGEMENT: "track_engagement";
+    readonly ONBOARDING_STATUS: "onboarding_status";
+    readonly SYNC_ALL: "sync_all";
 };
 export type McpToolName = (typeof MCP_TOOL)[keyof typeof MCP_TOOL];
 export declare const APPROVAL_SCOPE: {

package/dist/contracts.js

@@ -19,6 +19,8 @@ exports.MCP_TOOL = {
     IMPORT_PROSPECTS: "import_prospects",
     REGISTER_ENTRY_POINT: "register_entry_point",
     TRACK_ENGAGEMENT: "track_engagement",
+    ONBOARDING_STATUS: "onboarding_status",
+    SYNC_ALL: "sync_all",
 };
 exports.APPROVAL_SCOPE = {
     TARGET_SNAPSHOT_CREATE: "target_snapshot:create",
@@ -41,6 +43,8 @@ exports.TOOL_APPROVAL_REQUIREMENT = {
     [exports.MCP_TOOL.IMPORT_PROSPECTS]: exports.APPROVAL_SCOPE.PROSPECT_IMPORT,
     [exports.MCP_TOOL.REGISTER_ENTRY_POINT]: exports.APPROVAL_SCOPE.ENTRY_POINT_REGISTER,
     [exports.MCP_TOOL.TRACK_ENGAGEMENT]: null,
+    [exports.MCP_TOOL.ONBOARDING_STATUS]: null,
+    [exports.MCP_TOOL.SYNC_ALL]: null,
 };
 /** 승인 토큰이 필요한 도구 — 토큰 없이 호출되면 즉시 거부한다. */
 exports.APPROVAL_REQUIRED_TOOLS = new Set(Object.entries(exports.TOOL_APPROVAL_REQUIREMENT)

package/dist/index.d.ts

@@ -6,6 +6,9 @@ export * from "./mapping";
 export * from "./platform";
 export * from "./targets";
 export * from "./tools";
+export * from "./sync";
+export { PostgresAdapter } from "./db/postgres";
+export type { DbAdapter } from "./db/adapter";
 /**
  * crmforall MCP 커넥터 라이브러리 진입점.
  * 서버 기동은 server.ts(bin)에서 — CLI가 이 모듈을 import해도 서버가 뜨지 않는다.

package/dist/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = void 0;
 exports.buildAdapter = buildAdapter;
 const postgres_1 = require("./db/postgres");
 __exportStar(require("./config"), exports);
@@ -22,6 +23,9 @@ __exportStar(require("./mapping"), exports);
 __exportStar(require("./platform"), exports);
 __exportStar(require("./targets"), exports);
 __exportStar(require("./tools"), exports);
+__exportStar(require("./sync"), exports);
+var postgres_2 = require("./db/postgres");
+Object.defineProperty(exports, "PostgresAdapter", { enumerable: true, get: function () { return postgres_2.PostgresAdapter; } });
 /**
  * crmforall MCP 커넥터 라이브러리 진입점.
  * 서버 기동은 server.ts(bin)에서 — CLI가 이 모듈을 import해도 서버가 뜨지 않는다.

package/dist/server.js

@@ -30,6 +30,14 @@ async function main() {
     const server = new mcp_js_1.McpServer({
         name: "crmforall-connector",
         version: "0.1.0",
+    }, {
+        instructions: [
+            "크렘포올 DB 커넥터입니다. 고객사 DB를 진단·연결·매핑해 크렘포올 플랫폼과 잇습니다.",
+            "온보딩 순서: onboarding_status로 현재 단계를 확인 → test_connection(연결·권한) → inspect_schema(컬럼 확인) → propose_field_mapping(후보) → validate_mapping(persist=true)으로 확정.",
+            "막히면 onboarding_status의 nextStep을 따르세요. 오류 응답의 hint도 다음 행동을 알려줍니다.",
+            "보안 원칙: DB 비밀번호·커넥터 시크릿·고객 개인정보(전화번호 원문 등)는 절대 사용자에게 출력하지 마세요. 컬럼명·집계·인원수만 다룹니다.",
+            "쓰기/발송 도구(create_target_snapshot·send_kakao_message 등)는 플랫폼의 사람 승인 토큰이 있어야 동작합니다. 승인 없이는 거부됩니다.",
+        ].join("\n"),
     });
     (0, tools_1.registerTools)(server, {
         config,

package/dist/sync.d.ts

@@ -0,0 +1,30 @@
+import type { DbAdapter } from "./db/adapter";
+import type { PlatformClient } from "./platform";
+/**
+ * 발송 결과 동기화 — 플랫폼이 가진 발송 작업 결과를 고객사 CRM 스키마로 반영한다.
+ * 데이터 방향: 플랫폼 → 고객사 DB(crm_send_jobs / crm_send_results). 승인 불필요(읽기성).
+ * CLI `connect sync`(주기 폴링)와 MCP `sync_send_result`·`sync_all`이 공유한다.
+ */
+export interface SyncedJob {
+    sendJobId: string;
+    status: string;
+    counts: Record<string, number>;
+}
+/** 한 발송 작업의 결과를 플랫폼에서 가져와 CRM 스키마에 upsert */
+export declare function syncSendJob(db: DbAdapter, platform: PlatformClient, crmSchema: string, sendJobId: string): Promise<SyncedJob>;
+export interface SyncResult {
+    synced: number;
+    /** 아직 진행 중(non-terminal)으로 남은 작업 수 — 다음 주기에 다시 시도 */
+    stillPending: number;
+    jobs: SyncedJob[];
+}
+/**
+ * 진행 중인(완료/실패가 아닌) 발송 작업을 모두 동기화한다 (주기 폴링의 1회분).
+ * 데이터 방향은 단방향(플랫폼→로컬)이라 원본 운영 테이블은 절대 건드리지 않는다.
+ */
+export declare function syncPendingSendJobs(opts: {
+    db: DbAdapter;
+    platform: PlatformClient;
+    crmSchema: string;
+    limit?: number;
+}): Promise<SyncResult>;

package/dist/sync.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncSendJob = syncSendJob;
+exports.syncPendingSendJobs = syncPendingSendJobs;
+const TERMINAL = new Set(["done", "failed"]);
+/** 한 발송 작업의 결과를 플랫폼에서 가져와 CRM 스키마에 upsert */
+async function syncSendJob(db, platform, crmSchema, sendJobId) {
+    const job = await platform.getSendJob(sendJobId);
+    for (const r of job.results) {
+        await db.execute(`INSERT INTO ${crmSchema}.crm_send_results
+         (send_job_id, receiver_ref, status, provider_code, internal_code)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (send_job_id, receiver_ref) DO UPDATE
+         SET status = EXCLUDED.status,
+             provider_code = EXCLUDED.provider_code,
+             internal_code = EXCLUDED.internal_code,
+             synced_at = now()`, [sendJobId, r.receiverRef, r.status, r.providerCode, r.internalCode]);
+    }
+    await db.execute(`UPDATE ${crmSchema}.crm_send_jobs SET status = $2 WHERE send_job_id = $1`, [sendJobId, job.status]);
+    const counts = job.results.reduce((acc, r) => {
+        acc[r.status] = (acc[r.status] ?? 0) + 1;
+        return acc;
+    }, {});
+    return { sendJobId, status: job.status, counts };
+}
+/**
+ * 진행 중인(완료/실패가 아닌) 발송 작업을 모두 동기화한다 (주기 폴링의 1회분).
+ * 데이터 방향은 단방향(플랫폼→로컬)이라 원본 운영 테이블은 절대 건드리지 않는다.
+ */
+async function syncPendingSendJobs(opts) {
+    const { db, platform, crmSchema, limit = 200 } = opts;
+    const rows = await db.selectRows(`SELECT send_job_id FROM ${crmSchema}.crm_send_jobs
+       WHERE status NOT IN ('done','failed')
+       ORDER BY send_job_id
+       LIMIT $1`, [limit]);
+    const jobs = [];
+    let stillPending = 0;
+    for (const row of rows) {
+        const id = String(row.send_job_id);
+        const synced = await syncSendJob(db, platform, crmSchema, id);
+        jobs.push(synced);
+        if (!TERMINAL.has(synced.status))
+            stillPending++;
+    }
+    return { synced: jobs.length, stillPending, jobs };
+}

package/dist/tools.js

@@ -7,6 +7,7 @@ const contracts_1 = require("./contracts");
 const config_1 = require("./config");
 const mapping_1 = require("./mapping");
 const targets_1 = require("./targets");
+const sync_1 = require("./sync");
 function ok(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -73,6 +74,48 @@ function requireMapping(rt, mappingVersion) {
 }
 function registerTools(server, rt) {
     const s = rt.config.crmSchema;
+    // AI 온보딩 안내 — 지금 어디까지 됐고 다음에 뭘 할지 한 번에 알려준다.
+    server.tool(contracts_1.MCP_TOOL.ONBOARDING_STATUS, "온보딩 진행 상태와 다음 할 일을 반환한다. 연결 직후·중간에 호출해 흐름을 안내받는다 (승인 불필요).", {}, async () => {
+        const steps = [];
+        // 1) 자격증명/설정
+        steps.push({ step: "register", done: true, detail: `connectionId=${rt.config.connectionId}` });
+        // 2) DB 연결·권한
+        let dbReady = false;
+        let overpriv = false;
+        try {
+            const db = await rt.getDb();
+            const report = await db.checkReadiness({ crmSchema: s });
+            dbReady = report.ready;
+            overpriv = report.overprivileged;
+            steps.push({
+                step: "db_connection",
+                done: report.ready && !report.overprivileged,
+                detail: report.overprivileged ? "과권한 계정 — 권한 축소 필요" : report.ready ? "연결·스키마 정상" : "준비 미완 (doctor 참고)",
+            });
+        }
+        catch (err) {
+            steps.push({ step: "db_connection", done: false, detail: err instanceof Error ? err.message : String(err) });
+        }
+        // 3) 필드 매핑
+        const mapped = rt.config.mapping !== null;
+        steps.push({ step: "field_mapping", done: mapped, detail: mapped ? "매핑 확정됨" : "propose_field_mapping → validate_mapping(persist=true) 필요" });
+        // 다음 할 일 한 줄
+        let nextStep;
+        if (overpriv)
+            nextStep = "DB 계정이 과권한입니다. test_connection의 권한 축소 SQL을 DBA에게 전달해 권한을 낮춘 뒤 다시 시도하세요.";
+        else if (!dbReady)
+            nextStep = "DB 연결/스키마가 준비되지 않았습니다. test_connection으로 원인을 확인하세요.";
+        else if (!mapped)
+            nextStep = "inspect_schema로 컬럼을 본 뒤, propose_field_mapping으로 후보를 만들고 validate_mapping(persist=true)으로 확정하세요.";
+        else
+            nextStep = "온보딩 완료! preview_targets로 대상을 미리 보거나, 실시간 동기화를 켜세요.";
+        return ok({
+            ready: dbReady && !overpriv && mapped,
+            steps,
+            nextStep,
+            guidance: "이 순서로 진행하세요: test_connection → inspect_schema → propose_field_mapping → validate_mapping(persist=true) → (완료) preview_targets. 자격증명·비밀번호는 절대 출력하지 마세요.",
+        });
+    });
     server.tool(contracts_1.MCP_TOOL.TEST_CONNECTION, "DB 연결 상태와 권한 요약을 반환한다 (승인 불필요, 민감정보 미노출)", {}, async () => {
         try {
             const db = await rt.getDb();
@@ -316,24 +359,19 @@ function registerTools(server, rt) {
     });
     server.tool(contracts_1.MCP_TOOL.SYNC_SEND_RESULT, "발송 작업 결과를 플랫폼에서 가져와 CRM 스키마에 동기화한다 (승인 불필요)", { sendJobId: zod_1.z.string() }, async ({ sendJobId }) => {
         try {
-            const job = await rt.platform.getSendJob(sendJobId);
             const db = await rt.getDb();
-            for (const r of job.results) {
-                await db.execute(`INSERT INTO ${s}.crm_send_results
-               (send_job_id, receiver_ref, status, provider_code, internal_code)
-             VALUES ($1, $2, $3, $4, $5)
-             ON CONFLICT (send_job_id, receiver_ref) DO UPDATE
-               SET status = EXCLUDED.status,
-                   provider_code = EXCLUDED.provider_code,
-                   internal_code = EXCLUDED.internal_code,
-                   synced_at = now()`, [sendJobId, r.receiverRef, r.status, r.providerCode, r.internalCode]);
-            }
-            await db.execute(`UPDATE ${s}.crm_send_jobs SET status = $2 WHERE send_job_id = $1`, [sendJobId, job.status]);
-            const counts = job.results.reduce((acc, r) => {
-                acc[r.status] = (acc[r.status] ?? 0) + 1;
-                return acc;
-            }, {});
-            return ok({ sendJobId, status: job.status, resultCounts: counts });
+            const r = await (0, sync_1.syncSendJob)(db, rt.platform, s, sendJobId);
+            return ok({ sendJobId: r.sendJobId, status: r.status, resultCounts: r.counts });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.SYNC_ALL, "진행 중인 발송 작업 전체를 한 번에 동기화한다 (주기 폴링 1회분, 승인 불필요)", { limit: zod_1.z.number().int().positive().max(500).optional() }, async ({ limit }) => {
+        try {
+            const db = await rt.getDb();
+            const result = await (0, sync_1.syncPendingSendJobs)({ db, platform: rt.platform, crmSchema: s, limit });
+            return ok(result);
         }
         catch (err) {
             return unexpected(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crmforall/connector",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "crmforall MCP 커넥터 — 운영 DB 읽기, CRM 스키마 쓰기(승인 토큰 필수), 대상 산출",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",