smbc-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# SMBC マルチペイメントサービス MCP サーバー
+
+SMBC マルチペイメントサービス（OpenAPI タイプ）の API 仕様を MCP リソースとして公開するサーバーです。
+
+Cursor・Claude Desktop などの MCP クライアントから API 仕様を参照できるようになります。クローンやビルドは不要で、`npx` で即利用できます。
+
+公式ドキュメント: https://docs.smbc-gp.co.jp/mulpay/docs/introduction/overview
+
+---
+
+## セットアップ
+
+### Cursor への登録
+
+グローバル設定（`~/.cursor/mcp.json`）またはプロジェクト設定（`.cursor/mcp.json`）に以下を追加します。
+
+```json
+{
+  "mcpServers": {
+    "smbc-api-docs": {
+      "command": "npx",
+      "args": ["smbc-mcp-server"],
+      "env": {
+        "SMBC_SHOP_ID": "your_shop_id",
+        "SMBC_SHOP_PASSWORD": "your_shop_password"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop への登録
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` に以下を追加します。
+
+```json
+{
+  "mcpServers": {
+    "smbc-api-docs": {
+      "command": "npx",
+      "args": ["smbc-mcp-server"],
+      "env": {
+        "SMBC_SHOP_ID": "your_shop_id",
+        "SMBC_SHOP_PASSWORD": "your_shop_password"
+      }
+    }
+  }
+}
+```
+
+設定後に MCP クライアントを再起動すると利用可能になります。
+
+---
+
+## 環境変数
+
+| 変数名 | 必須 | 説明 | デフォルト |
+|---|---|---|---|
+| `SMBC_SHOP_ID` | 必須 | ショップID | - |
+| `SMBC_SHOP_PASSWORD` | 必須 | ショップパスワード | - |
+| `SMBC_OPENAPI_PATH` | 任意 | OpenAPI ファイルのパス | パッケージ同梱の `openapi-type.yml` |
+
+---
+
+## 利用できるリソース
+
+### `smbc://index`
+
+全 API オペレーションの一覧を返します。
+
+```json
+{
+  "operations": [
+    { "operationId": "token", "method": "POST", "path": "/token", "summary": "アクセストークン発行", "requiresAuth": false },
+    { "operationId": "creditCharge", "method": "POST", "path": "/credit/charge", "summary": "クレジットカード決済", "requiresAuth": true }
+  ]
+}
+```
+
+### `smbc://operation/{operationId}`
+
+特定の API オペレーションの詳細を返します。
+
+```
+smbc://operation/token
+smbc://operation/creditCharge
+```
+
+レスポンスには `description`・`requestSchema`・`requiredFields`・`requiresAuth` などの完全な情報が含まれます。
+
+情報が見つからない場合は公式ドキュメント（https://docs.smbc-gp.co.jp/mulpay/docs/introduction/overview）への案内が返されます。
+
+---
+
+## API が更新された場合
+
+1. 新しいバージョンの本パッケージが公開されるまで待つ
+2. または `SMBC_OPENAPI_PATH` 環境変数で最新の YML ファイルを直接指定する
+
+```json
+"env": {
+  "SMBC_SHOP_ID": "your_shop_id",
+  "SMBC_SHOP_PASSWORD": "your_shop_password",
+  "SMBC_OPENAPI_PATH": "/path/to/latest/openapi-type.yml"
+}
+```
+
+---
+
+## 開発者向け
+
+```bash
+# 依存インストール
+npm install
+
+# ビルド
+npm run build
+
+# テスト
+npm test
+```

package/build/config.js

@@ -0,0 +1,6 @@
+import { fileURLToPath } from "url";
+import { join, dirname } from "path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function getOpenapiPath() {
+    return process.env.SMBC_OPENAPI_PATH ?? join(__dirname, "openapi-type.yml");
+}

package/build/error-sanitizer.js

@@ -0,0 +1,21 @@
+export function isApiError(result) {
+    return (result.startsWith("Error ") ||
+        result === "Network error occurred" ||
+        result === "Request timed out");
+}
+export function sanitizeError(e) {
+    if (e instanceof Error && e.name === "AbortError") {
+        return "Request timed out";
+    }
+    return "Network error occurred";
+}
+export function sanitizeHttpError(status, body) {
+    if (body !== null && typeof body === "object") {
+        const obj = body;
+        const title = typeof obj["title"] === "string" ? obj["title"] : undefined;
+        if (title) {
+            return `Error ${status}: ${title}`;
+        }
+    }
+    return `Error ${status}: request failed`;
+}

package/build/http-client.js

@@ -0,0 +1,90 @@
+import { sanitizeError, sanitizeHttpError } from "./error-sanitizer.js";
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 1000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function buildBasicAuth(shopId, shopPassword) {
+    const encoded = Buffer.from(`${shopId}:${shopPassword}`).toString("base64");
+    return `Basic ${encoded}`;
+}
+export async function callApi(options, config) {
+    const { method, serverUrl, path, body, contentType, idempotencyKey, requiresAuth } = options;
+    const url = `${serverUrl}${path}`;
+    const headers = {
+        "Content-Type": contentType,
+    };
+    // 認証ヘッダー
+    if (requiresAuth) {
+        if (config.accessToken) {
+            headers["Authorization"] = `Bearer ${config.accessToken}`;
+        }
+        else {
+            headers["Authorization"] = buildBasicAuth(config.shopId, config.shopPassword);
+        }
+    }
+    // 冪等キー
+    if (idempotencyKey) {
+        headers["Idempotency-Key"] = idempotencyKey;
+    }
+    // ボディ構築
+    let requestBody;
+    if (contentType === "application/x-www-form-urlencoded") {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(body)) {
+            if (v != null)
+                params.append(k, String(v));
+        }
+        requestBody = params;
+    }
+    else {
+        requestBody = JSON.stringify(body);
+    }
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        // タイムアウトは各試行でリセット
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const response = await fetch(url, {
+                method: method.toUpperCase(),
+                headers,
+                body: Object.keys(body).length > 0 ? requestBody : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            const responseText = await response.text();
+            let responseData;
+            try {
+                responseData = JSON.parse(responseText);
+            }
+            catch {
+                responseData = responseText;
+            }
+            if (response.ok) {
+                return JSON.stringify(responseData, null, 2);
+            }
+            // 4xx: リトライしない
+            if (response.status < 500) {
+                return sanitizeHttpError(response.status, responseData);
+            }
+            // 5xx: 最終試行ならエラー返却、それ以外は backoff
+            if (attempt === MAX_ATTEMPTS - 1) {
+                return sanitizeHttpError(response.status, responseData);
+            }
+            await sleep(BASE_DELAY_MS * Math.pow(2, attempt));
+        }
+        catch (e) {
+            clearTimeout(timer);
+            // タイムアウト: リトライしない
+            if (e instanceof Error && e.name === "AbortError") {
+                return sanitizeError(e);
+            }
+            // ネットワークエラー: 最終試行ならエラー返却、それ以外は backoff
+            if (attempt === MAX_ATTEMPTS - 1) {
+                return sanitizeError(e);
+            }
+            await sleep(BASE_DELAY_MS * Math.pow(2, attempt));
+        }
+    }
+    return sanitizeError(new Error("Unexpected retry exhaustion"));
+}

package/build/index.js

@@ -0,0 +1,43 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getOpenapiPath } from "./config.js";
+import { loadOperations } from "./openapi-loader.js";
+import { buildIndex, buildOperationDetail } from "./resource-handler.js";
+// 1. OpenAPI仕様書からエンドポイントを抽出
+const { operations } = await loadOperations(getOpenapiPath());
+// 2. MCPサーバー初期化
+const server = new Server({ name: "smbc-multipayment", version: "1.0.0" }, { capabilities: { resources: {} } });
+// 3. リソース一覧ハンドラー
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: [
+            {
+                uri: "smbc://index",
+                name: "SMBC API Index",
+                description: "全APIオペレーションのoperationId・メソッド・パス・summary一覧",
+                mimeType: "application/json",
+            },
+        ],
+    };
+});
+// 4. リソース読み取りハンドラー
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    if (uri === "smbc://index") {
+        return {
+            contents: [{ uri, mimeType: "application/json", text: buildIndex(operations) }],
+        };
+    }
+    const match = uri.match(/^smbc:\/\/operation\/(.+)$/);
+    if (match) {
+        const operationId = match[1];
+        return {
+            contents: [{ uri, mimeType: "application/json", text: buildOperationDetail(operations, operationId) }],
+        };
+    }
+    throw new Error(`Unknown resource URI: ${uri}`);
+});
+// 5. 起動
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/build/openapi-loader.js

@@ -0,0 +1,122 @@
+import { readFile } from "fs/promises";
+import { parse } from "yaml";
+function resolveRefs(schema, schemas, resolving = new Set()) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    const obj = schema;
+    // $ref の解決
+    if (typeof obj["$ref"] === "string") {
+        const ref = obj["$ref"];
+        // '#/components/schemas/SchemaName' 形式のみ対応
+        const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+        if (!match)
+            return schema;
+        const name = match[1];
+        if (resolving.has(name))
+            return {}; // 循環参照ガード
+        const target = schemas[name];
+        if (!target)
+            return schema;
+        const next = new Set(resolving);
+        next.add(name);
+        return resolveRefs(target, schemas, next);
+    }
+    const result = { ...obj };
+    // properties
+    if (result["properties"] && typeof result["properties"] === "object") {
+        const props = result["properties"];
+        result["properties"] = Object.fromEntries(Object.entries(props).map(([k, v]) => [k, resolveRefs(v, schemas, resolving)]));
+    }
+    // items
+    if (result["items"]) {
+        result["items"] = resolveRefs(result["items"], schemas, resolving);
+    }
+    // oneOf / anyOf / allOf
+    for (const key of ["oneOf", "anyOf", "allOf"]) {
+        if (Array.isArray(result[key])) {
+            result[key] = result[key].map((s) => resolveRefs(s, schemas, resolving));
+        }
+    }
+    return result;
+}
+export async function loadOperations(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, "utf-8");
+    }
+    catch {
+        process.stderr.write(`Error: Cannot read OpenAPI file: ${filePath}\n`);
+        process.exit(1);
+        return { operations: [], defaultServerUrl: "" }; // unreachable, for type narrowing
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let spec;
+    try {
+        spec = parse(content);
+    }
+    catch (e) {
+        process.stderr.write(`Error: Failed to parse YAML: ${e}\n`);
+        process.exit(1);
+    }
+    const schemas = spec?.components?.schemas ?? {};
+    const globalServers = spec?.servers ?? [];
+    const defaultServerUrl = globalServers[0]?.url ?? "";
+    const operations = [];
+    const paths = spec?.paths ?? {};
+    for (const [path, pathItem] of Object.entries(paths)) {
+        const pathObj = pathItem;
+        for (const method of ["get", "post", "put", "patch", "delete"]) {
+            if (!pathObj[method])
+                continue;
+            const op = pathObj[method];
+            const operationId = op["operationId"];
+            if (!operationId)
+                continue;
+            const summary = op["summary"] ?? "";
+            const description = op["description"];
+            // エンドポイント固有サーバー
+            const opServers = op["servers"];
+            const serverUrl = opServers?.[0]?.url;
+            // Idempotency-Key ヘッダー確認
+            const parameters = op["parameters"];
+            const hasIdempotencyKey = parameters?.some((p) => p["$ref"] === "#/components/parameters/headerIdempotencyKey") ?? false;
+            // 認証要否: security: [] は認証不要
+            const security = op["security"];
+            const requiresAuth = !(Array.isArray(security) && security.length === 0);
+            // リクエストボディのコンテンツタイプとスキーマ
+            const requestBody = op["requestBody"];
+            const content = requestBody?.["content"];
+            const contentType = content
+                ? (Object.keys(content).find((k) => k === "application/json") ??
+                    Object.keys(content)[0] ??
+                    "application/json")
+                : "application/json";
+            const rawSchema = content
+                ? content[contentType]?.["schema"]
+                : undefined;
+            const requestSchema = rawSchema
+                ? resolveRefs(rawSchema, schemas)
+                : undefined;
+            const resolvedSchema = requestSchema;
+            const requiredFields = Array.isArray(resolvedSchema?.["required"])
+                ? resolvedSchema["required"]
+                : undefined;
+            operations.push({
+                operationId,
+                summary,
+                description,
+                method,
+                path,
+                serverUrl,
+                defaultServerUrl,
+                requestContentType: contentType,
+                requestSchema,
+                requiredFields,
+                hasIdempotencyKey,
+                requiresAuth,
+            });
+        }
+    }
+    process.stderr.write(`Loaded ${operations.length} tools from ${filePath}\n`);
+    return { operations, defaultServerUrl };
+}