@awarecorp/mcp-logger 0.0.3-dev.5 → 0.0.4-dev.0

package/README.md

@@ -0,0 +1,257 @@
+# @awarecorp/mcp-logger
+
+**Unified MCP Observability Solution** - Monitor your Model Context Protocol servers with zero configuration.
+
+[![npm version](https://img.shields.io/npm/v/@awarecorp/mcp-logger)](https://www.npmjs.com/package/@awarecorp/mcp-logger)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Aware Corp](https://awarecorp.io/)
+
+---
+
+## 🎯 Overview
+
+`@awarecorp/mcp-logger` provides comprehensive observability for MCP servers in two ways:
+
+- **SDK**: Direct integration for custom MCP servers
+- **CLI**: Zero-code wrapper for existing MCP packages
+
+All telemetry data is sent to OpenTelemetry-compatible endpoints with automatic request-response pairing.
+
+## 📦 Installation
+
+```bash
+npm install @awarecorp/mcp-logger
+```
+
+## 🚀 Quick Start
+
+### SDK Mode
+
+Instrument your MCP server with one line of code:
+
+```typescript
+import { trace } from "@awarecorp/mcp-logger";
+
+trace(server, {
+  apiKey: "YOUR_API_KEY",
+  serviceName: "my-mcp-server",
+});
+```
+
+### CLI Mode
+
+Wrap any existing MCP server without code changes:
+
+```bash
+npx @awarecorp/mcp-logger \
+  -k YOUR_API_KEY \
+  -s my-server \
+  npx your-mcp-server
+```
+
+## 📋 Features
+
+### Core Capabilities
+
+- **Automatic Request-Response Pairing**: Single span per request-response cycle with intelligent message correlation
+- **Notification Support**: Tracks both client→server and server→client notifications
+- **Selective Method Tracking**: Configurable filtering to track only relevant methods (excludes noisy notifications like `notifications/initialized`)
+- **Custom Event Logging**: Add context-aware logs within request handlers
+- **Enhanced Error Handling**: Robust error serialization for complex error objects
+- **Custom OTLP Endpoint**: Send traces to any OTLP/HTTP compatible observability backend
+- **Transport Support**: stdio and SSE (Server-Sent Events)
+- **Zero Configuration**: Works out of the box with sensible defaults
+
+### Telemetry Data
+
+All spans include:
+
+- Request/response timestamps and payloads
+- Method name and parameters
+- Tool names and arguments (for `tools/call`)
+- Custom events and logs
+- Error details (if any)
+- Duration metrics
+- CLI server information (command, args, env)
+
+### Data Format
+
+Optimized for Elasticsearch with flat structure:
+
+- `mcp.request.method` / `mcp.response.method`: Method names for request/response
+- `mcp.source`: `sdk` or `cli`
+- `mcp.transport`: `stdio` or `sse`
+- `mcp.duration_ms`: Request duration
+- `mcp.tool.name`: Tool name (tools/call only)
+- `mcp.request.params` / `mcp.response.result`: Request/response payloads
+- `mcp.error.message`: Enhanced error serialization (no more `[object Object]`)
+- `mcp.events`: Custom log entries (JSON array)
+- `mcp.cli.server`: CLI execution info (JSON object)
+
+## 🔧 SDK API
+
+### `trace(server, options)`
+
+Enable automatic instrumentation on an MCP server.
+
+**Parameters:**
+
+- `server`: MCP Server instance
+- `options.apiKey`: API key for authentication (required)
+  - Currently accepts any string value for testing purposes
+  - For production use, sign up at [Aware](https://awarecorp.io/) to get your API key
+- `options.serviceName`: Service identifier (optional, auto-generated if omitted)
+- `options.endpoint`: Custom OTLP endpoint (optional, default: `https://aware.mcypher.com/v1/traces`)
+  - Accepts any OTLP/HTTP compatible endpoint URL
+  - Use this to send traces to your own observability backend (e.g., Jaeger, Grafana, etc.)
+- `options.debug`: Enable debug logging (optional, default: false)
+
+**Returns:** `void`
+
+### `trace.addLog(entry)`
+
+Add custom log entries within request handlers.
+
+**Parameters:**
+
+- `entry.level`: Log level (`info` | `warn` | `error`)
+- `entry.message`: Log message (required)
+- `entry.metadata`: Additional data (optional)
+- `entry.timestamp`: Unix timestamp in milliseconds (optional, auto-generated)
+
+**Returns:** `void`
+
+### `trace.shutdown()`
+
+Gracefully shutdown telemetry and flush pending data.
+
+**Returns:** `Promise<void>`
+
+## 🖥️ CLI Usage
+
+### Basic Syntax
+
+```bash
+mcp-logger [options] <command...>
+```
+
+### Options
+
+- `-k, --api-key <key>`: API key (required)
+  - Currently accepts any string value for testing
+  - Sign up at [Aware](https://awarecorp.io/) to get your API key for production use
+- `-s, --service-name <name>`: Service name (optional)
+- `-e, --endpoint <url>`: Custom OTLP endpoint (optional, default: `https://aware.mcypher.com/v1/traces`)
+  - Send traces to any OTLP/HTTP compatible backend
+  - Examples: Jaeger, Grafana Tempo, New Relic, Honeycomb, etc.
+- `-d, --debug`: Enable debug logging (optional)
+  - Shows detailed information about message processing and span creation
+
+### Examples
+
+**Wrap an npx command:**
+
+```bash
+mcp-logger -k API_KEY -s filesystem npx -y @modelcontextprotocol/server-filesystem /path
+```
+
+**Use with Claude Desktop:**
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@awarecorp/mcp-logger",
+        "-k",
+        "YOUR_API_KEY",
+        "-s",
+        "my-server",
+        "--",
+        "npx",
+        "-y",
+        "your-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+## 🏗️ How It Works
+
+### Request-Response Pairing
+
+Creates **one span per request-response pair** for complete transaction context:
+
+1. Request arrives → stored in pending map
+2. Response arrives → matched by ID, single span created
+3. Timeout (30s) → pending requests cleared
+4. Notifications → handled as single-direction spans (request-only or response-only)
+
+### Message Type Handling
+
+- **Paired Spans**: Request-response cycles with matching IDs (most common)
+- **Request-Only Spans**: Client→server notifications (no response expected)
+- **Response-Only Spans**: Server→client notifications (no matching request)
+
+### Tracked Methods
+
+Configurable method filtering with exclusion list:
+
+- Tracks: `tools/call`, `tools/list`, and other business-critical methods
+- Excludes: `notifications/initialized` and other noisy protocol notifications
+- Customizable via `EXCLUDED_METHODS` configuration
+
+## 📊 Telemetry Data Structure
+
+Each span includes:
+
+- Request/response timestamps and payloads (with optional fields for notifications)
+- Method name and parameters (separate fields for request/response)
+- Tool names and arguments (for `tools/call`)
+- Custom events and logs
+- Enhanced error details with proper serialization
+- Duration metrics
+- CLI server information (command, args, env)
+
+### Span Attributes
+
+All attributes use a flat structure optimized for Elasticsearch:
+
+**Core Attributes:**
+
+- Request attributes: `mcp.request.*` (id, method, params, timestamp)
+- Response attributes: `mcp.response.*` (method, result, error, timestamp)
+- Error handling: Proper serialization for Error objects, strings, and complex objects
+- Metadata: source, transport, duration, tool information
+
+**Context Tracking:**
+
+- `mcp.session.id`: Unique session identifier
+- `mcp.conversation.id`: Conversation/thread identifier
+- `mcp.user.id`: User identifier (from params, headers, or environment)
+- `mcp.client.name`: Client application name (e.g., 'Claude Desktop')
+- `mcp.client.version`: Client version
+
+**Permission & Security:**
+
+- `mcp.permission.level`: Permission level (read/write/admin/elevated)
+
+**Resource Tracking:**
+
+- `mcp.resource.type`: Resource type (tool/file/prompt)
+- `mcp.resource.uri`: Resource URI or identifier
+- `mcp.resource.access_count`: Number of times resource accessed
+
+## 📄 License
+
+MIT © [Aware Corp](https://awarecorp.io/)
+
+## 🔗 Links
+
+- [Aware Corp](https://awarecorp.io/)
+- [npm Package](https://www.npmjs.com/package/@awarecorp/mcp-logger)
+- [Model Context Protocol](https://modelcontextprotocol.io/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awarecorp/mcp-logger",
-  "version": "0.0.3-dev.5",
+  "version": "0.0.4-dev.0",
   "description": "Unified MCP observability solution - SDK for code integration and CLI for zero-config wrapping",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,11 @@
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",
     "version:major": "npm version major",
-    "version:dev": "npm version prerelease --preid=dev"
+    "version:dev": "npm version prerelease --preid=dev",
+    "version:stable": "npm version patch --no-git-tag-version && node -e \"const pkg=require('./package.json'); pkg.version=pkg.version.replace(/-dev\\.\\d+$/,''); require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2)+'\\n')\"",
+    "version:next-dev:patch": "node -e \"const pkg=require('./package.json'); const match=pkg.version.match(/^(\\\\d+)\\\\.(\\\\d+)\\\\.(\\\\d+)/); const newVer=match[1]+'.'+match[2]+'.'+(parseInt(match[3])+1)+'-dev.0'; pkg.version=newVer; require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2)+'\\\\n'); console.log('Version updated to',newVer)\"",
+    "version:next-dev:minor": "node -e \"const pkg=require('./package.json'); const match=pkg.version.match(/^(\\\\d+)\\\\.(\\\\d+)\\\\.(\\\\d+)/); const newVer=match[1]+'.'+(parseInt(match[2])+1)+'.0-dev.0'; pkg.version=newVer; require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2)+'\\\\n'); console.log('Version updated to',newVer)\"",
+    "version:next-dev:major": "node -e \"const pkg=require('./package.json'); const match=pkg.version.match(/^(\\\\d+)\\\\.(\\\\d+)\\\\.(\\\\d+)/); const newVer=(parseInt(match[1])+1)+'.0.0-dev.0'; pkg.version=newVer; require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2)+'\\\\n'); console.log('Version updated to',newVer)\""
   },
   "keywords": [
     "mcp",