@crmforall/connector 0.1.0

package/dist/tools.js

@@ -0,0 +1,410 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTools = registerTools;
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const contracts_1 = require("./contracts");
+const config_1 = require("./config");
+const mapping_1 = require("./mapping");
+const targets_1 = require("./targets");
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+function fail(code, message) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: { code, message, hint: contracts_1.ERROR_HINTS[code] } }),
+            },
+        ],
+    };
+}
+function unexpected(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/매핑되지 않은 필드|잘못된 식별자/.test(message)) {
+        return fail(contracts_1.ERROR_CODE.SCHEMA_MISSING_FIELD, message);
+    }
+    return fail(contracts_1.ERROR_CODE.NET_UNREACHABLE, `실행 실패: ${message}`);
+}
+/** 승인 검증 + 감사 기록 — 모든 승인 필요 도구의 공용 게이트 */
+async function consumeApprovalOrFail(rt, tool, token, scope, snapshotHash) {
+    const verdict = await rt.platform.consumeApproval({
+        token,
+        expectedScope: scope,
+        snapshotHash,
+    });
+    const db = await rt.getDb();
+    await db.execute(`INSERT INTO ${rt.config.crmSchema}.crm_audit_logs (actor, action, detail)
+     VALUES ($1, $2, $3)`, [
+        `connector:${rt.config.connectorId}`,
+        `${tool}.${verdict.ok ? "approved" : "denied"}`,
+        JSON.stringify(verdict.ok
+            ? { approvalId: verdict.claims.approvalId, scope }
+            : { code: verdict.code, scope }),
+    ]);
+    if (!verdict.ok) {
+        return { ok: false, result: fail(verdict.code, verdict.message) };
+    }
+    if (verdict.claims.tenantId !== rt.config.tenantId) {
+        return {
+            ok: false,
+            result: fail(contracts_1.ERROR_CODE.TOKEN_SCOPE_MISMATCH, "토큰의 테넌트가 이 커넥터의 테넌트와 다릅니다."),
+        };
+    }
+    return { ok: true, approvalId: verdict.claims.approvalId };
+}
+function requireMapping(rt, mappingVersion) {
+    const mapping = rt.config.mapping;
+    if (!mapping) {
+        return {
+            ok: false,
+            result: fail(contracts_1.ERROR_CODE.SCHEMA_MISSING_FIELD, "확정된 필드 매핑이 없습니다. propose_field_mapping → validate_mapping(persist=true)을 먼저 실행하세요."),
+        };
+    }
+    if (mapping.version !== mappingVersion) {
+        return {
+            ok: false,
+            result: fail(contracts_1.ERROR_CODE.SCHEMA_MISSING_FIELD, `요청한 매핑 버전(${mappingVersion})이 확정본(${mapping.version})과 다릅니다.`),
+        };
+    }
+    return { ok: true, mapping };
+}
+function registerTools(server, rt) {
+    const s = rt.config.crmSchema;
+    server.tool(contracts_1.MCP_TOOL.TEST_CONNECTION, "DB 연결 상태와 권한 요약을 반환한다 (승인 불필요, 민감정보 미노출)", {}, async () => {
+        try {
+            const db = await rt.getDb();
+            const report = await db.checkReadiness({ crmSchema: s });
+            return ok({
+                connectionId: rt.config.connectionId,
+                sourceType: db.sourceType,
+                status: report.overprivileged
+                    ? "overprivileged"
+                    : report.ready
+                        ? "ready"
+                        : "not_ready",
+                checks: report.checks.map(({ name, passed, detail }) => ({
+                    name,
+                    passed,
+                    detail,
+                })),
+            });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.INSPECT_SCHEMA, "운영 DB의 테이블/컬럼 후보를 반환한다 (컬럼명 중심, 데이터 미노출)", {
+        schemaAllowlist: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("탐색을 허용할 스키마 목록 (생략 시 시스템 스키마 외 전체)"),
+    }, async ({ schemaAllowlist }) => {
+        try {
+            const db = await rt.getDb();
+            const columns = await db.listColumns({ schemaAllowlist });
+            const tables = new Map();
+            for (const c of columns) {
+                const key = `${c.schema}.${c.table}`;
+                if (!tables.has(key)) {
+                    tables.set(key, { schema: c.schema, table: c.table, columns: [] });
+                }
+                tables.get(key).columns.push({ column: c.column, dataType: c.dataType });
+            }
+            return ok({ tables: [...tables.values()] });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.PROPOSE_FIELD_MAPPING, "컬럼명 휴리스틱으로 표준 필드 매핑 후보를 제안한다 (확정은 validate_mapping에서)", {
+        schemaAllowlist: zod_1.z.array(zod_1.z.string()).optional(),
+    }, async ({ schemaAllowlist }) => {
+        try {
+            const db = await rt.getDb();
+            const columns = await db.listColumns({ schemaAllowlist });
+            return ok((0, mapping_1.proposeMapping)(columns));
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.VALIDATE_MAPPING, "매핑의 필수 필드 충족과 컬럼 실재를 검증한다. persist=true면 통과본을 확정 저장한다", {
+        mapping: zod_1.z
+            .record(zod_1.z.unknown())
+            .describe("MappingConfig JSON — version, customer/reservation 엔터티"),
+        persist: zod_1.z
+            .boolean()
+            .default(false)
+            .describe("검증 통과 시 확정 매핑으로 저장할지 여부"),
+    }, async ({ mapping: rawMapping, persist }) => {
+        try {
+            const parsed = config_1.mappingConfigSchema.safeParse(rawMapping);
+            if (!parsed.success) {
+                return fail(contracts_1.ERROR_CODE.SCHEMA_MISSING_FIELD, `매핑 형식 오류: ${parsed.error.issues.map((i) => i.path.join(".")).join(", ")}`);
+            }
+            const db = await rt.getDb();
+            const columns = await db.listColumns({});
+            const validation = (0, mapping_1.validateMapping)(parsed.data, columns);
+            if (!validation.valid) {
+                return fail(contracts_1.ERROR_CODE.SCHEMA_MISSING_FIELD, `매핑 검증 실패 — 누락: [${validation.missingRequired.join(", ")}], 미존재 컬럼: [${validation.unknownColumns.join(", ")}]`);
+            }
+            let persisted = false;
+            if (persist) {
+                await rt.persistMapping(parsed.data);
+                await db.execute(`INSERT INTO ${s}.crm_field_mappings (version, mapping)
+             VALUES ($1, $2)
+             ON CONFLICT (version) DO UPDATE SET mapping = EXCLUDED.mapping`, [parsed.data.version, JSON.stringify(parsed.data)]);
+                persisted = true;
+            }
+            return ok({ valid: true, version: parsed.data.version, persisted });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.PREVIEW_TARGETS, "조건 프로젝트의 대상 수와 제외 사유별 건수를 반환한다 (원문 전화번호 미노출)", {
+        projectId: zod_1.z.string(),
+        mappingVersion: zod_1.z.string(),
+    }, async ({ projectId, mappingVersion }) => {
+        try {
+            const m = requireMapping(rt, mappingVersion);
+            if (!m.ok)
+                return m.result;
+            const project = await rt.platform.getProjectDefinition(projectId);
+            const db = await rt.getDb();
+            const computation = await (0, targets_1.computeTargets)(db, m.mapping, project, {
+                now: rt.now,
+            });
+            return ok({
+                targetCount: computation.members.length,
+                exclusions: computation.exclusions,
+                previewHash: computation.previewHash,
+            });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.CREATE_TARGET_SNAPSHOT, "승인된 미리보기를 대상 스냅샷으로 고정한다 (승인 토큰 필수, 해시 일치 검증)", {
+        projectId: zod_1.z.string(),
+        previewHash: zod_1.z.string(),
+        approvalToken: zod_1.z.string().min(1),
+    }, async ({ projectId, previewHash, approvalToken }) => {
+        try {
+            const mapping = rt.config.mapping;
+            if (!mapping) {
+                return fail(contracts_1.ERROR_CODE.SCHEMA_MISSING_FIELD, "확정된 필드 매핑이 없습니다.");
+            }
+            const gate = await consumeApprovalOrFail(rt, contracts_1.MCP_TOOL.CREATE_TARGET_SNAPSHOT, approvalToken, contracts_1.APPROVAL_SCOPE.TARGET_SNAPSHOT_CREATE, previewHash);
+            if (!gate.ok)
+                return gate.result;
+            const db = await rt.getDb();
+            // 멱등: 같은 승인의 중복 요청은 기존 스냅샷으로 수렴
+            const existing = await db.selectRows(`SELECT snapshot_id, snapshot_hash, target_count
+           FROM ${s}.crm_target_snapshots WHERE approval_id = $1`, [gate.approvalId]);
+            if (existing.length > 0) {
+                return ok({
+                    snapshotId: String(existing[0].snapshot_id),
+                    snapshotHash: String(existing[0].snapshot_hash),
+                    targetCount: Number(existing[0].target_count),
+                    deduplicated: true,
+                });
+            }
+            // 승인 시점과 실행 시점의 대상이 같은지 재산출로 확인
+            const project = await rt.platform.getProjectDefinition(projectId);
+            const computation = await (0, targets_1.computeTargets)(db, mapping, project, {
+                now: rt.now,
+            });
+            if (computation.previewHash !== previewHash) {
+                return fail(contracts_1.ERROR_CODE.SNAPSHOT_HASH_MISMATCH, "승인 이후 대상이 변동되었습니다. 미리보기를 다시 산출하고 재승인 받으세요.");
+            }
+            const snapshotId = (0, node_crypto_1.randomUUID)();
+            await db.execute(`INSERT INTO ${s}.crm_target_snapshots
+             (snapshot_id, project_id, project_version, mapping_version,
+              snapshot_hash, approval_id, target_count, exclusions)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+                snapshotId,
+                project.projectId,
+                project.projectVersion,
+                mapping.version,
+                computation.previewHash,
+                gate.approvalId,
+                computation.members.length,
+                JSON.stringify(computation.exclusions),
+            ]);
+            for (const member of computation.members) {
+                await db.execute(`INSERT INTO ${s}.crm_snapshot_members (snapshot_id, customer_key, phone_hash)
+             VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`, [snapshotId, member.customerKey, member.phoneHash]);
+            }
+            return ok({
+                snapshotId,
+                snapshotHash: computation.previewHash,
+                targetCount: computation.members.length,
+                deduplicated: false,
+            });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.WRITE_CRM_EVENT, "CRM 전용 스키마에 이벤트를 기록한다 (승인 토큰 필수, 운영 원천 테이블 비접근)", {
+        eventType: zod_1.z.string().min(1),
+        payload: zod_1.z.record(zod_1.z.unknown()),
+        approvalToken: zod_1.z.string().min(1),
+    }, async ({ eventType, payload, approvalToken }) => {
+        try {
+            const gate = await consumeApprovalOrFail(rt, contracts_1.MCP_TOOL.WRITE_CRM_EVENT, approvalToken, contracts_1.APPROVAL_SCOPE.CRM_EVENT_WRITE, undefined);
+            if (!gate.ok)
+                return gate.result;
+            const db = await rt.getDb();
+            const existing = await db.selectRows(`SELECT event_id FROM ${s}.crm_events WHERE approval_id = $1`, [gate.approvalId]);
+            if (existing.length > 0) {
+                return ok({ eventId: String(existing[0].event_id), deduplicated: true });
+            }
+            const eventId = (0, node_crypto_1.randomUUID)();
+            await db.execute(`INSERT INTO ${s}.crm_events (event_id, event_type, payload, approval_id)
+           VALUES ($1, $2, $3, $4)`, [eventId, eventType, JSON.stringify(payload), gate.approvalId]);
+            return ok({ eventId, deduplicated: false });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.SEND_KAKAO_MESSAGE, "승인된 스냅샷 대상에게 발송 작업을 생성한다 (승인 토큰 필수, 스냅샷 해시 바인딩)", {
+        snapshotId: zod_1.z.string(),
+        messageVersion: zod_1.z.string(),
+        channel: zod_1.z.enum(["alimtalk", "brand"]),
+        approvalToken: zod_1.z.string().min(1),
+    }, async ({ snapshotId, messageVersion, channel, approvalToken }) => {
+        try {
+            const db = await rt.getDb();
+            const snapshots = await db.selectRows(`SELECT snapshot_hash, target_count, project_id FROM ${s}.crm_target_snapshots
+           WHERE snapshot_id = $1`, [snapshotId]);
+            if (snapshots.length === 0) {
+                return fail(contracts_1.ERROR_CODE.SNAPSHOT_HASH_MISMATCH, `스냅샷 ${snapshotId}이 없습니다. create_target_snapshot을 먼저 실행하세요.`);
+            }
+            const snapshotHash = String(snapshots[0].snapshot_hash);
+            const gate = await consumeApprovalOrFail(rt, contracts_1.MCP_TOOL.SEND_KAKAO_MESSAGE, approvalToken, contracts_1.APPROVAL_SCOPE.KAKAO_SEND, snapshotHash);
+            if (!gate.ok)
+                return gate.result;
+            // 멱등: 같은 승인의 중복 요청은 하나의 발송 작업으로 수렴
+            const existing = await db.selectRows(`SELECT send_job_id FROM ${s}.crm_send_jobs WHERE approval_id = $1`, [gate.approvalId]);
+            if (existing.length > 0) {
+                return ok({ sendJobId: String(existing[0].send_job_id), deduplicated: true });
+            }
+            const { sendJobId } = await rt.platform.createSendJob({
+                approvalId: gate.approvalId,
+                snapshotId,
+                snapshotHash,
+                messageVersion,
+                channel,
+                targetCount: Number(snapshots[0].target_count),
+                campaignRef: snapshots[0].project_id ? String(snapshots[0].project_id) : null,
+            });
+            await db.execute(`INSERT INTO ${s}.crm_send_jobs
+             (send_job_id, snapshot_id, channel, message_version, approval_id, status)
+           VALUES ($1, $2, $3, $4, $5, 'queued')
+           ON CONFLICT (approval_id) DO NOTHING`, [sendJobId, snapshotId, channel, messageVersion, gate.approvalId]);
+            return ok({ sendJobId, deduplicated: false });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    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 });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    server.tool(contracts_1.MCP_TOOL.TRACK_ENGAGEMENT, "반응(클릭/예약/픽업완료)을 crm_engagements에 기록한다 (추가 전용, 개인정보 비반환, 승인 불필요)", {
+        identityKey: zod_1.z.string().min(1),
+        engagementType: zod_1.z.enum(["click", "reservation", "pickup_completed"]),
+        campaignRef: zod_1.z.string().nullable(),
+        shortLinkRef: zod_1.z.string().nullable(),
+        reservationRef: zod_1.z.string().nullable(),
+        pickupAmount: zod_1.z.number().nullable(),
+        occurredAt: zod_1.z.string().datetime(),
+    }, async (input) => {
+        try {
+            const db = await rt.getDb();
+            const eventId = (0, node_crypto_1.randomUUID)();
+            await db.execute(`INSERT INTO ${s}.crm_engagements
+             (event_id, identity_key, engagement_type, campaign_ref,
+              short_link_ref, reservation_ref, pickup_amount, occurred_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+                eventId,
+                input.identityKey,
+                input.engagementType,
+                input.campaignRef,
+                input.shortLinkRef,
+                input.reservationRef,
+                input.pickupAmount,
+                input.occurredAt,
+            ]);
+            // 플랫폼 중계는 집계용 — 실패해도 로컬 기록(원본)은 유지된다
+            let relayed = true;
+            try {
+                await rt.platform.reportEngagement({
+                    identityKey: input.identityKey,
+                    engagementType: input.engagementType,
+                    campaignRef: input.campaignRef,
+                    shortLinkRef: input.shortLinkRef,
+                    reservationRef: input.reservationRef,
+                    pickupAmount: input.pickupAmount,
+                    occurredAt: input.occurredAt,
+                });
+            }
+            catch {
+                relayed = false;
+            }
+            return ok({ eventId, relayed });
+        }
+        catch (err) {
+            return unexpected(err);
+        }
+    });
+    // --- 2차 도구 — 승인 경계만 고정, 본 구현은 해당 마일스톤에서 ---
+    const futureTools = [
+        { name: contracts_1.MCP_TOOL.IMPORT_PROSPECTS, phase: "2차" },
+        { name: contracts_1.MCP_TOOL.REGISTER_ENTRY_POINT, phase: "2차" },
+    ];
+    for (const { name, phase } of futureTools) {
+        server.tool(name, `${name} — ${phase} 마일스톤에서 구현된다. 승인 경계는 유지된다.`, { approvalToken: zod_1.z.string().optional() }, async () => ({
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: {
+                            code: "E_NOT_IMPLEMENTED",
+                            message: `${name}은 ${phase} 마일스톤에서 구현됩니다. 승인 토큰 검증 경계는 유지됩니다.`,
+                        },
+                    }),
+                },
+            ],
+        }));
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@crmforall/connector",
+  "version": "0.1.0",
+  "description": "crmforall MCP 커넥터 — 운영 DB 읽기, CRM 스키마 쓰기(승인 토큰 필수), 대상 산출",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./db": "./dist/db/index.js"
+  },
+  "typesVersions": {
+    "*": {
+      "db": [
+        "dist/db/index.d.ts"
+      ]
+    }
+  },
+  "bin": {
+    "crmforall-connector": "./dist/server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "pg": "^8.16.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.15.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HosungYou/crmforall-connector"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}