@sayren/mcp 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -19,13 +19,17 @@ const METHODS = [
 	"DELETE"
 ];
 /**
-* 돈이 나가는 쓰기 — 되돌릴 수 없으므로 에이전트에게 열지 않는다. 콘솔에서 사람이 한다.
-* 목록은 operationId(`{Controller}_{method}`)로 고정한다.
+* 서버가 정책(`x-agent-policy`)을 싣지 않는 옛 api에만 쓰는 폴백 — 환불로 이어지는 쓰기를 막는다.
+* 새 api는 문서의 정책이 원천이고 이 목록은 보지 않는다(승인 흐름으로 부를 수 있다).
 */
-const BLOCKED_OPERATIONS = {
+const LEGACY_BLOCKED_OPERATIONS = {
 	OrdersController_cancelBySeller: "셀러 직권취소는 PG 환불로 이어져 되돌릴 수 없다. 셀러 콘솔에서 처리한다",
 	ClaimsController_approve: "클레임 승인은 환불로 이어져 되돌릴 수 없다. 셀러 콘솔에서 처리한다"
 };
+/** 문서가 에이전트 정책을 싣는 api인가 — 하나라도 있으면 서버가 정책을 강제한다 */
+function servesAgentPolicy(document) {
+	return Object.values(document.paths ?? {}).some((item) => Object.values(item).some((operation) => operation?.["x-agent-policy"] !== void 0));
+}
 /**
 * 문서에서 에이전트가 쓸 수 있는 오퍼레이션만 고른다.
 * - `/v1/oauth2/*`: 토큰 발급 표면이다. PAT로 부를 일이 없다
@@ -34,6 +38,7 @@ const BLOCKED_OPERATIONS = {
 */
 function buildOperationIndex(document) {
 	const operations = [];
+	const serverPolicy = servesAgentPolicy(document);
 	for (const [path, item] of Object.entries(document.paths ?? {})) {
 		if (!path.startsWith("/v1/") || path.startsWith("/v1/oauth2/")) continue;
 		for (const method of METHODS) {
@@ -41,6 +46,7 @@ function buildOperationIndex(document) {
 			if (!raw?.operationId) continue;
 			const scopes = raw["x-required-scopes"] ?? [];
 			if (scopes.length === 0 || raw["x-console-only"]) continue;
+			const policy = raw["x-agent-policy"];
 			operations.push({
 				operationId: raw.operationId,
 				method,
@@ -49,7 +55,11 @@ function buildOperationIndex(document) {
 				summary: raw.summary ?? raw.operationId,
 				scopes,
 				deprecated: raw.deprecated === true,
-				blocked: BLOCKED_OPERATIONS[raw.operationId],
+				blocked: serverPolicy ? policy?.decision === "DENIED" ? policy.reason : void 0 : LEGACY_BLOCKED_OPERATIONS[raw.operationId],
+				approval: policy?.decision === "APPROVAL_REQUIRED" ? {
+					reason: policy.reason,
+					...policy.condition ? { condition: policy.condition } : {}
+				} : void 0,
 				raw
 			});
 		}
@@ -63,7 +73,8 @@ function formatOperationIndex(operations) {
 		const flags = [
 			op.scopes.join(","),
 			op.deprecated ? "deprecated" : "",
-			op.blocked ? "호출 불가" : ""
+			op.blocked ? "호출 불가" : "",
+			op.approval ? op.approval.condition ? "조건부 승인 필요" : "승인 필요" : ""
 		].filter(Boolean);
 		const lines = byTag[op.tag] ?? [];
 		lines.push(`${op.operationId} · ${op.method} ${op.path} · ${op.summary} [${flags.join(" · ")}]`);
@@ -102,6 +113,10 @@ function describeOperation(op, document) {
 		requiredScopes: op.scopes,
 		deprecated: op.deprecated || void 0,
 		blocked: op.blocked,
+		approval: op.approval ? {
+			...op.approval,
+			note: "부르면 서버가 실행하지 않고 승인 대기(202)로 둔다. 셀러가 콘솔에서 승인하면 서버가 그대로 실행한다. `dryRun: true`로 먼저 영향을 확인한다"
+		} : void 0,
 		tool: op.blocked ? void 0 : op.method === "GET" ? "call_api_read" : "call_api_write",
 		pathParams: parameters.filter((p) => p.in === "path").map((p) => p.name),
 		query: parameters.filter((p) => p.in === "query").map((p) => ({
@@ -163,6 +178,109 @@ function truncateData(data, maxChars) {
 		truncated: `응답 ${text$1.length}자 중 ${maxChars}자만 실었어요`
 	};
 }
+/** 같은 멱등키의 승인이 끝났을 때 상태별 안내 — 에이전트가 다음에 할 일 */
+const DECIDED_GUIDE = {
+	SUCCEEDED: {
+		message: "이 멱등키의 요청은 셀러가 승인해서 이미 실행됐어요. 다시 실행하지 않았어요",
+		nextSteps: ["실행 결과는 `result`다. 같은 요청을 다시 보내지 않는다"]
+	},
+	FAILED: {
+		message: "이 멱등키의 요청은 승인 뒤 실행했지만 실패했어요",
+		nextSteps: ["`result.error`로 원인을 사용자에게 알린다", "고쳐서 다시 하려면 새 멱등키로 요청한다(같은 키는 이 결과만 돌려준다)"]
+	},
+	UNKNOWN: {
+		message: "이 멱등키의 요청은 승인 뒤 실행 결과를 확인하지 못했어요. 이미 실행됐을 수 있어요",
+		nextSteps: ["다시 보내지 않는다. 대상 리소스를 조회해 바뀌었는지 확인하고 사용자에게 알린다", "셀러에게 콘솔의 감사 로그에서 실행 여부를 확인해 달라고 전한다"]
+	},
+	REJECTED: {
+		message: "이 멱등키의 요청은 셀러가 거절했어요. 아무것도 바뀌지 않았어요",
+		nextSteps: ["거절 사유(`decisionNote`)를 전한다. 사용자가 원하면 새 멱등키로 다시 요청한다"]
+	},
+	EXPIRED: {
+		message: "이 멱등키의 요청은 승인 기한(24시간)이 지났어요. 아무것도 바뀌지 않았어요",
+		nextSteps: ["사용자가 원하면 새 멱등키로 다시 요청한다"]
+	}
+};
+/**
+* 쓰기 결과를 에이전트가 읽을 형태로 바꾼다. 승인 대기(202 `APPROVAL_REQUIRED`)는 성공이 아니다 — 아직 아무것도
+* 바뀌지 않았다는 것과 셀러에게 전할 링크, 상태를 확인할 도구를 함께 준다. 같은 멱등키의 승인이 이미 끝났으면
+* (200 `APPROVAL_ALREADY_DECIDED`) `data.status`로 결과와 다음 할 일을 알린다. 에이전트 정책 거부(403)는 다시 시도하지
+* 않게 알린다. 다른 202(비동기 접수)는 승인 대기가 아니다 — `meta.code`로만 가른다.
+*/
+function describeWriteResult(result) {
+	if (result.ok && result.code === "APPROVAL_ALREADY_DECIDED") {
+		const approval = result.data ?? {};
+		const guide = DECIDED_GUIDE[approval.status ?? ""] ?? DECIDED_GUIDE.EXPIRED;
+		return {
+			isError: approval.status !== "SUCCEEDED",
+			body: {
+				status: `APPROVAL_${approval.status ?? "DECIDED"}`,
+				applied: approval.status === "SUCCEEDED" ? true : approval.status === "UNKNOWN" ? "unknown" : false,
+				message: guide?.message,
+				approvalId: approval.approvalId,
+				result: approval.result,
+				decisionNote: approval.decisionNote ?? void 0,
+				nextSteps: guide?.nextSteps
+			}
+		};
+	}
+	if (result.ok && result.code === "APPROVAL_REQUIRED") {
+		const pending = result.data ?? {};
+		if (pending.status === "EXECUTING") return {
+			isError: false,
+			body: {
+				status: "APPROVAL_EXECUTING",
+				applied: "unknown",
+				message: "셀러가 승인해서 서버가 이 요청을 실행하고 있어요",
+				approvalId: pending.approvalId,
+				nextSteps: ["같은 요청을 다시 보내지 않는다. 결과는 `get_approval_request`로 확인한다"]
+			}
+		};
+		return {
+			isError: false,
+			body: {
+				status: "APPROVAL_PENDING",
+				applied: false,
+				message: "승인 대기 중이에요. 아직 아무것도 바뀌지 않았어요. 셀러가 콘솔에서 승인하면 서버가 이 요청을 그대로 실행해요",
+				approvalId: pending.approvalId,
+				reason: pending.reason,
+				expiresAt: pending.expiresAt,
+				approvalUrl: pending.approvalUrl ?? void 0,
+				preview: pending.preview,
+				nextSteps: [pending.approvalUrl ? `사용자에게 승인 화면 링크를 전한다: ${pending.approvalUrl}` : "사용자에게 셀러 콘솔 › 설정 › 승인 요청에서 승인해 달라고 전한다", "같은 요청을 다시 보내지 않는다. 결과는 `get_approval_request`로 확인한다"]
+			}
+		};
+	}
+	if (result.ok && result.code === "DRY_RUN") return {
+		isError: false,
+		body: {
+			status: "DRY_RUN",
+			applied: false,
+			message: "실행하지 않았어요. 서버의 판정과 영향 미리보기예요",
+			...result.data
+		}
+	};
+	if (!result.ok) {
+		if (result.error?.code === "AGENT_OPERATION_DENIED") return {
+			isError: true,
+			body: {
+				...result,
+				nextSteps: ["에이전트는 이 작업을 할 수 없다. 다시 시도하지 말고 셀러에게 콘솔에서 직접 하도록 안내한다"]
+			}
+		};
+		return {
+			isError: true,
+			body: { ...result }
+		};
+	}
+	return {
+		isError: false,
+		body: {
+			status: result.status,
+			data: result.data
+		}
+	};
+}
 
 //#endregion
 //#region src/user-agent.ts
@@ -223,6 +341,7 @@ var AdminApi = class {
 		};
 		if (input.body !== void 0) headers["content-type"] = "application/json";
 		if (input.idempotencyKey) headers["idempotency-key"] = input.idempotencyKey;
+		if (input.dryRun) headers["x-sayren-dry-run"] = "1";
 		const response = await this.fetchImpl(url, {
 			method: input.method,
 			headers,
@@ -238,6 +357,7 @@ var AdminApi = class {
 		return response.ok ? {
 			ok: true,
 			status: response.status,
+			...payload?.meta?.code ? { code: payload.meta.code } : {},
 			data: payload?.data ?? payload
 		} : {
 			ok: false,
@@ -1067,8 +1187,21 @@ async function invoke(expected, input) {
 		path: buildPath(op.path, input.pathParams ?? {}),
 		query: input.query,
 		body: input.body,
-		idempotencyKey: input.idempotencyKey
+		idempotencyKey: input.idempotencyKey,
+		dryRun: expected === "write" && input.dryRun === true
 	});
+	if (expected === "write") {
+		const described = describeWriteResult(result);
+		if (described.isError) return {
+			...text(described.body),
+			isError: true
+		};
+		const { data: data$1, truncated: truncated$1 } = truncateData(described.body, MAX_RESPONSE_CHARS);
+		return text(truncated$1 ? {
+			...data$1,
+			truncated: truncated$1
+		} : data$1);
+	}
 	if (!result.ok) return {
 		...text(result),
 		isError: true
@@ -1095,13 +1228,14 @@ server.registerTool("call_api_read", {
 }, async (input) => invoke("read", input));
 server.registerTool("call_api_write", {
 	title: "관리 API 변경",
-	description: `POST·PUT·PATCH·DELETE 오퍼레이션을 부른다. 스토어 데이터가 실제로 바뀐다. 사용자가 요청한 변경만 한다. \`describe_operation\`에서 \`idempotencyKey: true\`인 오퍼레이션은 키를 새로 만들어 넣고, 재시도할 때는 같은 키를 쓴다. 환불로 이어지는 오퍼레이션(직권취소·클레임 승인)은 막혀 있다. ${UNTRUSTED_NOTE}`,
+	description: `POST·PUT·PATCH·DELETE 오퍼레이션을 부른다. 스토어 데이터가 실제로 바뀐다. 사용자가 요청한 변경만 한다. \`describe_operation\`에서 \`idempotencyKey: true\`인 오퍼레이션은 키를 새로 만들어 넣고, 재시도할 때는 같은 키를 쓴다. 바꾸기 전에 \`dryRun: true\`로 먼저 불러 대상·변경 전후·금액 영향과 승인 필요 여부를 사용자에게 보여 준다(서버가 실행하지 않는다). 환불·가격·할인처럼 승인이 필요한 쓰기는 서버가 승인 대기(\`APPROVAL_PENDING\`)로 두고, 셀러가 콘솔에서 승인하면 서버가 실행한다 — 결과 링크를 사용자에게 전하고 \`get_approval_request\`로 상태를 확인한다. 결제 설정·토큰 발급처럼 에이전트에게 거부된 작업은 다시 시도하지 않는다. ${UNTRUSTED_NOTE}`,
 	inputSchema: {
 		operationId: z.string().describe("`list_operations`가 준 operationId (GET 제외)"),
 		pathParams: pathParamsInput,
 		query: queryInput,
 		body: z.unknown().optional().describe("요청 본문(JSON). `describe_operation`의 body 스키마를 따른다"),
-		idempotencyKey: z.string().max(255).optional().describe("멱등키. 재시도에는 같은 값을 쓴다")
+		idempotencyKey: z.string().max(255).optional().describe("멱등키. 재시도에는 같은 값을 쓴다"),
+		dryRun: z.boolean().optional().describe("true면 실행하지 않고 서버의 판정(ALLOW·APPROVAL_REQUIRED·DENIED)과 영향 미리보기만 받는다")
 	},
 	annotations: {
 		readOnlyHint: false,
@@ -1110,6 +1244,29 @@ server.registerTool("call_api_write", {
 		openWorldHint: false
 	}
 }, async (input) => invoke("write", input));
+server.registerTool("get_approval_request", {
+	title: "승인 요청 상태",
+	description: "`call_api_write`가 승인 대기(`APPROVAL_PENDING`)로 돌려준 요청의 상태를 본다. `PENDING`은 아직 대기, `EXECUTING`은 승인 뒤 실행 중, `SUCCEEDED`·`FAILED`는 서버가 실행한 결과(`result`), `UNKNOWN`은 실행 결과를 확인하지 못함(이미 실행됐을 수 있으니 다시 보내지 말고 대상을 조회해 확인한다), `REJECTED`는 거절, `EXPIRED`는 기한(24시간) 지남이다. 승인은 셀러가 콘솔에서 한다 — 이 도구로 승인할 수 없다.",
+	inputSchema: { approvalId: z.string().describe("승인 대기 응답의 approvalId") },
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	}
+}, async ({ approvalId }) => {
+	const result = await adminApi.call({
+		method: "GET",
+		path: buildPath("/v1/approval-requests/{approvalId}", { approvalId })
+	});
+	if (!result.ok) return {
+		...text(result),
+		isError: true
+	};
+	const { data, truncated } = truncateData(result.data, MAX_RESPONSE_CHARS);
+	return text({
+		data,
+		...truncated ? { truncated } : {}
+	});
+});
 server.registerTool("verify_storefront", {
 	title: "생성 결과 검증",
 	description: "만들어진 프로젝트를 규칙과 대조한다. 결제가 조용히 실패하는 실수(브라우저 번들의 process.env, 클릭 시점 팝업 선오픈 누락, 결제 복귀 화면의 결과 확인 누락, 결과 확인 중 상태 조회 누락, 확정 배송비 미반영, 브라우저에 노출된 구매자 토큰 등)를 잡는다. 위반마다 고칠 자리(`file`·`line`)와 원인(`cause`)·수정 방법(`fix`)·예시 코드(`example`)·문서(`docUrl`)를 함께 준다. 규칙별 통과·위반은 `results`에 있다. 화면을 만든 뒤와 디자인을 고친 뒤에 부른다.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "sayren-mcp": "./dist/index.mjs"
@@ -12,7 +12,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.22.0",
     "zod": "^4.6.5",
-    "@sayren/store-sdk": "^0.13.0",
+    "@sayren/store-sdk": "^0.14.0",
     "@sayren/storefront-sdk": "^0.11.0"
   },
   "devDependencies": {

package/template/.template-meta.json

@@ -7,7 +7,7 @@
     "zod": "^4.6.5"
   },
   "versions": {
-    "@sayren/store-sdk": "0.13.0",
+    "@sayren/store-sdk": "0.14.0",
     "@sayren/storefront-sdk": "0.11.0",
     "@sayren/ui": "0.1.0"
   }