steam-game-server-mcp 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# Steam & Game Server MCP
+
+Steam 프로필, 게임 라이브러리, 동시 접속자, 게임 서버 정보를 조회하는 MCP(Model Context Protocol) 서버입니다.
+
+## 설치
+
+```bash
+npm install
+```
+
+## 환경 설정
+
+`.env` 파일을 생성하고 다음 변수를 설정하세요:
+
+```env
+STEAM_API_KEY=your_api_key_here
+STEAM_ID=your_steam_id_here
+```
+
+- **STEAM_API_KEY**: [Steam API 키](https://steamcommunity.com/dev/apikey) 발급
+- **STEAM_ID**: 17자리 Steam ID (선택)
+
+## 빌드 및 실행
+
+```bash
+# 빌드
+npm run build
+
+# 개발 모드 (tsx)
+npm run dev
+
+# 프로덕션
+npm start
+```
+
+## Cursor MCP 설정
+
+### npx 방식 (권장)
+
+```json
+{
+  "mcpServers": {
+    "steam-game-server": {
+      "command": "npx",
+      "args": ["steam-game-server-mcp@latest"],
+      "env": {
+        "STEAM_API_KEY": "your_key",
+        "STEAM_ID": "your_steam_id",
+        "STEAM_MCP_SERVERS_PATH": "C:/path/to/your/servers.json"
+      }
+    }
+  }
+}
+```
+
+- `npx steam-game-server-mcp@latest` → npm publish 후 사용 가능
+- 로컬 개발: `npx .` 또는 `node dist/index.js`
+
+## 제공 도구
+
+| 도구 | 설명 |
+|------|------|
+| `steam_resolve_vanity_url` | 커스텀 URL → SteamID 변환 |
+| `steam_get_player_summary` | 프로필 요약 (닉네임, 아바타, 상태) |
+| `steam_get_owned_games` | 보유 게임 목록 |
+| `steam_get_recently_played` | 최근 플레이 게임 |
+| `steam_get_current_players` | 앱별 동시 접속자 수 |
+| `steam_get_servers_at_address` | IP로 게임 서버 조회 |
+| `steam_get_app_news` | 앱 뉴스/패치 노트 |
+
+## 문서
+
+- [상세 명세서 (V1)](./docs/STEAM_GAME_SERVER_MCP_SPEC.md) - Steam API
+- [상세 설계 명세서 (V2)](./docs/STEAM_GAME_SERVER_MCP_SPEC_V2.md) - Game Server, RCON, Monitoring
+- [.cursor 설정 가이드](./.cursor/docs/SETUP_GUIDE.md) - Cursor AI 규칙 및 가이드

package/dist/config/servers.d.ts

@@ -0,0 +1,188 @@
+/**
+ * servers.json 로더 및 Zod 스키마 검증
+ * STEAM_MCP_SERVERS_PATH 또는 ./servers.json 경로 사용
+ */
+import { z } from "zod";
+/** 서버 단일 스키마 (Inventory 도구에서 재사용) */
+export declare const ServerSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    query: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
+    rcon: z.ZodEffects<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        port: z.ZodOptional<z.ZodNumber>;
+        passwordEnv: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        port?: number | undefined;
+        passwordEnv?: string | undefined;
+    }, {
+        port?: number | undefined;
+        enabled?: boolean | undefined;
+        passwordEnv?: string | undefined;
+    }>>, {
+        enabled: boolean;
+        port?: number | undefined;
+        passwordEnv?: string | undefined;
+    } | undefined, {
+        port?: number | undefined;
+        enabled?: boolean | undefined;
+        passwordEnv?: string | undefined;
+    } | undefined>;
+    logPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    query?: {
+        enabled: boolean;
+    } | undefined;
+    rcon?: {
+        enabled: boolean;
+        port?: number | undefined;
+        passwordEnv?: string | undefined;
+    } | undefined;
+    logPath?: string | undefined;
+}, {
+    type: string;
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    query?: {
+        enabled?: boolean | undefined;
+    } | undefined;
+    rcon?: {
+        port?: number | undefined;
+        enabled?: boolean | undefined;
+        passwordEnv?: string | undefined;
+    } | undefined;
+    logPath?: string | undefined;
+}>;
+/** 전체 설정 스키마 (Inventory 도구에서 재사용) */
+export declare const ServersConfigSchema: z.ZodObject<{
+    servers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodString;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        query: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+        }, {
+            enabled?: boolean | undefined;
+        }>>;
+        rcon: z.ZodEffects<z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            port: z.ZodOptional<z.ZodNumber>;
+            passwordEnv: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            port?: number | undefined;
+            passwordEnv?: string | undefined;
+        }, {
+            port?: number | undefined;
+            enabled?: boolean | undefined;
+            passwordEnv?: string | undefined;
+        }>>, {
+            enabled: boolean;
+            port?: number | undefined;
+            passwordEnv?: string | undefined;
+        } | undefined, {
+            port?: number | undefined;
+            enabled?: boolean | undefined;
+            passwordEnv?: string | undefined;
+        } | undefined>;
+        logPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+        name: string;
+        host: string;
+        port: number;
+        query?: {
+            enabled: boolean;
+        } | undefined;
+        rcon?: {
+            enabled: boolean;
+            port?: number | undefined;
+            passwordEnv?: string | undefined;
+        } | undefined;
+        logPath?: string | undefined;
+    }, {
+        type: string;
+        id: string;
+        name: string;
+        host: string;
+        port: number;
+        query?: {
+            enabled?: boolean | undefined;
+        } | undefined;
+        rcon?: {
+            port?: number | undefined;
+            enabled?: boolean | undefined;
+            passwordEnv?: string | undefined;
+        } | undefined;
+        logPath?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    servers: {
+        type: string;
+        id: string;
+        name: string;
+        host: string;
+        port: number;
+        query?: {
+            enabled: boolean;
+        } | undefined;
+        rcon?: {
+            enabled: boolean;
+            port?: number | undefined;
+            passwordEnv?: string | undefined;
+        } | undefined;
+        logPath?: string | undefined;
+    }[];
+}, {
+    servers: {
+        type: string;
+        id: string;
+        name: string;
+        host: string;
+        port: number;
+        query?: {
+            enabled?: boolean | undefined;
+        } | undefined;
+        rcon?: {
+            port?: number | undefined;
+            enabled?: boolean | undefined;
+            passwordEnv?: string | undefined;
+        } | undefined;
+        logPath?: string | undefined;
+    }[];
+}>;
+export type ServerConfig = z.infer<typeof ServerSchema>;
+export type ServersConfig = z.infer<typeof ServersConfigSchema>;
+/** servers.json 로드 및 검증 */
+export declare function loadServersConfig(): ServersConfig;
+/** serverId로 서버 설정 조회 */
+export declare function getServerConfig(serverId: string): ServerConfig;
+/** query가 활성화된 서버 목록 */
+export declare function getQueryableServers(): ServerConfig[];
+/**
+ * servers.json 원자적 쓰기 (temp 파일 + rename)
+ * 명세 §15.2.3: 장애 시 기존 servers.json 유지
+ */
+export declare function writeServersConfig(config: ServersConfig): void;

package/dist/config/servers.js

@@ -0,0 +1,106 @@
+/**
+ * servers.json 로더 및 Zod 스키마 검증
+ * STEAM_MCP_SERVERS_PATH 또는 ./servers.json 경로 사용
+ */
+import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+/** 서버 단일 스키마 (Inventory 도구에서 재사용) */
+export const ServerSchema = z.object({
+    id: z.string().min(1, "서버 ID는 필수입니다"),
+    name: z.string().min(1, "서버 이름은 필수입니다"),
+    type: z.string().min(1, "게임 타입은 필수입니다"),
+    host: z.string().min(1, "호스트는 필수입니다"),
+    port: z.number().int().min(1).max(65535),
+    query: z
+        .object({
+        enabled: z.boolean().optional().default(true),
+    })
+        .optional(),
+    rcon: z
+        .object({
+        enabled: z.boolean().optional().default(false),
+        port: z.number().int().min(1).max(65535).optional(),
+        passwordEnv: z.string().optional(),
+    })
+        .optional()
+        .refine((r) => {
+        if (!r || !r.enabled)
+            return true;
+        return r.port != null && r.passwordEnv != null && r.passwordEnv.length > 0;
+    }, { message: "rcon.enabled가 true일 때 port와 passwordEnv가 필요합니다" }),
+    logPath: z.string().optional(),
+});
+/** 전체 설정 스키마 (Inventory 도구에서 재사용) */
+export const ServersConfigSchema = z.object({
+    servers: z.array(ServerSchema),
+});
+/** servers.json 파일 경로 반환 (환경변수 우선) */
+function getServersPath() {
+    const envPath = process.env.STEAM_MCP_SERVERS_PATH;
+    if (envPath)
+        return resolve(envPath);
+    return resolve(process.cwd(), "servers.json");
+}
+/** servers.json 로드 및 검증 */
+export function loadServersConfig() {
+    const path = getServersPath();
+    if (!existsSync(path)) {
+        throw new Error("servers.json을 찾을 수 없습니다.");
+    }
+    const raw = readFileSync(path, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("servers.json 형식이 올바르지 않습니다: JSON 파싱 실패");
+    }
+    const result = ServersConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const details = result.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join("; ");
+        throw new Error(`servers.json 형식이 올바르지 않습니다: ${details}`);
+    }
+    return result.data;
+}
+/** serverId로 서버 설정 조회 */
+export function getServerConfig(serverId) {
+    const config = loadServersConfig();
+    const server = config.servers.find((s) => s.id === serverId);
+    if (!server) {
+        throw new Error("등록되지 않은 서버 ID입니다.");
+    }
+    return server;
+}
+/** query가 활성화된 서버 목록 */
+export function getQueryableServers() {
+    const config = loadServersConfig();
+    return config.servers.filter((s) => s.query?.enabled !== false);
+}
+/**
+ * servers.json 원자적 쓰기 (temp 파일 + rename)
+ * 명세 §15.2.3: 장애 시 기존 servers.json 유지
+ */
+export function writeServersConfig(config) {
+    const path = getServersPath();
+    const tmpPath = path.replace(/\.json$/, ".tmp.json");
+    try {
+        const content = JSON.stringify(config, null, 2);
+        writeFileSync(tmpPath, content, "utf-8");
+    }
+    catch {
+        throw new Error("servers.json을 임시 파일에 저장하는 데 실패했습니다. 디스크 공간과 권한을 확인하세요.");
+    }
+    try {
+        renameSync(tmpPath, path);
+    }
+    catch {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            /* tmp 정리 실패 무시 */
+        }
+        throw new Error("servers.json 업데이트에 실패했습니다. 파일 시스템 권한 또는 잠금 상태를 확인하세요.");
+    }
+}

package/dist/game-server/cache.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 서버 쿼리 캐시 - TTL 30초 (명세 §6.2)
+ */
+import type { ServerState } from "./types.js";
+/** 캐시 TTL (ms) */
+export declare const CACHE_TTL = 30000;
+export declare function getCached(serverId: string): ServerState | null;
+export declare function setCache(serverId: string, data: ServerState): void;
+export declare function invalidateCache(serverId: string): void;

package/dist/game-server/cache.js

@@ -0,0 +1,22 @@
+/**
+ * 서버 쿼리 캐시 - TTL 30초 (명세 §6.2)
+ */
+/** 캐시 TTL (ms) */
+export const CACHE_TTL = 30_000;
+const cache = new Map();
+export function getCached(serverId) {
+    const cached = cache.get(serverId);
+    if (!cached)
+        return null;
+    if (Date.now() - cached.ts >= CACHE_TTL) {
+        cache.delete(serverId);
+        return null;
+    }
+    return cached.data;
+}
+export function setCache(serverId, data) {
+    cache.set(serverId, { data, ts: Date.now() });
+}
+export function invalidateCache(serverId) {
+    cache.delete(serverId);
+}

package/dist/game-server/dedup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 동시 쿼리 Dedup - pendingQueries Map (명세 §6.3)
+ */
+import type { ServerState } from "./types.js";
+/** 캐시 + Dedup 적용 쿼리 */
+export declare function queryWithDedup(serverId: string): Promise<ServerState>;

package/dist/game-server/dedup.js

@@ -0,0 +1,27 @@
+/**
+ * 동시 쿼리 Dedup - pendingQueries Map (명세 §6.3)
+ */
+import { queryServer } from "./query.js";
+import { getCached, setCache } from "./cache.js";
+const pendingQueries = new Map();
+/** 캐시 + Dedup 적용 쿼리 */
+export async function queryWithDedup(serverId) {
+    const cached = getCached(serverId);
+    if (cached)
+        return cached;
+    const existing = pendingQueries.get(serverId);
+    if (existing)
+        return existing;
+    const promise = queryServer(serverId)
+        .then((result) => {
+        setCache(serverId, result);
+        pendingQueries.delete(serverId);
+        return result;
+    })
+        .catch((err) => {
+        pendingQueries.delete(serverId);
+        throw err;
+    });
+    pendingQueries.set(serverId, promise);
+    return promise;
+}

package/dist/game-server/normalize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * gamedig raw 결과 → ServerState 정규화 (명세 §5.3)
+ */
+import type { ServerState, LatencyCategory } from "./types.js";
+/** gamedig v5 결과 타입 (Results + 확장) */
+export interface GamedigResult {
+    name?: string;
+    map?: string;
+    players?: Array<{
+        name?: string;
+        score?: number;
+        time?: number;
+        raw?: Record<string, unknown>;
+    }>;
+    numplayers?: number;
+    maxplayers?: number;
+    ping?: number;
+    type?: string;
+    raw?: Record<string, string | number | unknown>;
+}
+/** ping → LatencyCategory (명세 §5.2) */
+export declare function getLatencyCategory(ping: number): LatencyCategory;
+/** gamedig raw → ServerState 변환 */
+export declare function normalize(raw: GamedigResult, serverId: string): ServerState;

package/dist/game-server/normalize.js

@@ -0,0 +1,38 @@
+/**
+ * gamedig raw 결과 → ServerState 정규화 (명세 §5.3)
+ */
+/** ping → LatencyCategory (명세 §5.2) */
+export function getLatencyCategory(ping) {
+    if (ping < 0)
+        return "CRITICAL";
+    if (ping <= 100)
+        return "GOOD";
+    if (ping <= 200)
+        return "NORMAL";
+    if (ping <= 300)
+        return "HIGH";
+    return "CRITICAL";
+}
+/** gamedig raw → ServerState 변환 */
+export function normalize(raw, serverId) {
+    const ping = raw.ping ?? -1;
+    const playerList = raw.players?.map((p) => ({
+        name: p.name ?? "Unknown",
+        score: p.score,
+        time: p.time,
+    }));
+    const playerCount = raw.players?.length ?? raw.numplayers ?? 0;
+    return {
+        id: serverId,
+        name: (raw.name ?? "Unknown").trim(),
+        map: raw.map ?? "Unknown",
+        players: playerCount,
+        maxPlayers: raw.maxplayers ?? 0,
+        ping,
+        game: raw.raw?.game ?? raw.type ?? "unknown",
+        latencyCategory: getLatencyCategory(ping),
+        playerList: playerList?.length ? playerList : undefined,
+        rules: raw.raw,
+        queriedAt: new Date().toISOString(),
+    };
+}

package/dist/game-server/query.d.ts

@@ -0,0 +1,8 @@
+/**
+ * gamedig 쿼리 + timeout 래핑 (명세 §6.4)
+ */
+import type { ServerState } from "./types.js";
+/** 쿼리 타임아웃 (ms) */
+export declare const QUERY_TIMEOUT = 5000;
+/** 단일 서버 쿼리 (캐시/딥 없음) */
+export declare function queryServer(serverId: string): Promise<ServerState>;

package/dist/game-server/query.js

@@ -0,0 +1,36 @@
+/**
+ * gamedig 쿼리 + timeout 래핑 (명세 §6.4)
+ */
+import { GameDig } from "gamedig";
+import { getServerConfig } from "../config/servers.js";
+import { normalize } from "./normalize.js";
+/** 쿼리 타임아웃 (ms) */
+export const QUERY_TIMEOUT = 5_000;
+function timeout(ms) {
+    return new Promise((_, reject) => setTimeout(() => reject(new Error("서버 응답 시간 초과")), ms));
+}
+/** 단일 서버 쿼리 (캐시/딥 없음) */
+export async function queryServer(serverId) {
+    const config = getServerConfig(serverId);
+    if (config.query?.enabled === false) {
+        throw new Error("해당 서버는 쿼리가 비활성화되어 있습니다.");
+    }
+    try {
+        const raw = await Promise.race([
+            GameDig.query({
+                type: config.type,
+                host: config.host,
+                port: config.port,
+            }),
+            timeout(QUERY_TIMEOUT),
+        ]);
+        return normalize(raw, serverId);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "게임 서버 쿼리 실패";
+        if (message.includes("timeout") || message.includes("시간 초과")) {
+            throw new Error("서버 응답 시간 초과");
+        }
+        throw new Error(`게임 서버 쿼리 실패: ${message}`);
+    }
+}

package/dist/game-server/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 게임 서버 데이터 모델 (명세 §5)
+ */
+/** ping 기반 지연 카테고리 */
+export type LatencyCategory = "GOOD" | "NORMAL" | "HIGH" | "CRITICAL";
+/** 서버 상태 (정규화된 형태) */
+export interface ServerState {
+    id: string;
+    name: string;
+    map: string;
+    players: number;
+    maxPlayers: number;
+    ping: number;
+    game: string;
+    latencyCategory: LatencyCategory;
+    playerList?: ServerPlayer[];
+    rules?: Record<string, string>;
+    queriedAt: string;
+}
+/** 플레이어 정보 */
+export interface ServerPlayer {
+    name: string;
+    score?: number;
+    time?: number;
+}
+/** HealthStatus (server_health, server_diagnose) */
+export type HealthStatus = "GOOD" | "WARNING" | "HIGH_LOAD" | "CRITICAL";

package/dist/game-server/types.js

@@ -0,0 +1,4 @@
+/**
+ * 게임 서버 데이터 모델 (명세 §5)
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Steam & Game Server MCP 서버
+ * .env의 STEAM_API_KEY, STEAM_ID 사용
+ */
+import "dotenv/config";