@awarecorp/mcp-logger 0.0.2-dev.1 → 0.0.2-dev.3

package/README.md

@@ -284,19 +284,30 @@ MIT
 
 ## 📦 배포 (Maintainers Only)
 
-### Stable 버전 배포
+**권장:** GitHub Actions를 사용한 자동 배포
+
+### 자동 배포 (GitHub Actions) ⭐
 ```bash
-npm run version:patch    # 또는 minor, major
-npm run publish:stable
+# Dev 버전 (develop 브랜치)
+git checkout develop
+npm run version:dev
+git push origin develop --tags
 ```
 
-### Dev 버전 배포
+자세한 가이드:
+- [GITHUB_SETUP.md](./GITHUB_SETUP.md) - Repository 초기 설정
+- [GITHUB_ACTIONS.md](./GITHUB_ACTIONS.md) - 자동 배포 사용법
+
+### 수동 배포 (로컬)
 ```bash
+# Dev 버전
 npm run version:dev
 npm run publish:dev
 ```
 
-자세한 내용은 [DEVELOPMENT.md](./DEVELOPMENT.md#배포)를 참조하세요.
+**참고:** Stable 버전은 아직 지원하지 않습니다.
+
+자세한 개발 가이드: [DEVELOPMENT.md](./DEVELOPMENT.md)
 
 ---
 

package/dist/cli/cli.js

@@ -1,85 +1,2 @@
 #!/usr/bin/env node
-/**
- * MCP Logger CLI
- *
- * MCP 서버를 래핑하여 자동으로 observability를 추가합니다.
- */
-import { spawn } from 'child_process';
-import { program } from 'commander';
-import { initializeTelemetry, shutdownTelemetry } from '../shared/telemetry.js';
-import { MessageInterceptor } from './interceptor.js';
-program
-    .name('mcp-logger')
-    .description('Add observability to any MCP server without code changes')
-    .version('1.0.0')
-    .requiredOption('-k, --api-key <key>', 'Aware API key')
-    .option('-s, --service-name <name>', 'Service name for identification')
-    .option('-d, --debug', 'Enable debug logging', false)
-    .option('-e, --endpoint <url>', 'Custom OTLP endpoint')
-    .argument('<command...>', 'MCP server command to wrap')
-    .action(async (command, options) => {
-    try {
-        // 1. Telemetry 초기화
-        initializeTelemetry(options);
-        if (options.debug) {
-            console.error('[MCP Logger CLI] Starting MCP server:', command.join(' '));
-        }
-        // 2. MCP 서버 실행
-        const [cmd, ...args] = command;
-        const mcpServer = spawn(cmd, args, {
-            stdio: ['pipe', 'pipe', 'inherit'], // stdin, stdout, stderr
-            env: {
-                ...process.env,
-                // Trace context 전파 (향후 사용)
-                MCP_LOGGER_ENABLED: 'true',
-            },
-        });
-        // 3. stdin 가로채기 (Claude → MCP Server)
-        const requestInterceptor = new MessageInterceptor('request', options.debug);
-        process.stdin.pipe(requestInterceptor).pipe(mcpServer.stdin);
-        // 4. stdout 가로채기 (MCP Server → Claude)
-        const responseInterceptor = new MessageInterceptor('response', options.debug);
-        mcpServer.stdout.pipe(responseInterceptor).pipe(process.stdout);
-        // 5. 에러 처리
-        mcpServer.on('error', async (err) => {
-            console.error('[MCP Logger CLI] Failed to start MCP server:', err);
-            await shutdownTelemetry();
-            process.exit(1);
-        });
-        mcpServer.on('exit', async (code, signal) => {
-            if (options.debug) {
-                console.error(`[MCP Logger CLI] MCP server exited with code ${code}, signal ${signal}`);
-            }
-            await shutdownTelemetry();
-            process.exit(code || 0);
-        });
-        // 6. 시그널 처리 - 한 번만 처리
-        let isShuttingDown = false;
-        const handleShutdown = async (signal) => {
-            if (isShuttingDown)
-                return;
-            isShuttingDown = true;
-            if (options.debug) {
-                console.error(`[MCP Logger CLI] Received ${signal}, shutting down...`);
-            }
-            mcpServer.kill(signal);
-            // MCP 서버가 종료될 때까지 대기 (최대 5초)
-            await Promise.race([
-                new Promise(resolve => mcpServer.once('exit', resolve)),
-                new Promise(resolve => setTimeout(resolve, 5000))
-            ]);
-            await shutdownTelemetry();
-            process.exit(0);
-        };
-        process.on('SIGTERM', () => handleShutdown('SIGTERM'));
-        process.on('SIGINT', () => handleShutdown('SIGINT'));
-    }
-    catch (err) {
-        console.error('[MCP Logger CLI] Fatal error:', err);
-        await shutdownTelemetry();
-        process.exit(1);
-    }
-});
-// CLI 실행
-program.parse();
-//# sourceMappingURL=cli.js.map
+import{spawn as e}from"child_process";import{program as r}from"commander";import{NodeSDK as t}from"@opentelemetry/sdk-node";import{OTLPTraceExporter as o}from"@opentelemetry/exporter-trace-otlp-http";import{Resource as s}from"@opentelemetry/resources";import{trace as i,SpanStatusCode as n}from"@opentelemetry/api";import{Transform as c}from"stream";const a="https://aware.mcypher.com/v1/traces",p="1.0.0";let g=null,d=null,m=!1;function l(){return d}async function u(){if(g)try{await g.shutdown(),g=null,d=null,m=!1}catch(e){console.error("[MCP Logger] Error shutting down telemetry:",e)}}function h(e,r=1e4){try{const t=JSON.stringify(e);return t.length>r?t.slice(0,r)+"... (truncated)":t}catch(e){return null}}class f extends c{buffer="";direction;debug;constructor(e,r=!1){super(),this.direction=e,this.debug=r}_transform(e,r,t){try{this.push(e),this.buffer+=e.toString(),this.buffer.length>1e6&&(this.debug&&console.error("[MCP Logger CLI] Buffer size exceeded, clearing..."),this.buffer=""),this.tryParseMessages(),t()}catch(e){t(e)}}tryParseMessages(){const e=this.buffer.split("\n");this.buffer=e.pop()||"";for(const r of e){const e=r.trim();if(e)try{const r=JSON.parse(e);this.traceMessage(r).catch(e=>{this.debug&&console.error("[MCP Logger CLI] Trace error:",e)})}catch(r){this.debug&&console.error("[MCP Logger CLI] Failed to parse:",e)}}}async traceMessage(e){const r=l();if(!r)return void(this.debug&&console.error("[MCP Logger CLI] Tracer not initialized"));const t=e.method?`mcp.${e.method}`:void 0!==e.id?"mcp.response":"mcp.notification";return new Promise(o=>{r.startActiveSpan(t,r=>{try{if(function(e,r){for(const[t,o]of Object.entries(r))null!=o&&e.setAttribute(t,o)}(r,{"mcp.direction":this.direction,"mcp.jsonrpc":e.jsonrpc||"2.0"}),void 0!==e.id&&r.setAttribute("mcp.id",String(e.id)),e.method&&r.setAttribute("mcp.method",e.method),e.params){const t=h(e.params);t&&(r.setAttribute("mcp.params.size",t.length),t.length<1e3&&r.setAttribute("mcp.params",t))}const t=h(e);t&&function(e,r,t,o){try{t?e.addEvent(r,t):e.addEvent(r)}catch(e){o&&console.error("[MCP Logger] Failed to add span event:",e)}}(r,`mcp.${this.direction}`,{message:t,timestamp:Date.now()},this.debug),this.debug&&console.error(`[MCP Logger CLI] ${this.direction}:`,JSON.stringify(e,null,2)),e.error?(r.setAttribute("mcp.error",!0),r.setAttribute("mcp.error.code",e.error.code),r.setAttribute("mcp.error.message",e.error.message),r.setStatus({code:n.ERROR,message:e.error.message})):function(e){e.setStatus({code:n.OK})}(r)}catch(e){this.debug&&console.error("[MCP Logger CLI] Error in span:",e),r.setStatus({code:n.ERROR,message:String(e)})}finally{r.end(),o()}})})}_flush(e){try{if(this.buffer.trim())try{const e=JSON.parse(this.buffer);this.traceMessage(e).catch(e=>{this.debug&&console.error("[MCP Logger CLI] Trace error:",e)})}catch(e){this.debug&&console.error("[MCP Logger CLI] Failed to parse final buffer:",e)}e()}catch(r){e(r)}}}r.name("mcp-logger").description("Add observability to any MCP server without code changes").version("1.0.0").requiredOption("-k, --api-key <key>","Aware API key").option("-s, --service-name <name>","Service name for identification").option("-e, --endpoint <url>","Custom OTLP endpoint").argument("<command...>","MCP server command to wrap").action(async(r,n)=>{try{const c=!0;!function(e){if(m)return console.error("[MCP Logger] Telemetry already initialized, returning existing tracer"),d;const r=e.serviceName||`mcp-server-${Math.random().toString(36).slice(2,8)}`;console.error("[MCP Logger] Initializing telemetry..."),console.error(`[MCP Logger] Endpoint: ${e.endpoint||a}`),console.error(`[MCP Logger] Service: ${r}`),g=new t({resource:new s({"service.name":r,"service.version":p}),traceExporter:new o({url:e.endpoint||a,headers:{"x-api-key":e.apiKey}})}),g.start(),d=i.getTracer("mcp-logger",p),m=!0,console.error("[MCP Logger] Telemetry initialized successfully");const n=async()=>{console.error("[MCP Logger] Shutting down telemetry..."),await u()};process.once("SIGTERM",n),process.once("SIGINT",n)}({...n,debug:c}),console.error("[MCP Logger CLI] Starting MCP server:",r.join(" "));const[l,...h]=r,C=e(l,h,{stdio:["pipe","pipe","inherit"],env:{...process.env,MCP_LOGGER_ENABLED:"true"}}),y=new f("request",c);process.stdin.pipe(y).pipe(C.stdin);const L=new f("response",c);C.stdout.pipe(L).pipe(process.stdout),C.on("error",async e=>{console.error("[MCP Logger CLI] Failed to start MCP server:",e),await u(),process.exit(1)}),C.on("exit",async(e,r)=>{console.error(`[MCP Logger CLI] MCP server exited with code ${e}, signal ${r}`),await u(),process.exit(e||0)});let M=!1;const P=async e=>{M||(M=!0,console.error(`[MCP Logger CLI] Received ${e}, shutting down...`),C.kill(e),await Promise.race([new Promise(e=>C.once("exit",e)),new Promise(e=>setTimeout(e,5e3))]),await u(),process.exit(0))};process.on("SIGTERM",()=>P("SIGTERM")),process.on("SIGINT",()=>P("SIGINT"))}catch(e){console.error("[MCP Logger CLI] Fatal error:",e),await u(),process.exit(1)}}),r.parse();

package/dist/cli/interceptor.js

@@ -1,170 +1 @@
-/**
- * JSON-RPC 메시지 가로채기 및 추적
- *
- * stdin/stdout을 통과하는 JSON-RPC 메시지를 파싱하여 OpenTelemetry로 추적합니다.
- */
-import { Transform } from 'stream';
-import { SpanStatusCode } from '@opentelemetry/api';
-import { getTracer } from '../shared/telemetry.js';
-import { setSpanAttributes, addSpanEvent, markSpanSuccess, safeStringify } from '../shared/span-utils.js';
-/**
- * JSON-RPC 메시지 파싱 및 로깅을 위한 Transform stream
- */
-export class MessageInterceptor extends Transform {
-    buffer = '';
-    direction;
-    debug;
-    constructor(direction, debug = false) {
-        super();
-        this.direction = direction;
-        this.debug = debug;
-    }
-    _transform(chunk, encoding, callback) {
-        try {
-            // 원본 데이터는 그대로 전달
-            this.push(chunk);
-            // 로깅을 위한 파싱 (비동기)
-            this.buffer += chunk.toString();
-            // 버퍼 크기 제한 (메모리 누수 방지)
-            if (this.buffer.length > 1_000_000) { // 1MB
-                if (this.debug) {
-                    console.error('[MCP Logger CLI] Buffer size exceeded, clearing...');
-                }
-                this.buffer = '';
-            }
-            this.tryParseMessages();
-            callback();
-        }
-        catch (err) {
-            callback(err);
-        }
-    }
-    /**
-     * 버퍼에서 JSON-RPC 메시지 파싱 시도
-     */
-    tryParseMessages() {
-        const lines = this.buffer.split('\n');
-        // 마지막 불완전한 라인은 버퍼에 보관
-        this.buffer = lines.pop() || '';
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            try {
-                const message = JSON.parse(trimmed);
-                // OpenTelemetry로 로깅 (비동기지만 blocking하지 않음)
-                this.traceMessage(message).catch(err => {
-                    if (this.debug) {
-                        console.error('[MCP Logger CLI] Trace error:', err);
-                    }
-                });
-            }
-            catch (err) {
-                // JSON 파싱 실패는 무시 (MCP 메시지가 아닐 수 있음)
-                if (this.debug) {
-                    console.error('[MCP Logger CLI] Failed to parse:', trimmed);
-                }
-            }
-        }
-    }
-    /**
-     * 메시지를 OpenTelemetry span으로 추적
-     */
-    async traceMessage(message) {
-        const tracer = getTracer();
-        if (!tracer) {
-            if (this.debug) {
-                console.error('[MCP Logger CLI] Tracer not initialized');
-            }
-            return;
-        }
-        const spanName = message.method
-            ? `mcp.${message.method}`
-            : message.id !== undefined
-                ? 'mcp.response'
-                : 'mcp.notification';
-        return new Promise((resolve) => {
-            tracer.startActiveSpan(spanName, (span) => {
-                try {
-                    // 기본 속성 설정
-                    setSpanAttributes(span, {
-                        'mcp.direction': this.direction,
-                        'mcp.jsonrpc': message.jsonrpc || '2.0',
-                    });
-                    if (message.id !== undefined) {
-                        span.setAttribute('mcp.id', String(message.id));
-                    }
-                    if (message.method) {
-                        span.setAttribute('mcp.method', message.method);
-                    }
-                    // params 처리
-                    if (message.params) {
-                        const paramsStr = safeStringify(message.params);
-                        if (paramsStr) {
-                            span.setAttribute('mcp.params.size', paramsStr.length);
-                            if (paramsStr.length < 1000) {
-                                span.setAttribute('mcp.params', paramsStr);
-                            }
-                        }
-                    }
-                    // 이벤트 기록
-                    const messageStr = safeStringify(message);
-                    if (messageStr) {
-                        addSpanEvent(span, `mcp.${this.direction}`, {
-                            message: messageStr,
-                            timestamp: Date.now(),
-                        }, this.debug);
-                    }
-                    if (this.debug) {
-                        console.error(`[MCP Logger CLI] ${this.direction}:`, JSON.stringify(message, null, 2));
-                    }
-                    // 에러 체크
-                    if (message.error) {
-                        span.setAttribute('mcp.error', true);
-                        span.setAttribute('mcp.error.code', message.error.code);
-                        span.setAttribute('mcp.error.message', message.error.message);
-                        span.setStatus({ code: SpanStatusCode.ERROR, message: message.error.message });
-                    }
-                    else {
-                        markSpanSuccess(span);
-                    }
-                }
-                catch (err) {
-                    if (this.debug) {
-                        console.error('[MCP Logger CLI] Error in span:', err);
-                    }
-                    span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
-                }
-                finally {
-                    span.end();
-                    resolve();
-                }
-            });
-        });
-    }
-    _flush(callback) {
-        try {
-            // 남은 버퍼 처리
-            if (this.buffer.trim()) {
-                try {
-                    const message = JSON.parse(this.buffer);
-                    this.traceMessage(message).catch(err => {
-                        if (this.debug) {
-                            console.error('[MCP Logger CLI] Trace error:', err);
-                        }
-                    });
-                }
-                catch (err) {
-                    if (this.debug) {
-                        console.error('[MCP Logger CLI] Failed to parse final buffer:', err);
-                    }
-                }
-            }
-            callback();
-        }
-        catch (err) {
-            callback(err);
-        }
-    }
-}
-//# sourceMappingURL=interceptor.js.map
+import{Transform as e}from"stream";import"@opentelemetry/api";import"@opentelemetry/sdk-node";import"@opentelemetry/exporter-trace-otlp-http";import"@opentelemetry/resources";class r extends e{buffer="";direction;debug;constructor(e,r=!1){super(),this.direction=e,this.debug=r}_transform(e,r,t){try{this.push(e),this.buffer+=e.toString(),this.buffer.length>1e6&&(this.debug&&console.error("[MCP Logger CLI] Buffer size exceeded, clearing..."),this.buffer=""),this.tryParseMessages(),t()}catch(e){t(e)}}tryParseMessages(){const e=this.buffer.split("\n");this.buffer=e.pop()||"";for(const r of e){const e=r.trim();if(e)try{const r=JSON.parse(e);this.traceMessage(r).catch(e=>{this.debug&&console.error("[MCP Logger CLI] Trace error:",e)})}catch(r){this.debug&&console.error("[MCP Logger CLI] Failed to parse:",e)}}}async traceMessage(e){this.debug&&console.error("[MCP Logger CLI] Tracer not initialized")}_flush(e){try{if(this.buffer.trim())try{const e=JSON.parse(this.buffer);this.traceMessage(e).catch(e=>{this.debug&&console.error("[MCP Logger CLI] Trace error:",e)})}catch(e){this.debug&&console.error("[MCP Logger CLI] Failed to parse final buffer:",e)}e()}catch(r){e(r)}}}export{r as MessageInterceptor};

package/dist/index.d.ts

@@ -1,15 +1,115 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
 /**
- * @awarecorp/mcp-logger
+ * 공통 타입 정의
+ */
+/**
+ * 텔레메트리 초기화 옵션
+ */
+interface TelemetryOptions {
+    /**
+     * API Key for authentication (필수)
+     */
+    apiKey: string;
+    /**
+     * 서비스 이름 (옵션)
+     * 지정하지 않으면 자동으로 'mcp-server-{random}' 형식으로 생성
+     */
+    serviceName?: string;
+    /**
+     * 커스텀 OTLP 엔드포인트 (옵션)
+     * 기본값: CONFIG.ENDPOINT
+     */
+    endpoint?: string;
+    /**
+     * 디버그 로그 활성화 (옵션)
+     */
+    debug?: boolean;
+}
+
+/**
+ * SDK 타입 정의
+ */
+
+/**
+ * SDK 초기화 옵션 (TelemetryOptions 확장)
+ */
+interface SDKInitOptions extends TelemetryOptions {
+}
+/**
+ * MCP Server 타입 (재export)
+ */
+type MCPServer = Server;
+
+/**
+ * 공통 텔레메트리 레이어
+ *
+ * OpenTelemetry SDK 초기화 및 관리를 담당합니다.
+ * SDK와 CLI 양쪽에서 공통으로 사용됩니다.
+ */
+
+/**
+ * Telemetry 종료
+ */
+declare function shutdownTelemetry(): Promise<void>;
+
+/**
+ * MCP Logger SDK
+ *
+ * MCP 서버에 자동 관측성(Observability)을 추가하는 SDK입니다.
+ */
+
+/**
+ * MCP 서버에 자동 계측을 추가합니다.
+ *
+ * 이 함수는 MCP 서버의 모든 요청/응답을 자동으로 로깅하고 추적합니다.
+ * OpenTelemetry를 사용하여 traces를 수집하며, 설정된 엔드포인트로 전송합니다.
+ *
+ * @param server - MCP Server 인스턴스
+ * @param options - 초기화 옵션
+ *
+ * @throws {Error} apiKey가 제공되지 않은 경우
+ * @throws {Error} server 인스턴스가 제공되지 않은 경우
+ *
+ * @example
+ * TypeScript 사용 예시:
+ * ```typescript
+ * import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+ * import { initMCPLogger } from '@awarecorp/mcp-logger';
+ *
+ * const server = new Server({ name: 'my-server', version: '1.0.0' }, {
+ *   capabilities: { tools: {} }
+ * });
+ *
+ * initMCPLogger(server, {
+ *   apiKey: 'your-api-key',
+ *   serviceName: 'my-mcp-server',
+ *   debug: true,
+ * });
+ *
+ * server.setRequestHandler('tools/call', async (request) => {
+ *   // 이 핸들러는 자동으로 로깅됩니다
+ *   return { result: 'success' };
+ * });
+ * ```
  *
- * Unified MCP observability solution
+ * @example
+ * JavaScript 사용 예시:
+ * ```javascript
+ * const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+ * const { initMCPLogger } = require('@awarecorp/mcp-logger');
  *
- * This package provides:
- * 1. SDK: For programmatic integration into MCP servers
- * 2. CLI: For wrapping existing MCP servers without code changes
+ * const server = new Server({ name: 'my-server', version: '1.0.0' }, {
+ *   capabilities: { tools: {} }
+ * });
  *
- * NOTE: This entry point ONLY exports the SDK.
- * CLI functionality is available through the `mcp-logger` binary.
+ * initMCPLogger(server, {
+ *   apiKey: process.env.API_KEY,
+ *   serviceName: 'my-mcp-server',
+ * });
+ * ```
  */
-export { initMCPLogger, shutdown } from './sdk/index.js';
-export type { SDKInitOptions, MCPServer } from './sdk/types.js';
-//# sourceMappingURL=index.d.ts.map
+declare function initMCPLogger(server: MCPServer, options: SDKInitOptions): void;
+
+export { initMCPLogger, shutdownTelemetry as shutdown };
+export type { MCPServer, SDKInitOptions };

package/dist/index.js

@@ -1,21 +1 @@
-/**
- * @awarecorp/mcp-logger
- *
- * Unified MCP observability solution
- *
- * This package provides:
- * 1. SDK: For programmatic integration into MCP servers
- * 2. CLI: For wrapping existing MCP servers without code changes
- *
- * NOTE: This entry point ONLY exports the SDK.
- * CLI functionality is available through the `mcp-logger` binary.
- */
-// ============================================================================
-// SDK Exports (PUBLIC API)
-// ============================================================================
-export { initMCPLogger, shutdown } from './sdk/index.js';
-// ============================================================================
-// CLI is NOT exported here
-// Access via: npx @awarecorp/mcp-logger --api-key xxx -- <command>
-// ============================================================================
-//# sourceMappingURL=index.js.map
+import{NodeSDK as e}from"@opentelemetry/sdk-node";import{OTLPTraceExporter as r}from"@opentelemetry/exporter-trace-otlp-http";import{Resource as t}from"@opentelemetry/resources";import{trace as o,SpanStatusCode as n}from"@opentelemetry/api";const s="https://aware.mcypher.com/v1/traces",c="1.0.0";let i=null,a=null,l=!1;function u(){return a}async function g(){if(i)try{await i.shutdown(),i=null,a=null,l=!1}catch(e){console.error("[MCP Logger] Error shutting down telemetry:",e)}}function m(e,r){for(const[t,o]of Object.entries(r))null!=o&&e.setAttribute(t,o)}function p(e,r,t,o){try{t?e.addEvent(r,t):e.addEvent(r)}catch(e){o&&console.error("[MCP Logger] Failed to add span event:",e)}}function d(e,r=1e4){try{const t=JSON.stringify(e);return t.length>r?t.slice(0,r)+"... (truncated)":t}catch(e){return null}}function h(h,f){if(!f.apiKey)throw new Error("[MCP Logger SDK] apiKey is required");if(!h)throw new Error("[MCP Logger SDK] server instance is required");!function(n){if(l)return n.debug&&console.error("[MCP Logger] Telemetry already initialized, returning existing tracer"),a;const u=n.serviceName||`mcp-server-${Math.random().toString(36).slice(2,8)}`;n.debug&&(console.error("[MCP Logger] Initializing telemetry..."),console.error(`[MCP Logger] Endpoint: ${n.endpoint||s}`),console.error(`[MCP Logger] Service: ${u}`)),i=new e({resource:new t({"service.name":u,"service.version":c}),traceExporter:new r({url:n.endpoint||s,headers:{"x-api-key":n.apiKey}})}),i.start(),a=o.getTracer("mcp-logger",c),l=!0,n.debug&&console.error("[MCP Logger] Telemetry initialized successfully");const m=async()=>{n.debug&&console.error("[MCP Logger] Shutting down telemetry..."),await g()};process.once("SIGTERM",m),process.once("SIGINT",m)}(f),function(e,r=!1){const t=u();if(!t)throw new Error("[MCP Logger SDK] Tracer not initialized. Call initMCPLogger first.");const o=e.setRequestHandler.bind(e);e.setRequestHandler=function(e,s){const c=e.shape?.method,i=c?._def?.value||"unknown";return r&&console.log(`[MCP Logger SDK] Instrumenting handler: ${i}`),o(e,async(e,o)=>{const c=`mcp.${i}`;return await t.startActiveSpan(c,{attributes:{"mcp.method":i,"mcp.request.method":e.method}},async t=>{const c=Date.now();try{const i=d(e.params||{});m(t,{"mcp.request.id":"unknown","mcp.request.params.size":i?.length}),i&&i.length<1e3&&t.setAttribute("mcp.request.params",i),p(t,"mcp.request.received",{"request.method":e.method,"request.timestamp":c},r),r&&console.log("[MCP Logger SDK] Request received:",{method:e.method,params:e.params});const a=await s(e,o),l=Date.now(),u=l-c,g=d(a);return m(t,{"mcp.duration_ms":u,"mcp.response.size":g?.length}),g&&g.length<1e3&&t.setAttribute("mcp.response.result",g),p(t,"mcp.response.sent",{"response.timestamp":l,"response.duration_ms":u},r),function(e){e.setStatus({code:n.OK})}(t),r&&console.log(`[MCP Logger SDK] Response sent (${u}ms):`,a),a}catch(e){throw function(e,r,t){const o=r instanceof Error?r.message:"Unknown error",s=r instanceof Error?r.constructor.name:"Error";r instanceof Error&&e.recordException(r),e.setStatus({code:n.ERROR,message:o}),e.setAttribute("error",!0),e.setAttribute("error.type",s),e.setAttribute("error.message",o),t&&console.error("[MCP Logger] Error recorded in span:",r)}(t,e,r),r&&console.error("[MCP Logger SDK] Error occurred:",e),e}finally{t.end()}})})},r&&console.log("[MCP Logger SDK] Server instrumentation complete")}(h,f.debug),f.debug&&console.log("[MCP Logger SDK] ✓ Initialization complete")}export{h as initMCPLogger,g as shutdown};

package/dist/sdk/index.js

@@ -1,80 +1 @@
-/**
- * MCP Logger SDK
- *
- * MCP 서버에 자동 관측성(Observability)을 추가하는 SDK입니다.
- */
-import { initializeTelemetry } from '../shared/telemetry.js';
-import { instrumentMCPServer } from './instrumentation.js';
-/**
- * MCP 서버에 자동 계측을 추가합니다.
- *
- * 이 함수는 MCP 서버의 모든 요청/응답을 자동으로 로깅하고 추적합니다.
- * OpenTelemetry를 사용하여 traces를 수집하며, 설정된 엔드포인트로 전송합니다.
- *
- * @param server - MCP Server 인스턴스
- * @param options - 초기화 옵션
- *
- * @throws {Error} apiKey가 제공되지 않은 경우
- * @throws {Error} server 인스턴스가 제공되지 않은 경우
- *
- * @example
- * TypeScript 사용 예시:
- * ```typescript
- * import { Server } from '@modelcontextprotocol/sdk/server/index.js';
- * import { initMCPLogger } from '@awarecorp/mcp-logger';
- *
- * const server = new Server({ name: 'my-server', version: '1.0.0' }, {
- *   capabilities: { tools: {} }
- * });
- *
- * initMCPLogger(server, {
- *   apiKey: 'your-api-key',
- *   serviceName: 'my-mcp-server',
- *   debug: true,
- * });
- *
- * server.setRequestHandler('tools/call', async (request) => {
- *   // 이 핸들러는 자동으로 로깅됩니다
- *   return { result: 'success' };
- * });
- * ```
- *
- * @example
- * JavaScript 사용 예시:
- * ```javascript
- * const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
- * const { initMCPLogger } = require('@awarecorp/mcp-logger');
- *
- * const server = new Server({ name: 'my-server', version: '1.0.0' }, {
- *   capabilities: { tools: {} }
- * });
- *
- * initMCPLogger(server, {
- *   apiKey: process.env.API_KEY,
- *   serviceName: 'my-mcp-server',
- * });
- * ```
- */
-export function initMCPLogger(server, options) {
-    if (!options.apiKey) {
-        throw new Error('[MCP Logger SDK] apiKey is required');
-    }
-    if (!server) {
-        throw new Error('[MCP Logger SDK] server instance is required');
-    }
-    // 1. OpenTelemetry SDK 초기화
-    initializeTelemetry(options);
-    // 2. MCP Server 계측
-    instrumentMCPServer(server, options.debug);
-    if (options.debug) {
-        console.log('[MCP Logger SDK] ✓ Initialization complete');
-    }
-}
-/**
- * SDK를 종료하고 모든 pending traces를 flush합니다.
- *
- * 일반적으로 명시적으로 호출할 필요는 없습니다.
- * 프로세스 종료 시 자동으로 처리됩니다.
- */
-export { shutdownTelemetry as shutdown } from '../shared/telemetry.js';
-//# sourceMappingURL=index.js.map
+import{NodeSDK as e}from"@opentelemetry/sdk-node";import{OTLPTraceExporter as r}from"@opentelemetry/exporter-trace-otlp-http";import{Resource as t}from"@opentelemetry/resources";import{trace as o,SpanStatusCode as n}from"@opentelemetry/api";const s="https://aware.mcypher.com/v1/traces",c="1.0.0";let i=null,a=null,l=!1;function u(){return a}async function g(){if(i)try{await i.shutdown(),i=null,a=null,l=!1}catch(e){console.error("[MCP Logger] Error shutting down telemetry:",e)}}function m(e,r){for(const[t,o]of Object.entries(r))null!=o&&e.setAttribute(t,o)}function p(e,r,t,o){try{t?e.addEvent(r,t):e.addEvent(r)}catch(e){o&&console.error("[MCP Logger] Failed to add span event:",e)}}function d(e,r=1e4){try{const t=JSON.stringify(e);return t.length>r?t.slice(0,r)+"... (truncated)":t}catch(e){return null}}function h(h,f){if(!f.apiKey)throw new Error("[MCP Logger SDK] apiKey is required");if(!h)throw new Error("[MCP Logger SDK] server instance is required");!function(n){if(l)return n.debug&&console.error("[MCP Logger] Telemetry already initialized, returning existing tracer"),a;const u=n.serviceName||`mcp-server-${Math.random().toString(36).slice(2,8)}`;n.debug&&(console.error("[MCP Logger] Initializing telemetry..."),console.error(`[MCP Logger] Endpoint: ${n.endpoint||s}`),console.error(`[MCP Logger] Service: ${u}`)),i=new e({resource:new t({"service.name":u,"service.version":c}),traceExporter:new r({url:n.endpoint||s,headers:{"x-api-key":n.apiKey}})}),i.start(),a=o.getTracer("mcp-logger",c),l=!0,n.debug&&console.error("[MCP Logger] Telemetry initialized successfully");const m=async()=>{n.debug&&console.error("[MCP Logger] Shutting down telemetry..."),await g()};process.once("SIGTERM",m),process.once("SIGINT",m)}(f),function(e,r=!1){const t=u();if(!t)throw new Error("[MCP Logger SDK] Tracer not initialized. Call initMCPLogger first.");const o=e.setRequestHandler.bind(e);e.setRequestHandler=function(e,s){const c=e.shape?.method,i=c?._def?.value||"unknown";return r&&console.log(`[MCP Logger SDK] Instrumenting handler: ${i}`),o(e,async(e,o)=>{const c=`mcp.${i}`;return await t.startActiveSpan(c,{attributes:{"mcp.method":i,"mcp.request.method":e.method}},async t=>{const c=Date.now();try{const i=d(e.params||{});m(t,{"mcp.request.id":"unknown","mcp.request.params.size":i?.length}),i&&i.length<1e3&&t.setAttribute("mcp.request.params",i),p(t,"mcp.request.received",{"request.method":e.method,"request.timestamp":c},r),r&&console.log("[MCP Logger SDK] Request received:",{method:e.method,params:e.params});const a=await s(e,o),l=Date.now(),u=l-c,g=d(a);return m(t,{"mcp.duration_ms":u,"mcp.response.size":g?.length}),g&&g.length<1e3&&t.setAttribute("mcp.response.result",g),p(t,"mcp.response.sent",{"response.timestamp":l,"response.duration_ms":u},r),function(e){e.setStatus({code:n.OK})}(t),r&&console.log(`[MCP Logger SDK] Response sent (${u}ms):`,a),a}catch(e){throw function(e,r,t){const o=r instanceof Error?r.message:"Unknown error",s=r instanceof Error?r.constructor.name:"Error";r instanceof Error&&e.recordException(r),e.setStatus({code:n.ERROR,message:o}),e.setAttribute("error",!0),e.setAttribute("error.type",s),e.setAttribute("error.message",o),t&&console.error("[MCP Logger] Error recorded in span:",r)}(t,e,r),r&&console.error("[MCP Logger SDK] Error occurred:",e),e}finally{t.end()}})})},r&&console.log("[MCP Logger SDK] Server instrumentation complete")}(h,f.debug),f.debug&&console.log("[MCP Logger SDK] ✓ Initialization complete")}export{h as initMCPLogger,g as shutdown};

package/dist/sdk/instrumentation.js

@@ -1,99 +1 @@
-/**
- * MCP Server 자동 계측
- *
- * setRequestHandler를 오버라이드하여 모든 요청/응답을 자동으로 추적합니다.
- */
-import { getTracer } from '../shared/telemetry.js';
-import { setSpanAttributes, addSpanEvent, recordSpanError, markSpanSuccess, safeStringify } from '../shared/span-utils.js';
-/**
- * MCP Server에 자동 계측 적용
- */
-export function instrumentMCPServer(server, debug = false) {
-    const tracer = getTracer();
-    if (!tracer) {
-        throw new Error('[MCP Logger SDK] Tracer not initialized. Call initMCPLogger first.');
-    }
-    // 원본 setRequestHandler 저장
-    const originalSetRequestHandler = server.setRequestHandler.bind(server);
-    // setRequestHandler 오버라이드
-    server.setRequestHandler = function (requestSchema, handler) {
-        // requestSchema에서 method 추출
-        const methodLiteral = requestSchema.shape?.method;
-        const method = methodLiteral?._def?.value || 'unknown';
-        if (debug) {
-            console.log(`[MCP Logger SDK] Instrumenting handler: ${method}`);
-        }
-        // 래핑된 핸들러 생성
-        const wrappedHandler = async (request, extra) => {
-            const spanName = `mcp.${method}`;
-            return await tracer.startActiveSpan(spanName, {
-                attributes: {
-                    'mcp.method': method,
-                    'mcp.request.method': request.method,
-                },
-            }, async (span) => {
-                const startTime = Date.now();
-                try {
-                    // Request 로깅
-                    const paramsStr = safeStringify(request.params || {});
-                    setSpanAttributes(span, {
-                        'mcp.request.id': 'unknown', // MCPRequest에 id가 없으므로 'unknown'으로 설정
-                        'mcp.request.params.size': paramsStr?.length,
-                    });
-                    if (paramsStr && paramsStr.length < 1000) {
-                        span.setAttribute('mcp.request.params', paramsStr);
-                    }
-                    addSpanEvent(span, 'mcp.request.received', {
-                        'request.method': request.method,
-                        'request.timestamp': startTime,
-                    }, debug);
-                    if (debug) {
-                        console.log(`[MCP Logger SDK] Request received:`, {
-                            method: request.method,
-                            params: request.params,
-                        });
-                    }
-                    // 원본 핸들러 실행
-                    const result = await handler(request, extra);
-                    const endTime = Date.now();
-                    const duration = endTime - startTime;
-                    // Response 로깅
-                    const resultStr = safeStringify(result);
-                    setSpanAttributes(span, {
-                        'mcp.duration_ms': duration,
-                        'mcp.response.size': resultStr?.length,
-                    });
-                    if (resultStr && resultStr.length < 1000) {
-                        span.setAttribute('mcp.response.result', resultStr);
-                    }
-                    addSpanEvent(span, 'mcp.response.sent', {
-                        'response.timestamp': endTime,
-                        'response.duration_ms': duration,
-                    }, debug);
-                    markSpanSuccess(span);
-                    if (debug) {
-                        console.log(`[MCP Logger SDK] Response sent (${duration}ms):`, result);
-                    }
-                    return result;
-                }
-                catch (error) {
-                    // Error 로깅
-                    recordSpanError(span, error, debug);
-                    if (debug) {
-                        console.error(`[MCP Logger SDK] Error occurred:`, error);
-                    }
-                    throw error;
-                }
-                finally {
-                    span.end();
-                }
-            });
-        };
-        // 래핑된 핸들러로 등록
-        return originalSetRequestHandler(requestSchema, wrappedHandler);
-    };
-    if (debug) {
-        console.log('[MCP Logger SDK] Server instrumentation complete');
-    }
-}
-//# sourceMappingURL=instrumentation.js.map
+import"@opentelemetry/sdk-node";import"@opentelemetry/exporter-trace-otlp-http";import"@opentelemetry/resources";import"@opentelemetry/api";function e(e,t=!1){throw new Error("[MCP Logger SDK] Tracer not initialized. Call initMCPLogger first.")}export{e as instrumentMCPServer};