@awarecorp/mcp-logger 0.0.2-dev.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# @awarecorp/mcp-logger
+
+**통합 MCP Observability 솔루션** - 하나의 패키지로 SDK와 CLI를 모두 제공합니다.
+
+---
+
+## 🎯 두 가지 사용 방법
+
+### 1️⃣ **SDK**: 코드에 직접 통합
+당신이 MCP 서버를 개발하고 있다면, SDK를 사용하세요.
+
+### 2️⃣ **CLI**: 코드 수정 없이 래핑
+이미 만들어진 MCP 서버(npm 패키지)를 사용한다면, CLI를 사용하세요.
+
+---
+
+## 📦 설치
+
+```bash
+npm install @awarecorp/mcp-logger
+```
+
+---
+
+## 1️⃣ SDK 사용법
+
+### TypeScript
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { initMCPLogger } from '@awarecorp/mcp-logger';
+
+const server = new Server(
+  { name: 'my-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+// 🔥 자동 계측 활성화 (이것만 추가하면 됩니다!)
+initMCPLogger(server, {
+  apiKey: process.env.AWARE_API_KEY!,
+  serviceName: 'my-awesome-mcp-server',
+  debug: true, // 디버그 로그 활성화 (선택사항)
+});
+
+// 평소처럼 핸들러 등록
+server.setRequestHandler('tools/list', async () => ({
+  tools: [
+    { name: 'read_file', description: 'Read a file' },
+    { name: 'write_file', description: 'Write to a file' },
+  ],
+}));
+
+server.setRequestHandler('tools/call', async (request) => {
+  const { name, arguments: args } = request.params;
+  // 이 핸들러는 자동으로 로깅됩니다!
+  return { result: `Called ${name}` };
+});
+
+// stdio transport 시작
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### JavaScript (CommonJS)
+
+```javascript
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.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.AWARE_API_KEY,
+  serviceName: 'my-mcp-server',
+});
+
+server.setRequestHandler('tools/list', async () => ({
+  tools: [{ name: 'test', description: 'Test tool' }],
+}));
+
+const transport = new StdioServerTransport();
+server.connect(transport);
+```
+
+### SDK API
+
+#### `initMCPLogger(server, options)`
+
+MCP 서버에 자동 계측을 추가합니다.
+
+**Parameters:**
+- `server` (`MCPServer`): MCP Server 인스턴스
+- `options` (`SDKInitOptions`):
+  - `apiKey` (string, 필수): Aware API 키
+  - `serviceName` (string, 옵션): 서비스 이름 (기본값: 자동 생성)
+  - `debug` (boolean, 옵션): 디버그 로그 활성화 (기본값: false)
+  - `endpoint` (string, 옵션): 커스텀 OTLP 엔드포인트
+
+**Returns:** `void`
+
+**Throws:**
+- `Error`: apiKey가 제공되지 않은 경우
+- `Error`: server 인스턴스가 제공되지 않은 경우
+
+---
+
+## 2️⃣ CLI 사용법
+
+### 기본 사용법
+
+```bash
+npx @awarecorp/mcp-logger \
+  --api-key YOUR_API_KEY \
+  -- \
+  npx @modelcontextprotocol/server-filesystem /path/to/dir
+```
+
+`--` 뒤에 원래 사용하던 MCP 서버 명령어를 그대로 입력하면 됩니다.
+
+### 전역 설치 (선택사항)
+
+```bash
+npm install -g @awarecorp/mcp-logger
+```
+
+사용:
+```bash
+mcp-logger --api-key YOUR_KEY -- npx server-filesystem /path
+```
+
+### Claude Desktop 설정
+
+#### Before (관측성 없음)
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
+    }
+  }
+}
+```
+
+#### After (관측성 추가) ✨
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@awarecorp/mcp-logger",
+        "--api-key", "your-aware-api-key",
+        "--service-name", "my-filesystem-server",
+        "--",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/username/Documents"
+      ]
+    }
+  }
+}
+```
+
+**이게 전부입니다!** 코드 수정 없이 모든 요청/응답이 Aware 플랫폼에 기록됩니다.
+
+### CLI 옵션
+
+#### 필수 옵션
+- `--api-key <key>` 또는 `-k <key>`: Aware API 키 (필수)
+
+#### 선택 옵션
+- `--service-name <name>` 또는 `-s <name>`: 서비스 식별 이름 (기본값: 자동 생성)
+- `--debug` 또는 `-d`: 디버그 로그 활성화
+- `--endpoint <url>` 또는 `-e <url>`: 커스텀 OTLP 엔드포인트
+
+### CLI 사용 예시
+
+#### 파일시스템 서버
+```bash
+npx @awarecorp/mcp-logger \
+  --api-key abc123 \
+  --service-name my-filesystem \
+  -- \
+  npx -y @modelcontextprotocol/server-filesystem /Users/username/Documents
+```
+
+#### GitHub 서버
+```bash
+npx @awarecorp/mcp-logger \
+  -k abc123 \
+  -s github-integration \
+  -- \
+  npx -y @modelcontextprotocol/server-github
+```
+
+#### Brave Search 서버 (디버그 모드)
+```bash
+npx @awarecorp/mcp-logger \
+  --api-key abc123 \
+  --service-name brave-search \
+  --debug \
+  -- \
+  npx -y @modelcontextprotocol/server-brave-search
+```
+
+---
+
+## 🏗️ 아키텍처
+
+이 패키지는 세 가지 레이어로 구성되어 있습니다:
+
+```
+@awarecorp/mcp-logger
+├── SDK (공개 API)
+│   ├── initMCPLogger()    - MCP 서버 계측
+│   └── shutdown()          - 텔레메트리 종료
+│
+├── CLI (바이너리만 접근 가능)
+│   └── mcp-logger          - CLI 래퍼
+│
+└── Shared (내부 구현)
+    ├── telemetry           - OpenTelemetry 초기화
+    ├── span-utils          - Span 유틸리티
+    └── config              - 공통 설정
+```
+
+### 중요한 설계 원칙
+
+1. **SDK만 공개 API로 노출**: `import`로는 SDK만 접근 가능
+2. **CLI는 바이너리로만 접근**: `npx` 또는 `mcp-logger` 명령어로만 사용
+3. **공통 코드 재사용**: OpenTelemetry 로직은 shared 레이어에서 통합 관리
+4. **타입 안전성**: CLI는 타입 정의가 노출되지 않음
+
+---
+
+## 🔧 개발
+
+### 빌드
+
+```bash
+npm run build
+```
+
+### 로컬 테스트
+
+#### SDK 테스트
+```typescript
+// test.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { initMCPLogger } from './src/index.js';
+
+const server = new Server({ name: 'test', version: '1.0.0' }, { capabilities: {} });
+initMCPLogger(server, { apiKey: 'test', debug: true });
+```
+
+#### CLI 테스트
+```bash
+npm run build
+node bin/mcp-logger.js --help
+```
+
+---
+
+## 📝 라이선스
+
+MIT
+
+---
+
+## 🤝 기여
+
+이슈와 PR은 언제나 환영합니다!
+
+자세한 개발 가이드는 [DEVELOPMENT.md](./DEVELOPMENT.md)를 참조하세요.
+
+---
+
+## 📦 배포 (Maintainers Only)
+
+### Stable 버전 배포
+```bash
+npm run version:patch    # 또는 minor, major
+npm run publish:stable
+```
+
+### Dev 버전 배포
+```bash
+npm run version:dev
+npm run publish:dev
+```
+
+자세한 내용은 [DEVELOPMENT.md](./DEVELOPMENT.md#배포)를 참조하세요.
+
+---
+
+## 📞 지원
+
+- 문서: [https://aware.mcypher.com/docs](https://aware.mcypher.com/docs)
+- 이슈: [GitHub Issues](https://github.com/your-org/mcp-logger/issues)

package/bin/mcp-logger.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Logger CLI Entry Point
+ * 
+ * 컴파일된 CLI를 실행합니다.
+ */
+
+import '../dist/cli/cli.js';

package/dist/cli/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+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",g="1.0.0";let d=null,p=null,u=!1;function l(){return p}async function m(){if(d)try{await d.shutdown(),d=null,p=null,u=!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("-d, --debug","Enable debug logging",!1).option("-e, --endpoint <url>","Custom OTLP endpoint").argument("<command...>","MCP server command to wrap").action(async(r,n)=>{try{!function(e){if(u)return e.debug&&console.error("[MCP Logger] Telemetry already initialized, returning existing tracer"),p;const r=e.serviceName||`mcp-server-${Math.random().toString(36).slice(2,8)}`;e.debug&&(console.error("[MCP Logger] Initializing telemetry..."),console.error(`[MCP Logger] Endpoint: ${e.endpoint||a}`),console.error(`[MCP Logger] Service: ${r}`)),d=new t({resource:new s({"service.name":r,"service.version":g}),traceExporter:new o({url:e.endpoint||a,headers:{"x-api-key":e.apiKey}})}),d.start(),p=i.getTracer("mcp-logger",g),u=!0,e.debug&&console.error("[MCP Logger] Telemetry initialized successfully");const n=async()=>{e.debug&&console.error("[MCP Logger] Shutting down telemetry..."),await m()};process.once("SIGTERM",n),process.once("SIGINT",n)}(n),n.debug&&console.error("[MCP Logger CLI] Starting MCP server:",r.join(" "));const[c,...l]=r,h=e(c,l,{stdio:["pipe","pipe","inherit"],env:{...process.env,MCP_LOGGER_ENABLED:"true"}}),b=new f("request",n.debug);process.stdin.pipe(b).pipe(h.stdin);const C=new f("response",n.debug);h.stdout.pipe(C).pipe(process.stdout),h.on("error",async e=>{console.error("[MCP Logger CLI] Failed to start MCP server:",e),await m(),process.exit(1)}),h.on("exit",async(e,r)=>{n.debug&&console.error(`[MCP Logger CLI] MCP server exited with code ${e}, signal ${r}`),await m(),process.exit(e||0)});let y=!1;const L=async e=>{y||(y=!0,n.debug&&console.error(`[MCP Logger CLI] Received ${e}, shutting down...`),h.kill(e),await Promise.race([new Promise(e=>h.once("exit",e)),new Promise(e=>setTimeout(e,5e3))]),await m(),process.exit(0))};process.on("SIGTERM",()=>L("SIGTERM")),process.on("SIGINT",()=>L("SIGINT"))}catch(e){console.error("[MCP Logger CLI] Fatal error:",e),await m(),process.exit(1)}}),r.parse();

package/dist/cli/interceptor.js

@@ -0,0 +1 @@
+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

@@ -0,0 +1,115 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+/**
+ * 공통 타입 정의
+ */
+/**
+ * 텔레메트리 초기화 옵션
+ */
+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' };
+ * });
+ * ```
+ *
+ * @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',
+ * });
+ * ```
+ */
+declare function initMCPLogger(server: MCPServer, options: SDKInitOptions): void;
+
+export { initMCPLogger, shutdownTelemetry as shutdown };
+export type { MCPServer, SDKInitOptions };

package/dist/index.js

@@ -0,0 +1 @@
+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

@@ -0,0 +1 @@
+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

@@ -0,0 +1 @@
+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};

package/dist/sdk/types.d.ts

@@ -0,0 +1,66 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ZodObject, ZodLiteral } from 'zod';
+import { Request, Result } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * 공통 타입 정의
+ */
+/**
+ * 텔레메트리 초기화 옵션
+ */
+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 JSON-RPC Request 타입
+ */
+type MCPRequest = Request;
+/**
+ * MCP Result 타입
+ */
+type MCPResult = Result;
+/**
+ * MCP Request Schema 타입
+ */
+type MCPRequestSchema = ZodObject<{
+    method: ZodLiteral<string>;
+}>;
+/**
+ * Request Handler Extra 타입
+ */
+interface RequestHandlerExtra {
+    signal: AbortSignal;
+}
+/**
+ * MCP Server 타입 (재export)
+ */
+type MCPServer = Server;
+
+export type { MCPRequest, MCPRequestSchema, MCPResult, MCPServer, RequestHandlerExtra, SDKInitOptions };

package/dist/shared/config.js

@@ -0,0 +1 @@
+const e={ENDPOINT:"https://aware.mcypher.com/v1/traces",SDK_VERSION:"1.0.0",SERVICE_NAME_PREFIX:"mcp-server"};export{e as CONFIG};

package/dist/shared/span-utils.js

@@ -0,0 +1 @@
+import{SpanStatusCode as t,context as r,trace as e}from"@opentelemetry/api";function n(t,r){for(const[e,n]of Object.entries(r))null!=n&&t.setAttribute(e,n)}function o(t,r,e,n){try{e?t.addEvent(r,e):t.addEvent(r)}catch(t){n&&console.error("[MCP Logger] Failed to add span event:",t)}}function c(r,e,n){const o=e instanceof Error?e.message:"Unknown error",c=e instanceof Error?e.constructor.name:"Error";e instanceof Error&&r.recordException(e),r.setStatus({code:t.ERROR,message:o}),r.setAttribute("error",!0),r.setAttribute("error.type",c),r.setAttribute("error.message",o),n&&console.error("[MCP Logger] Error recorded in span:",e)}function s(r){r.setStatus({code:t.OK})}function a(t,r=1e4){try{const e=JSON.stringify(t);return e.length>r?e.slice(0,r)+"... (truncated)":e}catch(t){return null}}function i(){const t={},n=r.active(),o=e.getSpan(n);if(o){const r=o.spanContext();r&&(t.traceparent=`00-${r.traceId}-${r.spanId}-01`)}return t}export{o as addSpanEvent,i as getTraceHeaders,s as markSpanSuccess,c as recordSpanError,a as safeStringify,n as setSpanAttributes};

package/dist/shared/telemetry.js

@@ -0,0 +1 @@
+import{NodeSDK as e}from"@opentelemetry/sdk-node";import{OTLPTraceExporter as r}from"@opentelemetry/exporter-trace-otlp-http";import{Resource as o}from"@opentelemetry/resources";import{trace as t}from"@opentelemetry/api";const n="https://aware.mcypher.com/v1/traces",i="1.0.0";let c=null,s=null,l=!1;function a(a){if(l)return a.debug&&console.error("[MCP Logger] Telemetry already initialized, returning existing tracer"),s;const g=a.serviceName||`mcp-server-${Math.random().toString(36).slice(2,8)}`;a.debug&&(console.error("[MCP Logger] Initializing telemetry..."),console.error(`[MCP Logger] Endpoint: ${a.endpoint||n}`),console.error(`[MCP Logger] Service: ${g}`)),c=new e({resource:new o({"service.name":g,"service.version":i}),traceExporter:new r({url:a.endpoint||n,headers:{"x-api-key":a.apiKey}})}),c.start(),s=t.getTracer("mcp-logger",i),l=!0,a.debug&&console.error("[MCP Logger] Telemetry initialized successfully");const p=async()=>{a.debug&&console.error("[MCP Logger] Shutting down telemetry..."),await u()};return process.once("SIGTERM",p),process.once("SIGINT",p),s}function g(){return s}function p(){return l}async function u(){if(c)try{await c.shutdown(),c=null,s=null,l=!1}catch(e){console.error("[MCP Logger] Error shutting down telemetry:",e)}}export{g as getTracer,a as initializeTelemetry,p as isInitializedTelemetry,u as shutdownTelemetry};

package/dist/shared/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 공통 타입 정의
+ */
+/**
+ * 텔레메트리 초기화 옵션
+ */
+interface TelemetryOptions {
+    /**
+     * API Key for authentication (필수)
+     */
+    apiKey: string;
+    /**
+     * 서비스 이름 (옵션)
+     * 지정하지 않으면 자동으로 'mcp-server-{random}' 형식으로 생성
+     */
+    serviceName?: string;
+    /**
+     * 커스텀 OTLP 엔드포인트 (옵션)
+     * 기본값: CONFIG.ENDPOINT
+     */
+    endpoint?: string;
+    /**
+     * 디버그 로그 활성화 (옵션)
+     */
+    debug?: boolean;
+}
+/**
+ * Span 속성 인터페이스
+ */
+interface SpanAttributes {
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * MCP 메시지 방향
+ */
+type MessageDirection = 'request' | 'response';
+/**
+ * JSON-RPC 메시지 타입
+ */
+interface JSONRPCMessage {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method?: string;
+    params?: any;
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+}
+
+export type { JSONRPCMessage, MessageDirection, SpanAttributes, TelemetryOptions };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@awarecorp/mcp-logger",
+  "version": "0.0.2-dev.0",
+  "description": "Unified MCP observability solution - SDK for code integration and CLI for zero-config wrapping",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-logger": "./bin/mcp-logger.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "!dist/cli/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "npm run clean && rollup -c",
+    "build:readable": "npm run clean && tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "test:cli": "npm run build:readable && node bin/mcp-logger.js --help",
+    "publish:stable": "npm run build && npm publish --access public",
+    "publish:dev": "npm run build && npm publish --access public --tag dev",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "version:dev": "npm version prerelease --preid=dev"
+  },
+  "keywords": [
+    "mcp",
+    "observer",
+    "observability",
+    "opentelemetry",
+    "tracing",
+    "logging",
+    "cli",
+    "wrapper",
+    "aware"
+  ],
+  "author": "Aware",
+  "license": "MIT",
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
+    "@opentelemetry/resources": "^1.25.0",
+    "@opentelemetry/sdk-node": "^0.52.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0",
+    "commander": "^11.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^20.0.0",
+    "rollup": "^4.52.5",
+    "rollup-plugin-dts": "^6.2.3",
+    "tslib": "^2.8.1",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}