craft-stadium-mcp 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# craft-stadium-mcp
+
+CraftStadiumをClaude(Desktop/Code)から直接操作するためのMCPサーバー。組織のPersonal Access Token(PAT)で認証する。
+
+## セットアップ
+
+1. Organizeアプリの「設定 > アクセストークン」からPATを発行する。
+2. Claude Desktop/Codeの設定(`claude_desktop_config.json` または `.mcp.json`)に追加:
+
+   ```json
+   {
+     "mcpServers": {
+       "craft-stadium": {
+         "command": "npx",
+         "args": ["craft-stadium-mcp"],
+         "env": {
+           "CRAFTSTADIUM_TOKEN": "cs_pat_..."
+         }
+       }
+     }
+   }
+   ```
+
+   `npx`が都度パッケージを取得して実行するため、事前インストールは不要。デフォルトで本番API(`https://api.craftstadium.com`)に接続する。社内の開発環境(docker compose)に向けたい場合は `CRAFTSTADIUM_API_URL` に `http://localhost:8080` を追加で設定する。
+
+## 提供ツール
+
+| ツール | 内容 |
+|---|---|
+| `whoami` | 組織名・アカウント名・ロールを取得 |
+| `list_organizers` | 主催者一覧 |
+| `create_plan` | 企画作成 |
+| `list_plans` | 企画一覧 |
+| `create_hackathon` | 下書きハッカソン作成(公開設定・日程はWeb UIから編集) |
+| `list_hackathons` | 企画配下のハッカソン一覧 |
+
+## 開発
+
+```bash
+npm run dev    # tsx で直接起動
+npx tsc --noEmit  # 型チェック
+```
+
+MCP Inspectorで動作確認する場合:
+
+```bash
+npx @modelcontextprotocol/inspector npx tsx src/index.ts
+```

package/dist/client.js

@@ -0,0 +1,75 @@
+// cli/internal/client/client.go の TypeScript 版。
+export class APIError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(`${message} (status ${statusCode})`);
+        this.statusCode = statusCode;
+        this.name = "APIError";
+    }
+}
+export class Client {
+    baseURL;
+    token;
+    constructor(baseURL, token) {
+        this.baseURL = baseURL.replace(/\/+$/, "");
+        this.token = token;
+    }
+    async do(method, path, body) {
+        const headers = { "Content-Type": "application/json" };
+        if (this.token !== "") {
+            headers.Authorization = `Bearer ${this.token}`;
+        }
+        const res = await fetch(this.baseURL + path, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            // cli/internal/client/client.go の http.Client{Timeout: 30 * time.Second} に合わせる。
+            signal: AbortSignal.timeout(30_000),
+        });
+        const text = await res.text();
+        if (res.status >= 300) {
+            let message = text;
+            try {
+                const eb = JSON.parse(text);
+                if (eb.message)
+                    message = eb.message;
+            }
+            catch {
+                // レスポンスがJSONでない場合は生テキストをそのまま使う
+            }
+            throw new APIError(res.status, message);
+        }
+        if (text.length === 0) {
+            return undefined;
+        }
+        return JSON.parse(text);
+    }
+    get(path) {
+        return this.do("GET", path);
+    }
+    post(path, body) {
+        return this.do("POST", path, body);
+    }
+}
+// 外部主催者向けの既定値。社内の開発環境(docker compose)に向けたい場合は
+// CRAFTSTADIUM_API_URL=http://localhost:8080 を明示的に設定する。
+const DEFAULT_API_URL = "https://api.craftstadium.com";
+function newClient() {
+    const envURL = process.env.CRAFTSTADIUM_API_URL;
+    const baseURL = envURL && envURL !== "" ? envURL : DEFAULT_API_URL;
+    const token = process.env.CRAFTSTADIUM_TOKEN;
+    if (!token) {
+        throw new Error("CRAFTSTADIUM_TOKEN が設定されていません。MCPサーバー設定のenvにPersonal Access Tokenを指定してください。");
+    }
+    return new Client(baseURL, token);
+}
+let cached;
+// トークン未設定時のエラーをツール呼び出し時まで遅延させる。モジュール読み込み時に
+// newClient()を直接呼ぶと、MCPトランスポート接続前にプロセスがクラッシュし、
+// MCPホスト側にエラーメッセージが伝わらない。
+export function getClient() {
+    if (!cached) {
+        cached = newClient();
+    }
+    return cached;
+}

package/dist/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getClient } from "./client.js";
+import { buildCreateHackathonRequest, buildCreatePlanRequest, withTool } from "./tool-helpers.js";
+const server = new McpServer({ name: "craft-stadium", version: "1.0.0" });
+const planIdSchema = z
+    .string()
+    .min(1, "planIdを指定してください(list_plansで確認できる)")
+    .describe("企画ID(list_plansで確認できる)");
+server.tool("whoami", "現在のPATに紐づく組織名・アカウント名・ロールを取得する", {}, withTool("whoamiの取得に失敗しました", async () => {
+    const client = getClient();
+    const [org, account] = await Promise.all([
+        client.get("/organizations/my-organization"),
+        client.get("/organizations/my-organization/accounts/me"),
+    ]);
+    return {
+        organizationId: org.id,
+        organizationName: org.info.name,
+        accountId: account.id,
+        accountName: account.name,
+        role: account.role,
+    };
+}));
+server.tool("list_organizers", "組織配下の主催者一覧を取得する", {}, withTool("主催者一覧の取得に失敗しました", async () => {
+    return getClient().get("/organizations/my-organization/organizers");
+}));
+server.tool("create_plan", "新しい企画(Plan)を作成する", {
+    title: z.string().min(1, "titleを指定してください").describe("企画タイトル"),
+    organizerId: z
+        .number()
+        .int()
+        .positive("organizerIdを指定してください(list_organizersで確認できる)")
+        .describe("主催者ID(list_organizersで確認できる)"),
+    sponsorRecruitment: z.boolean().default(false).describe("スポンサー募集を有効にするか"),
+    operatingSupport: z.boolean().default(false).describe("運営サポートを有効にするか"),
+}, withTool("企画の作成に失敗しました", async ({ title, organizerId, sponsorRecruitment, operatingSupport }) => {
+    const req = buildCreatePlanRequest({ title, organizerId, sponsorRecruitment, operatingSupport });
+    return getClient().post("/plans", req);
+}));
+server.tool("list_plans", "企画(Plan)の一覧を取得する", {}, withTool("企画一覧の取得に失敗しました", async () => {
+    return getClient().get("/plans");
+}));
+server.tool("create_hackathon", "指定した企画の下に下書きハッカソンを作成する。公開設定・日程等はWeb UIから後で編集する前提。", {
+    planId: planIdSchema,
+    title: z.string().min(1, "titleを指定してください").describe("ハッカソンタイトル"),
+    displayId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("ハッカソンの表示ID(省略時はタイトルから自動生成)"),
+}, withTool("ハッカソンの作成に失敗しました", async ({ planId, title, displayId }) => {
+    const req = buildCreateHackathonRequest({ title, displayId });
+    return getClient().post(`/plans/${encodeURIComponent(planId)}/hackathons`, req);
+}));
+server.tool("list_hackathons", "指定した企画に紐づくハッカソンの一覧を取得する", {
+    planId: planIdSchema,
+}, withTool("ハッカソン一覧の取得に失敗しました", async ({ planId }) => {
+    return getClient().get(`/plans/${encodeURIComponent(planId)}/hackathons`);
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tool-helpers.js

@@ -0,0 +1,51 @@
+import { randomBytes } from "node:crypto";
+import { APIError } from "./client.js";
+// cli/cmd/hackathon.go の generateDisplayId と同じロジック(スラッグ化+ランダムサフィックス)。
+export function generateDisplayId(title) {
+    let slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    slug = slug.replace(/^-+|-+$/g, "");
+    if (slug === "")
+        slug = "hackathon";
+    const suffix = randomBytes(4).toString("hex");
+    return `${slug}-${suffix}`;
+}
+export function buildCreatePlanRequest(args) {
+    const hackathonOptions = {
+        sponsorRecruitment: args.sponsorRecruitment,
+        operatingSupport: args.operatingSupport,
+    };
+    return {
+        title: args.title,
+        organizerId: args.organizerId,
+        hackathonOptions,
+    };
+}
+// displayId省略時はgenerateDisplayIdで自動生成する。日程・selectMethodは下書き作成時は
+// 省略可 — バックエンドのapplyDraftDefaults(backend/app/internal/usecase/raid.go)が
+// 未入力のままサーバー側でデフォルト値を適用する(Issue #3339対応、PR #3347)。
+export function buildCreateHackathonRequest(args) {
+    return {
+        isPublished: false,
+        info: {
+            displayId: args.displayId ?? generateDisplayId(args.title),
+            title: args.title,
+        },
+    };
+}
+export function textResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+// 各ツールハンドラの成功時整形とエラーへのラベル付与を共通化する。
+// MCP SDK自身がツールコールバックのthrowを{content,isError:true}へ変換するため、
+// ここではエラーメッセージにどのツールで失敗したかのラベルを添えて再throwするだけでよい。
+export function withTool(label, handler) {
+    return async (args) => {
+        try {
+            return textResult(await handler(args));
+        }
+        catch (err) {
+            const message = err instanceof APIError ? err.message : err instanceof Error ? err.message : String(err);
+            throw new Error(`${label}: ${message}`);
+        }
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// cli/internal/client/types.go の TypeScript 版。フィールド形状はバックエンドのOpenAPIレスポンスに合わせている。
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "craft-stadium-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for operating CraftStadium via organization Personal Access Tokens",
+  "type": "module",
+  "bin": {
+    "craft-stadium-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "test": "node --import tsx --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.5.0"
+  }
+}