@anyshift/mcp-proxy 0.2.0

package/README.md

@@ -0,0 +1,314 @@
+# @anyshift/mcp-proxy
+
+**Universal MCP Proxy** - Add truncation, file writing, and JQ capabilities to ANY Model Context Protocol (MCP) server.
+
+## Features
+
+🔄 **100% MCP-Agnostic**: Works with any MCP server through environment variable contract
+✂️ **Response Truncation**: Auto-truncate large responses to token limits
+💾 **Automatic File Writing**: Save large responses to disk
+🔍 **JQ Tool**: Query saved JSON files with JQ syntax
+🎯 **Zero Configuration**: No config files, just environment variables
+
+## Why Use This?
+
+MCP servers often return very large responses (dashboards, metrics, logs) that:
+- Exceed AI model context windows (causing truncation or errors)
+- Make it hard for AI to synthesize information
+- Cannot be easily queried or analyzed
+
+This proxy solves these problems by:
+1. **Truncating** responses to configurable token limits
+2. **Saving** full responses to disk automatically
+3. **Adding** a JQ tool to query saved JSON files
+
+## Environment Variable Contract
+
+The proxy uses a **namespace convention** to separate its configuration from the child MCP server's configuration:
+
+### Proxy Configuration (MCP_PROXY_* prefix)
+
+These variables control the proxy's behavior:
+
+```bash
+# REQUIRED: Child MCP specification
+MCP_PROXY_CHILD_COMMAND="mcp-grafana"           # Command to spawn child MCP
+
+# OPTIONAL: Child command arguments
+MCP_PROXY_CHILD_ARGS="arg1,arg2"                # Comma-separated arguments
+
+# OPTIONAL: Truncation settings (defaults shown)
+MCP_PROXY_MAX_TOKENS=10000                      # Max tokens before truncation
+MCP_PROXY_CHARS_PER_TOKEN=4                     # Chars per token calculation
+
+# OPTIONAL: File writing settings
+MCP_PROXY_WRITE_TO_FILE=true                    # Enable file writing (default: false)
+MCP_PROXY_OUTPUT_PATH=/tmp/mcp-results          # REQUIRED if WRITE_TO_FILE=true
+MCP_PROXY_MIN_CHARS_FOR_WRITE=1000              # Min size to save (default: 1000)
+
+# OPTIONAL: JQ tool settings
+MCP_PROXY_ENABLE_JQ=true                        # Enable JQ tool (default: true)
+MCP_PROXY_JQ_TIMEOUT_MS=30000                   # JQ timeout (default: 30000)
+
+# OPTIONAL: Debug logging
+MCP_PROXY_ENABLE_LOGGING=true                   # Enable debug logs (default: false)
+```
+
+### Pass-Through Variables (NO prefix)
+
+All other environment variables are passed directly to the child MCP:
+
+```bash
+# Grafana example
+GRAFANA_URL=https://your-instance.grafana.net
+GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_...
+
+# Datadog example
+DATADOG_API_KEY=...
+DATADOG_APP_KEY=...
+
+# Anyshift example
+API_TOKEN=...
+API_BASE_URL=...
+
+# Any other env vars your MCP needs
+CUSTOM_VAR=value
+```
+
+**Key Design Principle:** The proxy knows nothing about specific MCP servers. It simply:
+1. Reads `MCP_PROXY_*` vars for its own config
+2. Passes everything else to the child MCP
+
+## Quick Start Examples
+
+### Example 1: Wrap Grafana MCP
+
+```bash
+# Proxy configuration
+export MCP_PROXY_CHILD_COMMAND="mcp-grafana"
+export MCP_PROXY_MAX_TOKENS=10000
+export MCP_PROXY_WRITE_TO_FILE=true
+export MCP_PROXY_OUTPUT_PATH=/tmp/grafana-results
+
+# Grafana credentials (passed through to child)
+export GRAFANA_URL=https://your-instance.grafana.net
+export GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_your_token
+
+# Run proxy
+npx @anyshift/mcp-proxy
+```
+
+### Example 2: Wrap Anyshift MCP
+
+```bash
+# Proxy configuration
+export MCP_PROXY_CHILD_COMMAND="npx"
+export MCP_PROXY_CHILD_ARGS="-y,@anyshift/anyshift-mcp-server"
+export MCP_PROXY_WRITE_TO_FILE=true
+export MCP_PROXY_OUTPUT_PATH=/tmp/anyshift-results
+
+# Anyshift credentials (passed through)
+export API_TOKEN=your_token
+export API_BASE_URL=https://api.anyshift.io
+
+# Run proxy
+npx @anyshift/mcp-proxy
+```
+
+### Example 3: Wrap Custom MCP
+
+```bash
+# Proxy configuration
+export MCP_PROXY_CHILD_COMMAND="node"
+export MCP_PROXY_CHILD_ARGS="/path/to/your/mcp-server.js"
+export MCP_PROXY_MAX_TOKENS=5000
+
+# Your MCP's credentials (passed through)
+export YOUR_API_KEY=...
+export YOUR_API_URL=...
+
+# Run proxy
+npx @anyshift/mcp-proxy
+```
+
+## How It Works
+
+```
+┌─────────────┐
+│  AI Agent   │
+└──────┬──────┘
+       │ MCP Protocol (stdio)
+       ▼
+┌─────────────────────────────────┐
+│    @anyshift/mcp-proxy          │
+│                                 │
+│  1. Spawns child MCP            │
+│     with pass-through env vars  │
+│                                 │
+│  2. Discovers child tools       │
+│     + adds JQ tool              │
+│                                 │
+│  3. Forwards tool calls         │
+│                                 │
+│  4. Applies truncation          │
+│     if response > MAX_TOKENS    │
+│                                 │
+│  5. Writes to file              │
+│     if response > MIN_CHARS     │
+│                                 │
+│  6. Returns modified response   │
+│     to AI agent                 │
+└────────────┬────────────────────┘
+             │ Child process (stdio)
+             ▼
+      ┌──────────────┐
+      │  Child MCP   │  (mcp-grafana, custom-mcp, etc.)
+      │    Server    │  Gets env vars WITHOUT MCP_PROXY_ prefix
+      └──────────────┘
+```
+
+## Integration Examples
+
+### AI-Workbench Integration
+
+```go
+// In ai-workbench builder.go
+func WrapWithProxy(baseMCPConfig MCPConfig, ...) MCPConfig {
+    proxyEnv := map[string]string{
+        "MCP_PROXY_CHILD_COMMAND": baseMCPConfig.Command,
+        "MCP_PROXY_MAX_TOKENS":    "10000",
+        "MCP_PROXY_WRITE_TO_FILE": "true",
+        "MCP_PROXY_OUTPUT_PATH":   outputPath,
+    }
+
+    // Merge child's env vars (pass-through)
+    for key, value := range baseMCPConfig.Env {
+        proxyEnv[key] = value
+    }
+
+    return MCPConfig{
+        Command: "npx",
+        Args:    []string{"-y", "@anyshift/mcp-proxy"},
+        Env:     proxyEnv,
+    }
+}
+```
+
+### Claude Desktop Integration
+
+```json
+{
+  "mcpServers": {
+    "grafana": {
+      "command": "npx",
+      "args": ["-y", "@anyshift/mcp-proxy"],
+      "env": {
+        "MCP_PROXY_CHILD_COMMAND": "mcp-grafana",
+        "MCP_PROXY_MAX_TOKENS": "10000",
+        "MCP_PROXY_WRITE_TO_FILE": "true",
+        "MCP_PROXY_OUTPUT_PATH": "/tmp/grafana-results",
+        "GRAFANA_URL": "https://your-instance.grafana.net",
+        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_..."
+      }
+    }
+  }
+}
+```
+
+## Environment Variable Reference
+
+### MCP_PROXY_CHILD_COMMAND (REQUIRED)
+
+The command to spawn as the child MCP server.
+
+**Examples:**
+- `"mcp-grafana"` - Direct binary
+- `"npx"` - Use with `MCP_PROXY_CHILD_ARGS="-y,@anyshift/anyshift-mcp-server"`
+- `"node"` - Use with `MCP_PROXY_CHILD_ARGS="/path/to/server.js"`
+
+### MCP_PROXY_CHILD_ARGS (OPTIONAL)
+
+Comma-separated arguments to pass to the child command.
+
+**Example:** `"arg1,arg2,--verbose"` becomes `["arg1", "arg2", "--verbose"]`
+
+### MCP_PROXY_MAX_TOKENS (OPTIONAL, default: 10000)
+
+Maximum tokens before truncating responses.
+
+**Calculation:** `maxTokens × charsPerToken = max characters`
+**Default:** `10000 × 4 = 40,000 characters`
+
+### MCP_PROXY_WRITE_TO_FILE (OPTIONAL, default: false)
+
+Enable automatic file writing for responses above `MIN_CHARS_FOR_WRITE`.
+
+**When to enable:**
+- Responses frequently exceed token limits
+- Need full data for later analysis
+- Want to use JQ tool to query responses
+
+### MCP_PROXY_OUTPUT_PATH (REQUIRED if WRITE_TO_FILE=true)
+
+Directory where response files are saved.
+
+**File naming:** `{timestamp}_{tool_name}_{short_id}.json`
+
+### MCP_PROXY_ENABLE_JQ (OPTIONAL, default: true)
+
+Add the `execute_jq_query` tool for querying saved JSON files.
+
+**Disable when:**
+- Child MCP already provides JQ tool
+- Don't need file querying capability
+
+### MCP_PROXY_ENABLE_LOGGING (OPTIONAL, default: false)
+
+Enable debug logging to stderr.
+
+**Logs include:**
+- Configuration summary
+- Tool discovery count
+- Truncation events
+- File writing operations
+
+## Development
+
+```bash
+# Clone and install
+cd mcp-proxy
+pnpm install
+
+# Build
+pnpm build
+
+# Test with Grafana
+export MCP_PROXY_CHILD_COMMAND="mcp-grafana"
+export GRAFANA_URL=...
+export GRAFANA_SERVICE_ACCOUNT_TOKEN=...
+node dist/index.js
+
+# Test with custom MCP
+export MCP_PROXY_CHILD_COMMAND="node"
+export MCP_PROXY_CHILD_ARGS="/path/to/my-mcp.js"
+export MY_API_KEY=...
+node dist/index.js
+```
+
+## Benefits
+
+✅ **Zero configuration files** - Pure environment variables
+✅ **Truly MCP-agnostic** - Works with ANY MCP server
+✅ **Simple integration** - Just wrap the command with env vars
+✅ **Clean separation** - Proxy config vs child config
+✅ **Pass-through design** - Child gets exactly what it needs
+
+## License
+
+MIT
+
+## Related Projects
+
+- [@anyshift/mcp-tools-common](../mcp-tools-common) - Shared MCP utilities (truncation, file writing, JQ)
+- [mcp-grafana](https://github.com/grafana/mcp-grafana) - Official Grafana MCP server
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

package/dist/fileWriter/index.d.ts

@@ -0,0 +1,18 @@
+import { FileWriterConfig, FileWriterResult } from './types.js';
+/**
+ * Create a file writer instance with the given configuration
+ * @param config - File writer configuration
+ * @returns Object with handleResponse method
+ */
+export declare function createFileWriter(config: FileWriterConfig): {
+    /**
+     * Handle tool response - writes to file if conditions are met
+     * @param toolName - Name of the tool that generated the response
+     * @param args - Arguments passed to the tool
+     * @param responseData - The response data to potentially write to file
+     * @returns Either the original response or a file reference response
+     */
+    handleResponse: (toolName: string, args: Record<string, unknown>, responseData: unknown) => Promise<FileWriterResult | unknown>;
+};
+export type { FileWriterConfig, FileWriterResult } from './types.js';
+export { analyzeJsonSchema, extractNullableFields } from './schema.js';

package/dist/fileWriter/index.js

@@ -0,0 +1,21 @@
+import { handleToolResponse } from './writer.js';
+/**
+ * Create a file writer instance with the given configuration
+ * @param config - File writer configuration
+ * @returns Object with handleResponse method
+ */
+export function createFileWriter(config) {
+    return {
+        /**
+         * Handle tool response - writes to file if conditions are met
+         * @param toolName - Name of the tool that generated the response
+         * @param args - Arguments passed to the tool
+         * @param responseData - The response data to potentially write to file
+         * @returns Either the original response or a file reference response
+         */
+        handleResponse: async (toolName, args, responseData) => {
+            return handleToolResponse(config, toolName, args, responseData);
+        },
+    };
+}
+export { analyzeJsonSchema, extractNullableFields } from './schema.js';

package/dist/fileWriter/schema.d.ts

@@ -0,0 +1,15 @@
+import { JsonSchema, NullableFields } from '../types/index.js';
+/**
+ * Analyze JSON structure and generate enhanced schema
+ * @param obj - The object to analyze
+ * @param path - Current path in the object (for debugging)
+ * @returns Schema representation of the object
+ */
+export declare function analyzeJsonSchema(obj: unknown, path?: string): JsonSchema;
+/**
+ * Extract nullable and always-null fields from schema
+ * @param schema - The schema to analyze
+ * @param basePath - Base path for field names
+ * @returns Object containing arrays of always-null and nullable field paths
+ */
+export declare function extractNullableFields(schema: unknown, basePath?: string): NullableFields;

package/dist/fileWriter/schema.js

@@ -0,0 +1,120 @@
+/**
+ * Analyze JSON structure and generate enhanced schema
+ * @param obj - The object to analyze
+ * @param path - Current path in the object (for debugging)
+ * @returns Schema representation of the object
+ */
+export function analyzeJsonSchema(obj, path = 'root') {
+    if (obj === null)
+        return { type: 'null' };
+    if (obj === undefined)
+        return { type: 'undefined' };
+    const type = Array.isArray(obj) ? 'array' : typeof obj;
+    if (type === 'object') {
+        const properties = {};
+        const objRecord = obj;
+        const keys = Object.keys(objRecord);
+        // Detect numeric string keys (common in Cypher results)
+        const numericKeys = keys.filter((k) => /^\d+$/.test(k));
+        const hasNumericKeys = keys.length > 0 && numericKeys.length >= keys.length * 0.8;
+        for (const key in objRecord) {
+            if (Object.prototype.hasOwnProperty.call(objRecord, key)) {
+                properties[key] = analyzeJsonSchema(objRecord[key], `${path}.${key}`);
+            }
+        }
+        const schema = { type: 'object', properties };
+        // Add metadata hints for numeric keys
+        if (hasNumericKeys) {
+            schema._keysAreNumeric = true;
+            schema._accessPattern = 'Use .["0"] not .[0]';
+        }
+        return schema;
+    }
+    else if (type === 'array') {
+        const arr = obj;
+        if (arr.length === 0) {
+            return { type: 'array', items: { type: 'unknown' }, length: 0 };
+        }
+        // Analyze array items for mixed types and nulls
+        const itemTypes = new Set();
+        let hasNulls = false;
+        // Sample first 10 items to detect type variance
+        const sampled = arr.slice(0, Math.min(10, arr.length));
+        for (const item of sampled) {
+            if (item === null) {
+                hasNulls = true;
+                itemTypes.add('null');
+            }
+            else {
+                itemTypes.add(Array.isArray(item) ? 'array' : typeof item);
+            }
+        }
+        const schema = {
+            type: 'array',
+            items: itemTypes.size === 1 && !hasNulls
+                ? analyzeJsonSchema(arr[0], `${path}[0]`)
+                : { types: Array.from(itemTypes) },
+            length: arr.length,
+        };
+        // Add hints for null handling
+        if (hasNulls) {
+            schema._hasNulls = true;
+        }
+        return schema;
+    }
+    else {
+        return { type };
+    }
+}
+/**
+ * Extract nullable and always-null fields from schema
+ * @param schema - The schema to analyze
+ * @param basePath - Base path for field names
+ * @returns Object containing arrays of always-null and nullable field paths
+ */
+export function extractNullableFields(schema, basePath = '') {
+    const alwaysNull = [];
+    const nullable = [];
+    function traverse(s, path) {
+        if (!s || typeof s !== 'object')
+            return;
+        const schemaObj = s;
+        // Check if this field is always null
+        if (schemaObj.type === 'null') {
+            alwaysNull.push(path);
+            return;
+        }
+        // Check if this field can be null (mixed types)
+        if (schemaObj.items && typeof schemaObj.items === 'object') {
+            const items = schemaObj.items;
+            if (items.types &&
+                Array.isArray(items.types) &&
+                items.types.includes('null')) {
+                nullable.push(path);
+            }
+        }
+        // Recurse into object properties
+        if (schemaObj.type === 'object' && schemaObj.properties) {
+            const props = schemaObj.properties;
+            for (const [key, value] of Object.entries(props)) {
+                const newPath = path ? `${path}.${key}` : key;
+                traverse(value, newPath);
+            }
+        }
+        // Recurse into array items
+        if (schemaObj.type === 'array' &&
+            schemaObj.items &&
+            typeof schemaObj.items === 'object') {
+            const items = schemaObj.items;
+            if (items.type === 'object' && items.properties) {
+                const props = items.properties;
+                for (const [key, value] of Object.entries(props)) {
+                    const newPath = path ? `${path}[].${key}` : `[].${key}`;
+                    traverse(value, newPath);
+                }
+            }
+        }
+    }
+    traverse(schema, basePath);
+    return { alwaysNull, nullable };
+}

package/dist/fileWriter/types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export FileWriterConfig and related types from the main types module
+ */
+export type { FileWriterConfig, FileWriterResult } from '../types/index.js';

package/dist/fileWriter/types.js

@@ -0,0 +1 @@
+export {};

package/dist/fileWriter/writer.d.ts

@@ -0,0 +1,10 @@
+import { FileWriterConfig, FileWriterResult } from './types.js';
+/**
+ * Centralized response handler with file writing capability
+ * @param config - File writer configuration
+ * @param toolName - Name of the tool that generated the response
+ * @param args - Arguments passed to the tool
+ * @param responseData - The response data to potentially write to file
+ * @returns Either the original response or a file reference response
+ */
+export declare function handleToolResponse(config: FileWriterConfig, toolName: string, args: Record<string, unknown>, responseData: unknown): Promise<FileWriterResult | unknown>;