@contextstream/mcp-server 0.2.5

package/src/config.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+const configSchema = z.object({
+  apiUrl: z.string().url(),
+  apiKey: z.string().min(1).optional(),
+  jwt: z.string().min(1).optional(),
+  defaultWorkspaceId: z.string().uuid().optional(),
+  defaultProjectId: z.string().uuid().optional(),
+  userAgent: z.string().default('contextstream-mcp/0.1.0'),
+});
+
+export type Config = z.infer<typeof configSchema>;
+
+export function loadConfig(): Config {
+  const parsed = configSchema.safeParse({
+    apiUrl: process.env.CONTEXTSTREAM_API_URL,
+    apiKey: process.env.CONTEXTSTREAM_API_KEY,
+    jwt: process.env.CONTEXTSTREAM_JWT,
+    defaultWorkspaceId: process.env.CONTEXTSTREAM_WORKSPACE_ID,
+    defaultProjectId: process.env.CONTEXTSTREAM_PROJECT_ID,
+    userAgent: process.env.CONTEXTSTREAM_USER_AGENT,
+  });
+
+  if (!parsed.success) {
+    const missing = parsed.error.errors.map((e) => e.path.join('.')).join(', ');
+    throw new Error(
+      `Invalid configuration. Set CONTEXTSTREAM_API_URL (and API key or JWT). Missing/invalid: ${missing}`
+    );
+  }
+
+  if (!parsed.data.apiKey && !parsed.data.jwt) {
+    throw new Error('Set CONTEXTSTREAM_API_KEY or CONTEXTSTREAM_JWT for authentication.');
+  }
+
+  return parsed.data;
+}

package/src/files.ts

@@ -0,0 +1,261 @@
+/**
+ * File reading utilities for code indexing
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface FileToIngest {
+  path: string;
+  content: string;
+  language?: string;
+}
+
+// File extensions to include for indexing
+const CODE_EXTENSIONS = new Set([
+  // Rust
+  'rs',
+  // TypeScript/JavaScript
+  'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs',
+  // Python
+  'py', 'pyi',
+  // Go
+  'go',
+  // Java/Kotlin
+  'java', 'kt', 'kts',
+  // C/C++
+  'c', 'h', 'cpp', 'hpp', 'cc', 'cxx',
+  // C#
+  'cs',
+  // Ruby
+  'rb',
+  // PHP
+  'php',
+  // Swift
+  'swift',
+  // Scala
+  'scala',
+  // Shell
+  'sh', 'bash', 'zsh',
+  // Config/Data
+  'json', 'yaml', 'yml', 'toml', 'xml',
+  // SQL
+  'sql',
+  // Markdown/Docs
+  'md', 'markdown', 'rst', 'txt',
+  // HTML/CSS
+  'html', 'htm', 'css', 'scss', 'sass', 'less',
+  // Other
+  'graphql', 'proto', 'dockerfile',
+]);
+
+// Directories to ignore
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.svn',
+  '.hg',
+  'target',
+  'dist',
+  'build',
+  'out',
+  '.next',
+  '.nuxt',
+  '__pycache__',
+  '.pytest_cache',
+  '.mypy_cache',
+  'venv',
+  '.venv',
+  'env',
+  '.env',
+  'vendor',
+  'coverage',
+  '.coverage',
+  '.idea',
+  '.vscode',
+  '.vs',
+]);
+
+// Files to ignore
+const IGNORE_FILES = new Set([
+  '.DS_Store',
+  'Thumbs.db',
+  '.gitignore',
+  '.gitattributes',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'Cargo.lock',
+  'poetry.lock',
+  'Gemfile.lock',
+  'composer.lock',
+]);
+
+// Max file size to index (1MB)
+const MAX_FILE_SIZE = 1024 * 1024;
+
+// Max number of files to index in one batch
+const MAX_FILES_PER_BATCH = 100;
+
+/**
+ * Read all indexable files from a directory
+ */
+export async function readFilesFromDirectory(
+  rootPath: string,
+  options: {
+    maxFiles?: number;
+    maxFileSize?: number;
+  } = {}
+): Promise<FileToIngest[]> {
+  const maxFiles = options.maxFiles ?? MAX_FILES_PER_BATCH;
+  const maxFileSize = options.maxFileSize ?? MAX_FILE_SIZE;
+  const files: FileToIngest[] = [];
+
+  async function walkDir(dir: string, relativePath: string = ''): Promise<void> {
+    if (files.length >= maxFiles) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // Skip directories we can't read
+    }
+
+    for (const entry of entries) {
+      if (files.length >= maxFiles) break;
+
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.join(relativePath, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip ignored directories
+        if (IGNORE_DIRS.has(entry.name)) continue;
+        await walkDir(fullPath, relPath);
+      } else if (entry.isFile()) {
+        // Skip ignored files
+        if (IGNORE_FILES.has(entry.name)) continue;
+
+        // Check extension
+        const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+        if (!CODE_EXTENSIONS.has(ext)) continue;
+
+        // Check file size
+        try {
+          const stat = await fs.promises.stat(fullPath);
+          if (stat.size > maxFileSize) continue;
+
+          // Read file content
+          const content = await fs.promises.readFile(fullPath, 'utf-8');
+          files.push({
+            path: relPath,
+            content,
+          });
+        } catch {
+          // Skip files we can't read
+        }
+      }
+    }
+  }
+
+  await walkDir(rootPath);
+  return files;
+}
+
+/**
+ * Read ALL indexable files from a directory (no limit)
+ * Returns files in batches via async generator for memory efficiency
+ */
+export async function* readAllFilesInBatches(
+  rootPath: string,
+  options: {
+    batchSize?: number;
+    maxFileSize?: number;
+  } = {}
+): AsyncGenerator<FileToIngest[], void, unknown> {
+  const batchSize = options.batchSize ?? 50;
+  const maxFileSize = options.maxFileSize ?? MAX_FILE_SIZE;
+  let batch: FileToIngest[] = [];
+
+  async function* walkDir(dir: string, relativePath: string = ''): AsyncGenerator<FileToIngest, void, unknown> {
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.join(relativePath, entry.name);
+
+      if (entry.isDirectory()) {
+        if (IGNORE_DIRS.has(entry.name)) continue;
+        yield* walkDir(fullPath, relPath);
+      } else if (entry.isFile()) {
+        if (IGNORE_FILES.has(entry.name)) continue;
+
+        const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+        if (!CODE_EXTENSIONS.has(ext)) continue;
+
+        try {
+          const stat = await fs.promises.stat(fullPath);
+          if (stat.size > maxFileSize) continue;
+
+          const content = await fs.promises.readFile(fullPath, 'utf-8');
+          yield { path: relPath, content };
+        } catch {
+          // Skip unreadable files
+        }
+      }
+    }
+  }
+
+  for await (const file of walkDir(rootPath)) {
+    batch.push(file);
+    if (batch.length >= batchSize) {
+      yield batch;
+      batch = [];
+    }
+  }
+
+  if (batch.length > 0) {
+    yield batch;
+  }
+}
+
+/**
+ * Get language from file extension
+ */
+export function detectLanguage(filePath: string): string {
+  const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
+  const langMap: Record<string, string> = {
+    rs: 'rust',
+    ts: 'typescript',
+    tsx: 'typescript',
+    js: 'javascript',
+    jsx: 'javascript',
+    py: 'python',
+    go: 'go',
+    java: 'java',
+    kt: 'kotlin',
+    c: 'c',
+    h: 'c',
+    cpp: 'cpp',
+    hpp: 'cpp',
+    cs: 'csharp',
+    rb: 'ruby',
+    php: 'php',
+    swift: 'swift',
+    scala: 'scala',
+    sql: 'sql',
+    md: 'markdown',
+    json: 'json',
+    yaml: 'yaml',
+    yml: 'yaml',
+    toml: 'toml',
+    html: 'html',
+    css: 'css',
+    sh: 'shell',
+  };
+  return langMap[ext] ?? 'unknown';
+}

package/src/http.ts

@@ -0,0 +1,154 @@
+import type { Config } from './config.js';
+
+export class HttpError extends Error {
+  status: number;
+  body: any;
+  code: string;
+
+  constructor(status: number, message: string, body?: any) {
+    super(message);
+    this.name = 'HttpError';
+    this.status = status;
+    this.body = body;
+    this.code = statusToCode(status);
+  }
+
+  toJSON() {
+    return {
+      error: this.message,
+      status: this.status,
+      code: this.code,
+      details: this.body,
+    };
+  }
+}
+
+function statusToCode(status: number): string {
+  switch (status) {
+    case 0: return 'NETWORK_ERROR';
+    case 400: return 'BAD_REQUEST';
+    case 401: return 'UNAUTHORIZED';
+    case 403: return 'FORBIDDEN';
+    case 404: return 'NOT_FOUND';
+    case 409: return 'CONFLICT';
+    case 422: return 'VALIDATION_ERROR';
+    case 429: return 'RATE_LIMITED';
+    case 500: return 'INTERNAL_ERROR';
+    case 502: return 'BAD_GATEWAY';
+    case 503: return 'SERVICE_UNAVAILABLE';
+    case 504: return 'GATEWAY_TIMEOUT';
+    default: return 'UNKNOWN_ERROR';
+  }
+}
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: any;
+  signal?: AbortSignal;
+  retries?: number;
+  retryDelay?: number;
+}
+
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const MAX_RETRIES = 3;
+const BASE_DELAY = 1000;
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function request<T>(
+  config: Config,
+  path: string,
+  options: RequestOptions = {}
+): Promise<T> {
+  const { apiUrl, apiKey, jwt, userAgent } = config;
+  // Ensure path has /api/v1 prefix
+  const apiPath = path.startsWith('/api/') ? path : `/api/v1${path}`;
+  const url = `${apiUrl.replace(/\/$/, '')}${apiPath}`;
+  const maxRetries = options.retries ?? MAX_RETRIES;
+  const baseDelay = options.retryDelay ?? BASE_DELAY;
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'User-Agent': userAgent,
+  };
+  if (apiKey) headers['X-API-Key'] = apiKey;
+  if (jwt) headers['Authorization'] = `Bearer ${jwt}`;
+
+  const fetchOptions: RequestInit = {
+    method: options.method || (options.body ? 'POST' : 'GET'),
+    headers,
+  };
+
+  if (options.body !== undefined) {
+    fetchOptions.body = JSON.stringify(options.body);
+  }
+
+  let lastError: HttpError | null = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 180_000);
+
+    // Combine user signal with timeout
+    if (options.signal) {
+      options.signal.addEventListener('abort', () => controller.abort());
+    }
+    fetchOptions.signal = controller.signal;
+
+    let response: Response;
+    try {
+      response = await fetch(url, fetchOptions);
+    } catch (error: any) {
+      clearTimeout(timeout);
+      
+      // Handle abort
+      if (error.name === 'AbortError') {
+        if (options.signal?.aborted) {
+          throw new HttpError(0, 'Request cancelled by user');
+        }
+        throw new HttpError(0, 'Request timeout after 180 seconds');
+      }
+      
+      lastError = new HttpError(0, error?.message || 'Network error');
+      
+      // Retry on network errors
+      if (attempt < maxRetries) {
+        const delay = baseDelay * Math.pow(2, attempt);
+        await sleep(delay);
+        continue;
+      }
+      throw lastError;
+    }
+
+    clearTimeout(timeout);
+
+    let payload: any = null;
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+      payload = await response.json().catch(() => null);
+    } else {
+      payload = await response.text().catch(() => null);
+    }
+
+    if (!response.ok) {
+      const message = payload?.message || payload?.error || response.statusText;
+      lastError = new HttpError(response.status, message, payload);
+      
+      // Retry on retryable status codes
+      if (RETRYABLE_STATUSES.has(response.status) && attempt < maxRetries) {
+        const retryAfter = response.headers.get('retry-after');
+        const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : baseDelay * Math.pow(2, attempt);
+        await sleep(delay);
+        continue;
+      }
+      
+      throw lastError;
+    }
+
+    return payload as T;
+  }
+
+  throw lastError || new HttpError(0, 'Request failed after retries');
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { ContextStreamClient } from './client.js';
+import { registerTools } from './tools.js';
+import { registerResources } from './resources.js';
+import { registerPrompts } from './prompts.js';
+
+async function main() {
+  const config = loadConfig();
+  const client = new ContextStreamClient(config);
+
+  const server = new McpServer({
+    name: 'contextstream-mcp',
+    version: '0.2.0',
+  });
+
+  // Register all MCP components
+  registerTools(server, client);
+  registerResources(server, client, config.apiUrl);
+  registerPrompts(server);
+
+  // Log startup info (to stderr to not interfere with stdio protocol)
+  console.error(`ContextStream MCP server starting...`);
+  console.error(`API URL: ${config.apiUrl}`);
+  console.error(`Auth: ${config.apiKey ? 'API Key' : config.jwt ? 'JWT' : 'None'}`);
+
+  // Start stdio transport (works with Claude Code, Cursor, VS Code MCP config, Inspector)
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('ContextStream MCP server connected and ready');
+}
+
+main().catch((err) => {
+  console.error('ContextStream MCP server failed to start:', err?.message || err);
+  process.exit(1);
+});