@nimrobo/mcporter-remote 0.1.0

package/tests/emit-ts.test.ts

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { __test as emitTsTestInternals, handleEmitTs } from '../src/cli/emit-ts-command.js';
+import { renderClientModule, renderTypesModule } from '../src/cli/emit-ts-templates.js';
+import { buildToolMetadata } from '../src/cli/generate/tools.js';
+import type { Runtime } from '../src/runtime.js';
+import { integrationDefinition, listCommentsTool } from './fixtures/tool-fixtures.js';
+
+function createRuntimeStub(): Runtime {
+  return {
+    listServers: () => ['integration'],
+    getDefinitions: () => [integrationDefinition],
+    getDefinition: (name: string) => {
+      if (name !== 'integration') {
+        throw new Error(`Server '${name}' not found.`);
+      }
+      return integrationDefinition;
+    },
+    registerDefinition: () => {},
+    listTools: async () => [listCommentsTool],
+    callTool: async () => ({}),
+    listResources: async () => ({}),
+    connect: async () => {
+      throw new Error('not implemented');
+    },
+    close: async () => {},
+  } as unknown as Runtime;
+}
+
+describe('emit-ts templates', () => {
+  it('renders type declarations with CallResult returns', () => {
+    const docs = emitTsTestInternals.buildDocEntries('integration', [buildToolMetadata(listCommentsTool)], false);
+    const metadata = {
+      server: integrationDefinition,
+      generatorLabel: 'mcporter@test',
+      generatedAt: new Date('2025-11-07T00:00:00Z'),
+    };
+    const source = renderTypesModule({ interfaceName: 'IntegrationTools', docs, metadata });
+    expect(source).toContain('export interface IntegrationTools');
+    expect(source).toContain('Promise<CommentList>');
+    expect(source).toContain('Issue identifier');
+  });
+
+  it('renders client module that wraps proxy calls', () => {
+    const docs = emitTsTestInternals.buildDocEntries('integration', [buildToolMetadata(listCommentsTool)], true);
+    const metadata = {
+      server: integrationDefinition,
+      generatorLabel: 'mcporter@test',
+      generatedAt: new Date('2025-11-07T00:00:00Z'),
+    };
+    const source = renderClientModule({
+      interfaceName: 'IntegrationTools',
+      docs,
+      metadata,
+      typesImportPath: './integration-client',
+    });
+    expect(source).toContain('createIntegrationClient');
+    expect(source).toContain('wrapCallResult');
+    expect(source).toContain('proxy.listComments');
+  });
+});
+
+describe('handleEmitTs', () => {
+  it('writes client and types files to disk', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'emit-ts-'));
+    const runtime = createRuntimeStub();
+    const clientPath = path.join(tmpDir, 'integration-client.ts');
+    await handleEmitTs(runtime, ['integration', '--out', clientPath, '--mode', 'client']);
+    const typesPath = path.join(tmpDir, 'integration-client.d.ts');
+    const clientSource = await fs.readFile(clientPath, 'utf8');
+    const typesSource = await fs.readFile(typesPath, 'utf8');
+    expect(clientSource).toContain('createIntegrationClient');
+    expect(typesSource).toContain('export interface IntegrationTools');
+  });
+
+  it('resolves HTTP selectors when emitting definitions', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'emit-ts-http-'));
+    const runtime = createRuntimeStub();
+    const typesPath = path.join(tmpDir, 'integration-tools.d.ts');
+    await handleEmitTs(runtime, ['https://www.example.com/mcp.getComponents', '--out', typesPath, '--mode', 'types']);
+    const typesSource = await fs.readFile(typesPath, 'utf8');
+    expect(typesSource).toContain('export interface HttpsWwwExampleComMcpGetComponentsTools');
+  });
+
+  it('accepts scheme-less HTTP selectors when emitting definitions', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'emit-ts-http-scheme-'));
+    const runtime = createRuntimeStub();
+    const typesPath = path.join(tmpDir, 'integration-tools.d.ts');
+    await handleEmitTs(runtime, ['example.com/mcp.getComponents', '--out', typesPath, '--mode', 'types']);
+    const typesSource = await fs.readFile(typesPath, 'utf8');
+    expect(typesSource).toContain('export interface ExampleComMcpGetComponentsTools');
+  });
+
+  it('emits JSON summaries when --json is provided', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'emit-ts-json-'));
+    const runtime = createRuntimeStub();
+    const typesPath = path.join(tmpDir, 'integration-tools.d.ts');
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleEmitTs(runtime, ['integration', '--out', typesPath, '--mode', 'types', '--json']);
+    const payload = JSON.parse(logSpy.mock.calls.at(-1)?.[0] ?? '{}');
+    expect(payload.mode).toBe('types');
+    expect(payload.server).toBe('integration');
+    logSpy.mockRestore();
+  });
+
+  it('emits JSON summaries for client mode', async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'emit-ts-json-client-'));
+    const runtime = createRuntimeStub();
+    const clientPath = path.join(tmpDir, 'integration-client.ts');
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    await handleEmitTs(runtime, ['integration', '--out', clientPath, '--mode', 'client', '--json']);
+    const payload = JSON.parse(logSpy.mock.calls.at(-1)?.[0] ?? '{}');
+    expect(payload.mode).toBe('client');
+    expect(payload.clientOutPath).toBe(clientPath);
+    expect(payload.typesOutPath.endsWith('.d.ts')).toBe(true);
+    const typesExists = await fs
+      .access(payload.typesOutPath)
+      .then(() => true)
+      .catch(() => false);
+    expect(typesExists).toBe(true);
+    logSpy.mockRestore();
+  });
+});

package/tests/ephemeral-target.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it, vi } from 'vitest';
+import { prepareEphemeralServerTarget } from '../src/cli/ephemeral-target.js';
+import type { Runtime } from '../src/runtime.js';
+
+function createRuntimeStub(): Runtime {
+  return {
+    getDefinitions: vi.fn(() => []),
+    registerDefinition: vi.fn(),
+  } as unknown as Runtime;
+}
+
+describe('prepareEphemeralServerTarget', () => {
+  it('auto-detects inline npx commands as ad-hoc STDIO servers', async () => {
+    const runtime = createRuntimeStub();
+    const { target, resolution } = await prepareEphemeralServerTarget({
+      runtime,
+      target: 'npx -y xcodebuildmcp',
+    });
+    expect(target).toBe('xcodebuildmcp');
+    expect(resolution?.definition.command.kind).toBe('stdio');
+    if (resolution?.definition.command.kind !== 'stdio') {
+      throw new Error('Expected stdio command');
+    }
+    expect(resolution.definition.command.command).toBe('npx');
+  });
+});

package/tests/error-classifier.test.ts

@@ -0,0 +1,46 @@
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import { describe, expect, it } from 'vitest';
+import { analyzeConnectionError } from '../src/error-classifier.js';
+
+describe('analyzeConnectionError', () => {
+  it('detects UnauthorizedError instances', () => {
+    const issue = analyzeConnectionError(new UnauthorizedError('needs auth'));
+    expect(issue.kind).toBe('auth');
+  });
+
+  it('flags offline transport failures', () => {
+    const issue = analyzeConnectionError(new Error('fetch failed: connect ECONNREFUSED 127.0.0.1:9000'));
+    expect(issue.kind).toBe('offline');
+  });
+
+  it('parses stdio exit codes', () => {
+    const issue = analyzeConnectionError(new Error('STDIO transport exited with code 2 (signal SIGTERM)'));
+    expect(issue.kind).toBe('stdio-exit');
+    expect(issue.stdioExitCode).toBe(2);
+    expect(issue.stdioSignal).toBe('SIGTERM');
+  });
+
+  it('extracts HTTP status codes from plain text', () => {
+    const issue = analyzeConnectionError(new Error('HTTP error 429: rate limited'));
+    expect(issue.kind).toBe('http');
+    expect(issue.statusCode).toBe(429);
+  });
+
+  it.each([401, 403] as const)('keeps %s classified as auth', (status) => {
+    const issue = analyzeConnectionError(new Error(`SSE error: Non-200 status code (${status})`));
+    expect(issue.kind).toBe('auth');
+    expect(issue.statusCode).toBe(status);
+  });
+
+  it('classifies HTTP 405 as transport/http instead of auth', () => {
+    const issue = analyzeConnectionError(new Error('SSE error: Non-200 status code (405)'));
+    expect(issue.kind).toBe('http');
+    expect(issue.statusCode).toBe(405);
+  });
+
+  it('extracts HTTP status codes from JSON payloads', () => {
+    const issue = analyzeConnectionError(new Error('{"error":{"status":503}}'));
+    expect(issue.kind).toBe('http');
+    expect(issue.statusCode).toBe(503);
+  });
+});

package/tests/fixtures/ansi.ts

@@ -0,0 +1,18 @@
+export function stripAnsi(value: string): string {
+  let result = '';
+  let index = 0;
+  while (index < value.length) {
+    const char = value[index];
+    if (char === '\u001B') {
+      index += 1;
+      while (index < value.length && value[index] !== 'm') {
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+    result += char;
+    index += 1;
+  }
+  return result;
+}

package/tests/fixtures/cli-list-fixtures.ts

@@ -0,0 +1,43 @@
+import type { ServerDefinition } from '../../src/config.js';
+
+process.env.MCPORTER_DISABLE_AUTORUN = '1';
+
+export const cliModulePromise = import('../../src/cli.js');
+
+export const linearDefinition: ServerDefinition = {
+  name: 'linear',
+  description: 'Hosted Linear MCP',
+  command: { kind: 'http', url: new URL('https://example.com/mcp') },
+};
+
+export const buildLinearDocumentsTool = (includeSchema?: boolean) => ({
+  name: 'list_documents',
+  description: "List documents in the user's Linear workspace",
+  inputSchema: includeSchema
+    ? {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'The search query' },
+          limit: { type: 'number', description: 'Maximum number of documents to return' },
+          before: { type: 'string', description: 'Cursor to page backwards' },
+          after: { type: 'string', description: 'Cursor to page forwards' },
+          orderBy: {
+            type: 'string',
+            description: 'Sort order for the documents',
+            enum: ['createdAt', 'updatedAt'],
+          },
+          projectId: { type: 'string', description: 'Filter by project' },
+          initiativeId: { type: 'string', description: 'Filter by initiative' },
+          creatorId: { type: 'string', description: 'Filter by creator' },
+          includeArchived: { type: 'boolean', description: 'Whether to include archived documents' },
+        },
+        required: ['query'],
+      }
+    : undefined,
+  outputSchema: includeSchema
+    ? {
+        title: 'DocumentConnection',
+        type: 'object',
+      }
+    : undefined,
+});

package/tests/fixtures/config-fixture.ts

@@ -0,0 +1,29 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { LoadConfigOptions, RawConfig } from '../../src/config.js';
+
+type TempConfigCtx = {
+  tempDir: string;
+  configPath: string;
+  loadOptions: LoadConfigOptions;
+  cleanup(): Promise<void>;
+};
+
+export async function createTempConfig(initial?: RawConfig): Promise<TempConfigCtx> {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcporter-config-fixture-'));
+  const configPath = path.join(tempDir, 'config', 'mcporter.json');
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  if (initial) {
+    await fs.writeFile(configPath, JSON.stringify(initial), 'utf8');
+  }
+  const loadOptions: LoadConfigOptions = { rootDir: tempDir, configPath };
+  return {
+    tempDir,
+    configPath,
+    loadOptions,
+    async cleanup() {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    },
+  };
+}

package/tests/fixtures/imports/.claude/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "claude-only": {
+      "command": "claude-cli",
+      "args": ["--run"]
+    }
+  }
+}

package/tests/fixtures/imports/.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "claude-shared": {
+      "command": "claude-shared-cli"
+    },
+    "claude-overridden": {
+      "command": "claude-shared-cli"
+    }
+  }
+}

package/tests/fixtures/imports/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "claude-local": {
+      "command": "claude-local-cli"
+    },
+    "claude-overridden": {
+      "command": "claude-local-cli"
+    }
+  }
+}

package/tests/fixtures/imports/.codeium/windsurf/mcp_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "shared": {
+      "baseUrl": "https://windsurf.local/mcp"
+    },
+    "windsurf-only": {
+      "command": "windsurf-cli",
+      "args": ["--list"],
+      "env": {
+        "WINDSURF": "1"
+      }
+    }
+  }
+}

package/tests/fixtures/imports/.codex/config.toml

@@ -0,0 +1,7 @@
+[mcp_servers]
+[mcp_servers.shared]
+url = "https://codex.local/mcp"
+
+[mcp_servers."codex-only"]
+command = "codex-cli"
+args = ["--run"]

package/tests/fixtures/imports/.config/opencode/opencode.jsonc

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "opencode-user-only": {
+      "description": "User-level OpenCode server",
+      "command": "opencode-user-cli",
+      "args": ["--json"]
+    }
+  }
+}

package/tests/fixtures/imports/.cursor/mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "shared": {
+      "baseUrl": "https://cursor.local/mcp"
+    },
+    "cursor-only": {
+      "command": "cursor-cli",
+      "args": ["--flag"],
+      "env": {
+        "CURSOR_FLAG": "1"
+      }
+    }
+  }
+}

package/tests/fixtures/imports/Library/Application Support/Code/User/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "shared": {
+      "baseUrl": "https://vscode.local/mcp"
+    },
+    "vscode-only": {
+      "command": "code-mcp",
+      "args": ["--serve"]
+    }
+  }
+}

package/tests/fixtures/imports/config/mcporter.json

@@ -0,0 +1,11 @@
+{
+  "imports": ["cursor", "claude-code", "codex"],
+  "mcpServers": {
+    "local-only": {
+      "baseUrl": "https://local.example/mcp"
+    },
+    "cursor-only": {
+      "baseUrl": "https://local.override/cursor"
+    }
+  }
+}

package/tests/fixtures/imports/home/.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "claude-home": {
+      "command": "claude-home-cli"
+    }
+  }
+}

package/tests/fixtures/imports/home/.codeium/windsurf/mcp_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "shared": {
+      "baseUrl": "https://windsurf.local/mcp"
+    },
+    "windsurf-only": {
+      "command": "windsurf-cli",
+      "args": ["--list"],
+      "env": {
+        "WINDSURF": "1"
+      }
+    }
+  }
+}

package/tests/fixtures/imports/home/.codex/config.toml

@@ -0,0 +1,7 @@
+[mcp_servers]
+[mcp_servers.shared]
+url = "https://codex.local/mcp"
+
+[mcp_servers."codex-only"]
+command = "codex-cli"
+args = ["--run"]

package/tests/fixtures/imports/home/Library/Application Support/Code/User/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "shared": {
+      "baseUrl": "https://vscode.local/mcp"
+    },
+    "vscode-only": {
+      "command": "code-mcp",
+      "args": ["--serve"]
+    }
+  }
+}

package/tests/fixtures/imports/opencode.jsonc

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "opencode-only": {
+      "description": "Project-level OpenCode server",
+      "type": "stdio",
+      "command": "opencode-cli",
+      "args": ["serve"]
+    }
+  }
+}

package/tests/fixtures/mcporter.json

@@ -0,0 +1,64 @@
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "description": "Chrome DevTools protocol bridge for driving local tabs during debugging or automation.",
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"],
+      "env": {
+        "npm_config_loglevel": "error"
+      }
+    },
+    "context7": {
+      "description": "Context7 MCP for React documentation lookup.",
+      "baseUrl": "https://mcp.context7.com/mcp"
+    },
+    "linear": {
+      "description": "Hosted Linear MCP; exposes issue search, create, and workflow tooling.",
+      "baseUrl": "https://mcp.linear.app/mcp",
+      "headers": {
+        "Authorization": "Bearer ${LINEAR_API_KEY}"
+      }
+    },
+    "next-devtools": {
+      "description": "Next.js dev server introspection (project metadata, logs, page insights).",
+      "baseUrl": "http://localhost:3000/_next/mcp"
+    },
+    "playwright": {
+      "description": "Playwright MCP server for accessibility-driven automation.",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "env": {
+        "npm_config_loglevel": "error"
+      }
+    },
+    "vercel": {
+      "description": "Vercel MCP (requires OAuth).",
+      "baseUrl": "https://mcp.vercel.com",
+      "auth": "oauth",
+      "tokenCacheDir": "~/.mcporter/vercel"
+    },
+    "firecrawl": {
+      "description": "Firecrawl hosted MCP for authenticated scraping and extraction.",
+      "baseUrl": "https://mcp.firecrawl.dev/v2/mcp",
+      "headers": {
+        "Authorization": "Bearer ${FIRECRAWL_API_KEY}"
+      }
+    },
+    "signoz": {
+      "description": "SigNoz Query MCP server (logs, traces, metrics).",
+      "command": "npx",
+      "args": ["-y", "signoz-mcp-server@latest"],
+      "env": {
+        "SIGNOZ_URL": "${SIGNOZ_URL:-http://localhost:3301}",
+        "SIGNOZ_TOKEN": "${SIGNOZ_TOKEN:-}",
+        "npm_config_loglevel": "error",
+        "NODE_OPTIONS": "--require=./scripts/mcp_signoz_retry_patch.cjs"
+      }
+    },
+    "shadcn": {
+      "description": "shadcn/ui registry MCP for browsing component recipes.",
+      "baseUrl": "https://www.shadcn.io/api/mcp"
+    }
+  },
+  "imports": []
+}

package/tests/fixtures/stdio-filesystem-server.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const rootDir = path.resolve(process.argv[2] ?? process.cwd());
+
+const server = new McpServer({ name: 'fs-fixture', version: '1.0.0' });
+
+server.registerTool(
+  'list_files',
+  {
+    title: 'List Files',
+    description: 'List the files in the configured root',
+    inputSchema: {},
+    outputSchema: {
+      files: z.array(z.string()),
+    },
+  },
+  async () => {
+    const entries = await fs.readdir(rootDir);
+    return {
+      content: [{ type: 'text', text: entries.join('\n') }],
+      structuredContent: { files: entries },
+    };
+  }
+);
+
+server.registerTool(
+  'read_text_file',
+  {
+    title: 'Read Text File',
+    description: 'Read a UTF-8 file relative to the MCP root',
+    inputSchema: {
+      path: z.string().describe('Relative path inside the root directory'),
+    },
+    outputSchema: {
+      contents: z.string(),
+    },
+  },
+  async ({ path: relativePath }) => {
+    const targetPath = path.resolve(rootDir, relativePath);
+    if (!targetPath.startsWith(rootDir)) {
+      throw new Error('path escapes configured root');
+    }
+    const data = await fs.readFile(targetPath, 'utf8');
+    return {
+      content: [{ type: 'text', text: data }],
+      structuredContent: { contents: data },
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+await new Promise((resolve, reject) => {
+  transport.onclose = resolve;
+  transport.onerror = reject;
+});

package/tests/fixtures/stdio-memory-server.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'memory-fixture', version: '1.0.0' });
+const memory = new Set();
+
+server.registerTool(
+  'create_entities',
+  {
+    title: 'Create Entities',
+    description: 'Insert the provided entity names into the in-memory store',
+    inputSchema: {
+      entities: z.array(z.string()),
+    },
+    outputSchema: {
+      count: z.number(),
+    },
+  },
+  async ({ entities }) => {
+    for (const entity of entities) {
+      if (entity.trim().length > 0) {
+        memory.add(entity.trim());
+      }
+    }
+    return {
+      content: [{ type: 'text', text: `Stored ${memory.size} entities` }],
+      structuredContent: { count: memory.size },
+    };
+  }
+);
+
+server.registerTool(
+  'list_entities',
+  {
+    title: 'List Entities',
+    description: 'Return all previously stored entities',
+    inputSchema: {},
+    outputSchema: {
+      entities: z.array(z.string()),
+    },
+  },
+  async () => {
+    return {
+      content: [{ type: 'text', text: JSON.stringify(Array.from(memory)) }],
+      structuredContent: { entities: Array.from(memory) },
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+await new Promise((resolve, reject) => {
+  transport.onclose = resolve;
+  transport.onerror = reject;
+});

package/tests/fixtures/test-helpers.ts

@@ -0,0 +1,24 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+// Generates a short-lived temp directory with a stable, short base to avoid
+// UNIX-domain socket length issues on macOS/Linux. On Windows we stick to the
+// platform temp dir.
+export async function makeShortTempDir(prefix: string): Promise<string> {
+  const baseDir = process.platform === 'win32' ? os.tmpdir() : '/tmp';
+  const dir = path.join(baseDir, `${prefix}-${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 8)}`);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+// Safely restore cwd when running under Vitest workers (which disallow chdir).
+export function restoreCwdSafely(originalCwd: string): void {
+  try {
+    process.chdir(originalCwd);
+  } catch (error) {
+    if (!(error instanceof Error) || !/chdir\(\) is not supported/.test(error.message)) {
+      throw error;
+    }
+  }
+}