@anyshift/mcp-proxy 0.4.2 → 0.6.0

package/dist/docs/handler.d.ts

@@ -0,0 +1,29 @@
+import type { DocsConfig } from './types.js';
+/**
+ * Execute docs_glob to find files matching a pattern
+ * Results are filtered against the indexed paths to ensure consistency with docs_read
+ */
+export declare function executeDocsGlob(config: DocsConfig, pattern: string): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Execute docs_grep to search documentation content
+ */
+export declare function executeDocsGrep(config: DocsConfig, query: string, maxResults?: number): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Execute docs_read to read a documentation file
+ */
+export declare function executeDocsRead(config: DocsConfig, relativePath: string): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;

package/dist/docs/handler.js

@@ -0,0 +1,192 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+// Maximum file size to read (5MB) - prevents DoS with large files
+const MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024;
+/**
+ * Validate that the docs base path exists and is a directory
+ */
+function validateDocsBasePath(docsBasePath) {
+    if (!path.isAbsolute(docsBasePath)) {
+        throw new Error(`Docs base path must be absolute: ${docsBasePath}`);
+    }
+    if (!fs.existsSync(docsBasePath)) {
+        throw new Error(`Docs base path does not exist: ${docsBasePath}`);
+    }
+    const stat = fs.statSync(docsBasePath);
+    if (!stat.isDirectory()) {
+        throw new Error(`Docs base path is not a directory: ${docsBasePath}`);
+    }
+}
+/**
+ * Validate that a path is strictly within the docs base directory (prevent path traversal).
+ * Also resolves symlinks to prevent symlink-based escapes.
+ * Returns the real (symlink-resolved) absolute path.
+ */
+function validatePathWithinDocs(filePath, docsBasePath) {
+    // Resolve to absolute path
+    const absolutePath = path.resolve(docsBasePath, filePath);
+    // Get the real path of the base directory (resolve any symlinks)
+    const realBase = fs.realpathSync(docsBasePath);
+    // Ensure the resolved path is strictly within the docs directory (not equal to it)
+    if (absolutePath === realBase || !absolutePath.startsWith(realBase + path.sep)) {
+        throw new Error(`Path traversal detected: ${filePath} resolves outside docs directory`);
+    }
+    // If the file exists, resolve symlinks and validate the real path
+    if (fs.existsSync(absolutePath)) {
+        const realPath = fs.realpathSync(absolutePath);
+        if (!realPath.startsWith(realBase + path.sep)) {
+            throw new Error(`Symlink escape detected: ${filePath} points outside docs directory`);
+        }
+        return realPath;
+    }
+    return absolutePath;
+}
+/**
+ * Validate that a relative path doesn't contain path traversal sequences.
+ * Used to validate indexed paths before use.
+ */
+function isValidRelativePath(relativePath) {
+    // Reject paths with traversal sequences
+    const normalized = path.normalize(relativePath);
+    return !normalized.startsWith('..') && !path.isAbsolute(normalized);
+}
+/**
+ * Execute docs_glob to find files matching a pattern
+ * Results are filtered against the indexed paths to ensure consistency with docs_read
+ */
+export async function executeDocsGlob(config, pattern) {
+    validateDocsBasePath(config.docsBasePath);
+    // Execute glob within the docs directory
+    const globMatches = await glob(pattern, {
+        cwd: config.docsBasePath,
+        nodir: true, // Only match files, not directories
+        dot: false, // Don't match hidden files
+    });
+    // Filter to only include paths that are in the index (ensures docs_read will accept them)
+    const indexedSet = new Set(config.indexedPaths);
+    const matches = globMatches.filter((p) => indexedSet.has(p));
+    // Sort matches alphabetically for consistent results
+    matches.sort();
+    const result = {
+        matchingPaths: matches,
+        totalMatches: matches.length,
+    };
+    const output = matches.length > 0
+        ? `Found ${matches.length} matching file(s):\n${matches.map((p) => `  - ${p}`).join('\n')}`
+        : `No files found matching pattern: ${pattern}`;
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}
+/**
+ * Execute docs_grep to search documentation content
+ */
+export async function executeDocsGrep(config, query, maxResults = 50) {
+    validateDocsBasePath(config.docsBasePath);
+    if (!query || query.trim() === '') {
+        throw new Error('Search query cannot be empty');
+    }
+    const searchQuery = query.toLowerCase();
+    const matches = [];
+    // Search through all indexed paths
+    for (const relativePath of config.indexedPaths) {
+        // Validate indexed path doesn't contain traversal sequences
+        if (!isValidRelativePath(relativePath)) {
+            continue; // Skip potentially malicious paths
+        }
+        const absolutePath = path.join(config.docsBasePath, relativePath);
+        // Skip if file doesn't exist
+        if (!fs.existsSync(absolutePath)) {
+            continue;
+        }
+        try {
+            // Check file size to prevent DoS
+            const stat = fs.statSync(absolutePath);
+            if (stat.size > MAX_FILE_SIZE_BYTES) {
+                console.warn(`[docs] Skipping large file during grep: ${relativePath} (${Math.round(stat.size / 1024)}KB exceeds ${MAX_FILE_SIZE_BYTES / 1024}KB limit)`);
+                continue; // Skip files that are too large
+            }
+            const content = fs.readFileSync(absolutePath, 'utf-8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                if (lines[i].toLowerCase().includes(searchQuery)) {
+                    matches.push({
+                        path: relativePath,
+                        lineNumber: i + 1,
+                        lineContent: lines[i].trim().substring(0, 200), // Truncate long lines
+                    });
+                    if (matches.length >= maxResults) {
+                        break;
+                    }
+                }
+            }
+            if (matches.length >= maxResults) {
+                break;
+            }
+        }
+        catch {
+            // Skip files that can't be read
+            continue;
+        }
+    }
+    const result = {
+        matches,
+        totalMatches: matches.length,
+        truncated: matches.length >= maxResults,
+    };
+    let output;
+    if (matches.length === 0) {
+        output = `No matches found for query: "${query}"`;
+    }
+    else {
+        const lines = matches.map((m) => `${m.path}:${m.lineNumber}: ${m.lineContent}`);
+        output = `Found ${matches.length} match(es)${result.truncated ? ' (truncated)' : ''}:\n\n${lines.join('\n')}`;
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}
+/**
+ * Execute docs_read to read a documentation file
+ */
+export async function executeDocsRead(config, relativePath) {
+    validateDocsBasePath(config.docsBasePath);
+    if (!relativePath || relativePath.trim() === '') {
+        throw new Error('File path cannot be empty');
+    }
+    // Normalize the path
+    const normalizedPath = path.normalize(relativePath).replace(/^\/+/, '');
+    // Validate path doesn't contain traversal sequences
+    if (!isValidRelativePath(normalizedPath)) {
+        throw new Error(`Invalid path: ${relativePath}`);
+    }
+    // Check if the path is in the indexed paths
+    if (!config.indexedPaths.includes(normalizedPath)) {
+        throw new Error(`Path not in documentation index: ${relativePath}\n\n` +
+            `Use docs_glob to find valid paths. The documentation index contains ${config.indexedPaths.length} pages.`);
+    }
+    // Validate path is within docs directory and resolve symlinks
+    // This returns the real (symlink-resolved) path
+    const realPath = validatePathWithinDocs(normalizedPath, config.docsBasePath);
+    // Check if file exists
+    if (!fs.existsSync(realPath)) {
+        throw new Error(`Documentation file not found: ${relativePath}`);
+    }
+    // Check file size to prevent DoS
+    const stat = fs.statSync(realPath);
+    if (stat.size > MAX_FILE_SIZE_BYTES) {
+        throw new Error(`File too large: ${relativePath} (${Math.round(stat.size / 1024)}KB exceeds ${MAX_FILE_SIZE_BYTES / 1024}KB limit)`);
+    }
+    // Read the file using the validated real path
+    const content = fs.readFileSync(realPath, 'utf-8');
+    const lineCount = content.split('\n').length;
+    const result = {
+        path: normalizedPath,
+        content,
+        lineCount,
+    };
+    return {
+        content: [{ type: 'text', text: content }],
+    };
+}

package/dist/docs/index.d.ts

@@ -0,0 +1,37 @@
+import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
+import { DOCS_GLOB_TOOL_DEFINITION, DOCS_GREP_TOOL_DEFINITION, DOCS_READ_TOOL_DEFINITION } from './tool.js';
+import type { DocsConfig } from './types.js';
+export type { DocsConfig } from './types.js';
+export { DOCS_GLOB_TOOL_DEFINITION, DOCS_GREP_TOOL_DEFINITION, DOCS_READ_TOOL_DEFINITION, };
+/**
+ * Tool definition with handler for MCP registration
+ */
+export interface DocsTool {
+    toolDefinition: {
+        name: string;
+        description: string;
+        inputSchema: object;
+    };
+    handler: (request: CallToolRequest) => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
+}
+/**
+ * Create the docs_glob tool
+ */
+export declare function createDocsGlobTool(config: DocsConfig): DocsTool;
+/**
+ * Create the docs_grep tool
+ */
+export declare function createDocsGrepTool(config: DocsConfig): DocsTool;
+/**
+ * Create the docs_read tool
+ */
+export declare function createDocsReadTool(config: DocsConfig): DocsTool;
+/**
+ * Create all docs tools at once
+ */
+export declare function createDocsTools(config: DocsConfig): DocsTool[];

package/dist/docs/index.js

@@ -0,0 +1,49 @@
+import { DocsGlobSchema, DocsGrepSchema, DocsReadSchema, DOCS_GLOB_TOOL_DEFINITION, DOCS_GREP_TOOL_DEFINITION, DOCS_READ_TOOL_DEFINITION, } from './tool.js';
+import { executeDocsGlob, executeDocsGrep, executeDocsRead } from './handler.js';
+export { DOCS_GLOB_TOOL_DEFINITION, DOCS_GREP_TOOL_DEFINITION, DOCS_READ_TOOL_DEFINITION, };
+/**
+ * Create the docs_glob tool
+ */
+export function createDocsGlobTool(config) {
+    return {
+        toolDefinition: DOCS_GLOB_TOOL_DEFINITION,
+        handler: async (request) => {
+            const parsed = DocsGlobSchema.parse(request.params.arguments);
+            return executeDocsGlob(config, parsed.pattern);
+        },
+    };
+}
+/**
+ * Create the docs_grep tool
+ */
+export function createDocsGrepTool(config) {
+    return {
+        toolDefinition: DOCS_GREP_TOOL_DEFINITION,
+        handler: async (request) => {
+            const parsed = DocsGrepSchema.parse(request.params.arguments);
+            return executeDocsGrep(config, parsed.query, parsed.maxResults);
+        },
+    };
+}
+/**
+ * Create the docs_read tool
+ */
+export function createDocsReadTool(config) {
+    return {
+        toolDefinition: DOCS_READ_TOOL_DEFINITION,
+        handler: async (request) => {
+            const parsed = DocsReadSchema.parse(request.params.arguments);
+            return executeDocsRead(config, parsed.path);
+        },
+    };
+}
+/**
+ * Create all docs tools at once
+ */
+export function createDocsTools(config) {
+    return [
+        createDocsGlobTool(config),
+        createDocsGrepTool(config),
+        createDocsReadTool(config),
+    ];
+}

package/dist/docs/tool.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export declare const DocsGlobSchema: z.ZodObject<{
+    pattern: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+}, {
+    pattern: string;
+}>;
+export declare const DOCS_GLOB_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            pattern: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const DocsGrepSchema: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    maxResults: number;
+}, {
+    query: string;
+    maxResults?: number | undefined;
+}>;
+export declare const DOCS_GREP_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            maxResults: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const DocsReadSchema: z.ZodObject<{
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+export declare const DOCS_READ_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/docs/tool.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+// =============================================================================
+// docs_glob - Find documentation files matching a pattern
+// =============================================================================
+export const DocsGlobSchema = z.object({
+    pattern: z
+        .string()
+        .describe('Glob pattern to match documentation files. Examples: "*.mdx", "integrations/**/*.mdx", "**/datadog*"'),
+});
+export const DOCS_GLOB_TOOL_DEFINITION = {
+    name: 'docs_glob',
+    description: `Find documentation files matching a glob pattern.
+
+Use this tool to discover which documentation pages exist before reading them.
+
+**Examples:**
+- Find all MDX files: \`pattern: "**/*.mdx"\`
+- Find integration docs: \`pattern: "integrations/**/*.mdx"\`
+- Find pages mentioning datadog: \`pattern: "**/datadog*"\`
+- Find all pages in a section: \`pattern: "setup/*.mdx"\`
+
+**Returns:** List of matching file paths (relative to docs root).`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'Glob pattern to match documentation files. Examples: "*.mdx", "integrations/**/*.mdx"',
+            },
+        },
+        required: ['pattern'],
+    },
+};
+// =============================================================================
+// docs_grep - Search documentation content
+// =============================================================================
+export const DocsGrepSchema = z.object({
+    query: z
+        .string()
+        .describe('Search query (case-insensitive substring match). Examples: "datadog integration", "API key", "webhook"'),
+    maxResults: z
+        .number()
+        .optional()
+        .default(50)
+        .describe('Maximum number of matches to return. Default: 50'),
+});
+export const DOCS_GREP_TOOL_DEFINITION = {
+    name: 'docs_grep',
+    description: `Search documentation content for a query string.
+
+Use this tool to find which documentation pages contain specific information.
+
+**Examples:**
+- Find pages about Datadog: \`query: "datadog"\`
+- Find API setup instructions: \`query: "API key"\`
+- Find webhook documentation: \`query: "webhook configuration"\`
+
+**Returns:** List of matches with file path, line number, and line content.
+Results are sorted by relevance (number of matches per file).`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search query (case-insensitive substring match). Examples: "datadog", "API key"',
+            },
+            maxResults: {
+                type: 'number',
+                description: 'Maximum number of matches to return. Default: 50',
+            },
+        },
+        required: ['query'],
+    },
+};
+// =============================================================================
+// docs_read - Read a documentation page
+// =============================================================================
+export const DocsReadSchema = z.object({
+    path: z
+        .string()
+        .describe('Path to the documentation file (relative to docs root). Must be an indexed path from docs_glob results.'),
+});
+export const DOCS_READ_TOOL_DEFINITION = {
+    name: 'docs_read',
+    description: `Read the content of a documentation page.
+
+**Important:** You can only read paths that exist in the documentation index.
+Use docs_glob first to find valid paths.
+
+**Examples:**
+- Read a specific page: \`path: "integrations/datadog.mdx"\`
+- Read setup guide: \`path: "setup/getting-started.mdx"\`
+
+**Returns:** Full content of the documentation page.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path to the documentation file (relative to docs root). Must be an indexed path.',
+            },
+        },
+        required: ['path'],
+    },
+};

package/dist/docs/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Configuration for the docs MCP tools
+ */
+export interface DocsConfig {
+    /**
+     * Base directory containing the documentation files.
+     * All tool operations are restricted to this directory.
+     */
+    docsBasePath: string;
+    /**
+     * Pre-indexed list of allowed document paths (relative to docsBasePath).
+     * Only these paths can be read. Glob and grep can search the directory,
+     * but read operations are restricted to indexed paths.
+     */
+    indexedPaths: string[];
+    /**
+     * Timeout for operations in milliseconds.
+     * Default: 30000 (30 seconds)
+     */
+    timeoutMs?: number;
+}
+/**
+ * Result from docs_glob operation
+ */
+export interface DocsGlobResult {
+    matchingPaths: string[];
+    totalMatches: number;
+}
+/**
+ * Result from docs_grep operation
+ */
+export interface DocsGrepMatch {
+    path: string;
+    lineNumber: number;
+    lineContent: string;
+}
+export interface DocsGrepResult {
+    matches: DocsGrepMatch[];
+    totalMatches: number;
+    truncated: boolean;
+}
+/**
+ * Result from docs_read operation
+ */
+export interface DocsReadResult {
+    path: string;
+    content: string;
+    lineCount: number;
+}

package/dist/docs/types.js

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

package/dist/index.js

@@ -18,9 +18,11 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { createJqTool } from './jq/index.js';
 import { createTimeseriesTool } from './timeseries/index.js';
+import { createDocsTools } from './docs/index.js';
 import { truncateResponseIfNeeded } from './truncation/index.js';
 import { createFileWriter } from './fileWriter/index.js';
 import { generateToolId } from './utils/filename.js';
@@ -115,6 +117,27 @@ const CHILD_COMMAND = process.env.MCP_PROXY_CHILD_COMMAND;
 const CHILD_ARGS = process.env.MCP_PROXY_CHILD_ARGS
     ? process.env.MCP_PROXY_CHILD_ARGS.split(',').map(s => s.trim()).filter(Boolean)
     : [];
+/**
+ * MCP_PROXY_REMOTE_URL (OPTIONAL)
+ * SSE URL of a remote MCP server to connect to instead of spawning a child process
+ * When set, the proxy connects as an SSE client to the remote server
+ * Example: "http://internal-server:3100/sse"
+ */
+const REMOTE_URL = process.env.MCP_PROXY_REMOTE_URL;
+/**
+ * MCP_PROXY_REMOTE_HEADERS (OPTIONAL)
+ * JSON string of custom headers to send with SSE/POST requests to the remote server
+ * Example: '{"X-Client-Credentials":"{\"prod\":{\"AWS_ACCESS_KEY_ID\":\"AKIA...\"}}"}'
+ */
+const REMOTE_HEADERS = process.env.MCP_PROXY_REMOTE_HEADERS;
+/**
+ * MCP_PROXY_REMOTE_CREDENTIALS (OPTIONAL)
+ * JSON string of credentials to send as X-Client-Credentials header to the remote server.
+ * This is a convenience alternative to embedding credentials inside MCP_PROXY_REMOTE_HEADERS,
+ * which requires triple-escaping nested JSON.
+ * Example: '{"prod":{"AWS_ACCESS_KEY_ID":"AKIA...","AWS_SECRET_ACCESS_KEY":"..."}}'
+ */
+const REMOTE_CREDENTIALS = process.env.MCP_PROXY_REMOTE_CREDENTIALS;
 /**
  * MCP_PROXY_MAX_TOKENS (OPTIONAL, default: 10000)
  * Maximum tokens before truncating responses
@@ -163,6 +186,27 @@ const JQ_TIMEOUT_MS = parseInt(process.env.MCP_PROXY_JQ_TIMEOUT_MS || '30000');
  * This tool allows detecting anomalies in time series data extracted from JSON files
  */
 const ENABLE_TIMESERIES = process.env.MCP_PROXY_ENABLE_TIMESERIES !== 'false'; // default true
+/**
+ * MCP_PROXY_ENABLE_DOCS (OPTIONAL, default: false)
+ * Enable the documentation tools (docs_glob, docs_grep, docs_read)
+ * Requires DOCS_BASE_PATH and DOCS_INDEXED_PATHS to be configured
+ */
+const ENABLE_DOCS = process.env.MCP_PROXY_ENABLE_DOCS === 'true'; // default false
+/**
+ * MCP_PROXY_DOCS_BASE_PATH (REQUIRED if ENABLE_DOCS=true)
+ * Base directory containing the documentation files
+ * All doc tool operations are restricted to this directory
+ */
+const DOCS_BASE_PATH = process.env.MCP_PROXY_DOCS_BASE_PATH || '';
+/**
+ * MCP_PROXY_DOCS_INDEXED_PATHS (REQUIRED if ENABLE_DOCS=true)
+ * Comma-separated list of indexed document paths (relative to DOCS_BASE_PATH)
+ * Only these paths can be read via docs_read
+ * Example: "integrations/datadog.mdx,setup/getting-started.mdx,faq.mdx"
+ */
+const DOCS_INDEXED_PATHS = process.env.MCP_PROXY_DOCS_INDEXED_PATHS
+    ? process.env.MCP_PROXY_DOCS_INDEXED_PATHS.split(',').map(s => s.trim()).filter(Boolean)
+    : [];
 /**
  * MCP_PROXY_SCHEMA_MAX_DEPTH (OPTIONAL, default: 3)
  * Maximum depth to traverse when generating query-assist schemas
@@ -191,19 +235,33 @@ const ENABLE_LOGGING = process.env.MCP_PROXY_ENABLE_LOGGING === 'true';
 // VALIDATION
 // ============================================================================
 // Validate configuration
-// CHILD_COMMAND is now optional - if not provided, proxy runs in standalone mode (JQ only)
-if (!CHILD_COMMAND) {
-    console.debug('[mcp-proxy] No child command specified - running in standalone mode (JQ only)');
+// CHILD_COMMAND and REMOTE_URL are optional - if neither provided, proxy runs in standalone mode (JQ only)
+if (!CHILD_COMMAND && !REMOTE_URL) {
+    console.debug('[mcp-proxy] No child command or remote URL specified - running in standalone mode (JQ only)');
     if (!ENABLE_JQ) {
         console.error('ERROR: Standalone mode requires JQ to be enabled (MCP_PROXY_ENABLE_JQ must not be false)');
         process.exit(1);
     }
 }
+if (CHILD_COMMAND && REMOTE_URL) {
+    console.error('ERROR: Cannot use both MCP_PROXY_CHILD_COMMAND and MCP_PROXY_REMOTE_URL');
+    process.exit(1);
+}
 if (WRITE_TO_FILE && !OUTPUT_PATH) {
     console.error('ERROR: MCP_PROXY_OUTPUT_PATH is required when MCP_PROXY_WRITE_TO_FILE=true');
     console.error('Example: export MCP_PROXY_OUTPUT_PATH="/tmp/mcp-results"');
     process.exit(1);
 }
+if (ENABLE_DOCS && !DOCS_BASE_PATH) {
+    console.error('ERROR: MCP_PROXY_DOCS_BASE_PATH is required when MCP_PROXY_ENABLE_DOCS=true');
+    console.error('Example: export MCP_PROXY_DOCS_BASE_PATH="/app/docs"');
+    process.exit(1);
+}
+if (ENABLE_DOCS && DOCS_INDEXED_PATHS.length === 0) {
+    console.error('ERROR: MCP_PROXY_DOCS_INDEXED_PATHS is required when MCP_PROXY_ENABLE_DOCS=true');
+    console.error('Example: export MCP_PROXY_DOCS_INDEXED_PATHS="page1.mdx,page2.mdx,folder/page3.mdx"');
+    process.exit(1);
+}
 // ============================================================================
 // PASS-THROUGH ENVIRONMENT VARIABLES
 // ============================================================================
@@ -237,8 +295,13 @@ for (const [key, value] of Object.entries(process.env)) {
 // ============================================================================
 if (ENABLE_LOGGING) {
     console.debug('[mcp-proxy] Configuration:');
-    console.debug(`  Mode: ${CHILD_COMMAND ? 'wrapper' : 'standalone (JQ only)'}`);
-    if (CHILD_COMMAND) {
+    console.debug(`  Mode: ${REMOTE_URL ? 'remote (SSE)' : CHILD_COMMAND ? 'wrapper' : 'standalone (JQ only)'}`);
+    if (REMOTE_URL) {
+        console.debug(`  Remote URL: ${REMOTE_URL}`);
+        console.debug(`  Remote headers: ${REMOTE_HEADERS ? 'configured' : 'none'}`);
+        console.debug(`  Remote credentials: ${REMOTE_CREDENTIALS ? 'configured' : 'none'}`);
+    }
+    else if (CHILD_COMMAND) {
         console.debug(`  Child command: ${CHILD_COMMAND}`);
         console.debug(`  Child args: [${CHILD_ARGS.join(', ')}]`);
     }
@@ -251,6 +314,11 @@ if (ENABLE_LOGGING) {
     }
     console.debug(`  JQ tool enabled: ${ENABLE_JQ}`);
     console.debug(`  Timeseries tool enabled: ${ENABLE_TIMESERIES}`);
+    console.debug(`  Docs tools enabled: ${ENABLE_DOCS}`);
+    if (ENABLE_DOCS) {
+        console.debug(`  Docs base path: ${DOCS_BASE_PATH}`);
+        console.debug(`  Docs indexed paths: ${DOCS_INDEXED_PATHS.length} pages`);
+    }
     if (CHILD_COMMAND) {
         console.debug(`  Pass-through env vars: ${Object.keys(childEnv).length}`);
     }
@@ -265,7 +333,61 @@ async function main() {
     // ------------------------------------------------------------------------
     let childClient = null;
     let childToolsResponse = { tools: [] };
-    if (CHILD_COMMAND) {
+    if (REMOTE_URL) {
+        // Remote mode: connect to a remote MCP server over SSE
+        console.debug(`[mcp-proxy] Connecting to remote MCP: ${REMOTE_URL}`);
+        let headers = {};
+        if (REMOTE_HEADERS) {
+            try {
+                headers = JSON.parse(REMOTE_HEADERS);
+            }
+            catch (e) {
+                console.error('ERROR: MCP_PROXY_REMOTE_HEADERS contains invalid JSON');
+                console.error(`  Value: ${REMOTE_HEADERS.substring(0, 100)}${REMOTE_HEADERS.length > 100 ? '...' : ''}`);
+                console.error(`  Parse error: ${e instanceof Error ? e.message : String(e)}`);
+                process.exit(1);
+            }
+        }
+        if (REMOTE_CREDENTIALS) {
+            try {
+                JSON.parse(REMOTE_CREDENTIALS); // Validate JSON before sending
+            }
+            catch (e) {
+                console.error('ERROR: MCP_PROXY_REMOTE_CREDENTIALS contains invalid JSON');
+                console.error(`  Value: ${REMOTE_CREDENTIALS.substring(0, 100)}${REMOTE_CREDENTIALS.length > 100 ? '...' : ''}`);
+                console.error(`  Parse error: ${e instanceof Error ? e.message : String(e)}`);
+                process.exit(1);
+            }
+            headers['X-Client-Credentials'] = REMOTE_CREDENTIALS;
+        }
+        const childTransport = new SSEClientTransport(new URL(REMOTE_URL), {
+            eventSourceInit: {
+                fetch: (url, init) => {
+                    // Safely convert init.headers (could be Headers object, array, or plain object)
+                    const initHeaders = init?.headers
+                        ? Object.fromEntries(new Headers(init.headers))
+                        : {};
+                    return fetch(url, {
+                        ...init,
+                        headers: { ...initHeaders, ...headers },
+                    });
+                },
+            },
+            requestInit: { headers },
+        });
+        childClient = new Client({
+            name: 'mcp-proxy-client',
+            version: '1.0.0'
+        }, {
+            capabilities: {}
+        });
+        await childClient.connect(childTransport);
+        console.debug('[mcp-proxy] Connected to remote MCP');
+        // Discover tools from remote MCP
+        childToolsResponse = await childClient.listTools();
+        console.debug(`[mcp-proxy] Discovered ${childToolsResponse.tools.length} tools from remote MCP`);
+    }
+    else if (CHILD_COMMAND) {
         console.debug(`[mcp-proxy] Spawning child MCP: ${CHILD_COMMAND}`);
         const childTransport = new StdioClientTransport({
             command: CHILD_COMMAND,
@@ -343,6 +465,18 @@ async function main() {
             timeoutMs: JQ_TIMEOUT_MS // Uses same timeout as JQ since it runs jq internally
         });
     }
+    // Docs tools configuration
+    let docsTools = [];
+    if (ENABLE_DOCS) {
+        docsTools = createDocsTools({
+            docsBasePath: DOCS_BASE_PATH,
+            indexedPaths: DOCS_INDEXED_PATHS,
+            timeoutMs: JQ_TIMEOUT_MS
+        });
+        if (ENABLE_LOGGING) {
+            console.debug(`[mcp-proxy] Docs tools created: ${docsTools.map(t => t.toolDefinition.name).join(', ')}`);
+        }
+    }
     // ------------------------------------------------------------------------
     // 5. REGISTER ALL TOOLS (CHILD + PROXY) WITH DESCRIPTION INJECTION
     // ------------------------------------------------------------------------
@@ -351,9 +485,10 @@ async function main() {
     const allTools = [
         ...enhancedChildTools,
         ...(jqTool ? [jqTool.toolDefinition] : []), // JQ tool already has description param
-        ...(timeseriesTool ? [timeseriesTool.toolDefinition] : []) // Timeseries tool already has description param
+        ...(timeseriesTool ? [timeseriesTool.toolDefinition] : []), // Timeseries tool already has description param
+        ...docsTools.map(t => t.toolDefinition) // Docs tools (if enabled)
     ];
-    const proxyToolCount = (jqTool ? 1 : 0) + (timeseriesTool ? 1 : 0);
+    const proxyToolCount = (jqTool ? 1 : 0) + (timeseriesTool ? 1 : 0) + docsTools.length;
     console.debug(`[mcp-proxy] Exposing ${allTools.length} tools total (${childToolsResponse.tools.length} from child + ${proxyToolCount} proxy tools)`);
     // ------------------------------------------------------------------------
     // 6. HANDLE TOOL LIST REQUESTS
@@ -430,6 +565,69 @@ async function main() {
                     isError: result.isError
                 };
             }
+            // Handle Docs tools locally (if enabled)
+            // Route through file writer for large doc handling (same as child MCP tools)
+            const docsToolNames = ['docs_glob', 'docs_grep', 'docs_read'];
+            if (docsToolNames.includes(toolName) && docsTools.length > 0) {
+                const docTool = docsTools.find(t => t.toolDefinition.name === toolName);
+                if (docTool) {
+                    if (ENABLE_LOGGING) {
+                        console.debug(`[mcp-proxy] Executing ${toolName} locally`);
+                    }
+                    try {
+                        result = await docTool.handler({
+                            params: { arguments: toolArgs }
+                        });
+                        const contentStr = result.content?.[0]?.text || '';
+                        const originalLength = contentStr.length;
+                        // Route through file writer (same pipeline as child MCP tools)
+                        const unifiedResponse = await fileWriter.handleResponse(toolName, toolArgs, {
+                            content: [{ type: 'text', text: contentStr }]
+                        });
+                        if (ENABLE_LOGGING) {
+                            if (unifiedResponse.wroteToFile) {
+                                console.debug(`[mcp-proxy] File written for ${toolName} (${originalLength} chars) → ${unifiedResponse.filePath}`);
+                            }
+                            else {
+                                console.debug(`[mcp-proxy] Response for ${toolName} (${originalLength} chars) returned directly`);
+                            }
+                        }
+                        // If not written to file, apply truncation to outputContent
+                        if (!unifiedResponse.wroteToFile && unifiedResponse.outputContent) {
+                            const outputStr = typeof unifiedResponse.outputContent === 'string'
+                                ? unifiedResponse.outputContent
+                                : JSON.stringify(unifiedResponse.outputContent);
+                            const truncated = truncateResponseIfNeeded(truncationConfig, outputStr);
+                            if (truncated.length < outputStr.length) {
+                                if (ENABLE_LOGGING) {
+                                    console.debug(`[mcp-proxy] Truncated response: ${outputStr.length} → ${truncated.length} chars`);
+                                }
+                                // Keep as string for docs (markdown content)
+                                unifiedResponse.outputContent = truncated;
+                            }
+                        }
+                        // Add retry metadata and return unified response
+                        addRetryMetadata(unifiedResponse, toolArgs);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify(unifiedResponse, null, 2)
+                                }],
+                            isError: false
+                        };
+                    }
+                    catch (error) {
+                        const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify(createErrorResponse(tool_id, error.message || String(error), toolArgs), null, 2)
+                                }],
+                            isError: true
+                        };
+                    }
+                }
+            }
             // Forward all other tools to child MCP (if child exists)
             if (!childClient) {
                 const tool_id = generateToolId(toolName, toolArgs, fileWriterConfig.toolAbbreviations);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyshift/mcp-proxy",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Generic MCP proxy that adds truncation, file writing, and JQ capabilities to any MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.0",
+    "glob": "^13.0.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {