ctxman 3.0.0 → 3.1.0

package/lib/api/mcp/start.js

@@ -0,0 +1,125 @@
+/**
+ * MCP server startup shared by `ctxman mcp` (bin/cm-mcp.js) and bin/mcp-server.js
+ */
+
+import { parseArgs } from 'util';
+import MCPServer from './server.js';
+import { resolveRootDir } from './sandbox.js';
+
+export const DEFAULT_PORT = 3000;
+export const DEFAULT_HOST = '127.0.0.1';
+export const TRANSPORTS = ['stdio', 'sse'];
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1'];
+
+const SERVER_OPTIONS = {
+  transport: { type: 'string' },
+  port: { type: 'string' },
+  host: { type: 'string' },
+  'api-key': { type: 'string' },
+  cors: { type: 'boolean' },
+  root: { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+};
+
+/**
+ * Parse the server options. Both `--port=3000` and `--port 3000` are accepted.
+ *
+ * @param {string[]} argv - Arguments after the command name
+ * @param {Object} [options]
+ * @param {boolean} [options.strict=true] - Reject unknown options, positionals and invalid
+ *   values. bin/mcp-server.js passes false to keep its old tolerance: unknown options are
+ *   ignored and an unknown transport means stdio.
+ * @returns {{transport: string, port: number, host: string, apiKey?: string, cors: boolean,
+ *   root?: string, help: boolean}}
+ * @throws {Error} In strict mode, on unknown options or invalid values
+ */
+export function parseServerArgs(argv, { strict = true } = {}) {
+  const { values } = parseArgs({
+    args: argv,
+    options: SERVER_OPTIONS,
+    strict,
+    allowPositionals: !strict,
+  });
+  // Lenient parsing turns a string option without a value into `true`
+  const text = (value) => (typeof value === 'string' ? value : undefined);
+
+  let transport = text(values.transport) ?? 'stdio';
+  if (!TRANSPORTS.includes(transport)) {
+    if (strict) {
+      throw new Error(`Unknown transport "${transport}" (expected ${TRANSPORTS.join(' or ')})`);
+    }
+    transport = 'stdio';
+  }
+
+  const portText = text(values.port);
+  let port = DEFAULT_PORT;
+  // Like before, bin/mcp-server.js treats an empty `--port=` as the default
+  if (portText !== undefined && (strict || portText)) {
+    port = strict ? Number(portText) : parseInt(portText, 10);
+    // Lenient mode only cares about the port when it is going to listen on it
+    if (
+      !(Number.isInteger(port) && port >= 0 && port <= 65535) &&
+      (strict || transport === 'sse')
+    ) {
+      throw new Error(`Invalid port "${portText}"`);
+    }
+  }
+
+  return {
+    transport,
+    port,
+    host: text(values.host) ?? DEFAULT_HOST,
+    apiKey: text(values['api-key']),
+    cors: values.cors === true,
+    root: text(values.root),
+    help: values.help === true,
+  };
+}
+
+/**
+ * Start the MCP server.
+ *
+ * With the stdio transport stdout is the JSON-RPC channel, so console.log/info/debug (logger
+ * lines, ignore-rule notices) are redirected to stderr for the rest of the process.
+ *
+ * @param {ReturnType<typeof parseServerArgs>} options
+ * @param {Object} [context]
+ * @param {Object} [context.env=process.env] - Read for CTXMAN_MCP_ROOT when --root is absent
+ * @returns {Promise<{server: MCPServer, root: string|null, transport?: Object}>}
+ */
+export async function startMcpServer(options, { env = process.env } = {}) {
+  const rootOption = options.root ?? (env.CTXMAN_MCP_ROOT || undefined);
+  const root = rootOption ? resolveRootDir(rootOption) : null;
+
+  if (options.transport !== 'sse') {
+    console.log = console.info = console.debug = console.error;
+  }
+
+  const server = new MCPServer({ root });
+  if (root) {
+    console.error(`Ctxman MCP Server confined to ${root}`);
+  }
+
+  if (options.transport === 'sse') {
+    const host = options.host ?? DEFAULT_HOST;
+    if (!options.apiKey && !LOOPBACK_HOSTS.includes(host)) {
+      console.error(
+        `Warning: listening on ${host} without --api-key; anyone who can reach it can read the project`
+      );
+    }
+    // Loaded only for this transport: it pulls in express
+    const { HttpSseTransport } = await import('./transports/HttpSseTransport.js');
+    const transport = new HttpSseTransport({
+      port: options.port ?? DEFAULT_PORT,
+      host,
+      cors: options.cors,
+      auth: options.apiKey ? { apiKey: options.apiKey } : undefined,
+    });
+    await transport.start();
+    await server.start(transport.transport);
+    return { server, root, transport };
+  }
+
+  await server.start();
+  return { server, root };
+}

package/lib/api/mcp/transports/HttpSseTransport.js

@@ -1,63 +1,71 @@
-import express from "express";
-import cors from "cors";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { randomUUID } from "crypto";
+import cors from 'cors';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { randomUUID } from 'crypto';
 
 export class HttpSseTransport {
-    constructor(options = {}) {
-        this.port = options.port || 3000;
-        this.endpoint = options.endpoint || "/mcp";
-        this.app = express();
-
-        this.app.use(cors());
-        this.app.use(express.json());
-
-        // Authentication Middleware
-        if (options.auth && options.auth.apiKey) {
-            this.app.use((req, res, next) => {
-                const apiKey = req.headers["x-api-key"] || req.query.apiKey;
-                if (!apiKey || apiKey !== options.auth.apiKey) {
-                    return res.status(401).json({ error: "Unauthorized" });
-                }
-                next();
-            });
-        }
+  constructor(options = {}) {
+    this.port = options.port || 3000;
+    this.host = options.host || '127.0.0.1';
+    this.endpoint = options.endpoint || '/mcp';
 
-        // Initialize StreamableHTTPServerTransport
-        this.transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            enableJsonResponse: false, // Prefer SSE
-            ...options.transportOptions
-        });
+    // JSON body parser plus, on a loopback host, Host header validation against DNS rebinding
+    this.app = createMcpExpressApp({ host: this.host });
 
-        this.setupRoutes();
+    // Off by default: with `Access-Control-Allow-Origin: *` any web page the user opens
+    // could call the tools and read the project
+    if (options.cors) {
+      this.app.use(cors({ exposedHeaders: ['Mcp-Session-Id'] }));
     }
 
-    setupRoutes() {
-        // Handle all requests to the endpoint via the transport
-        this.app.all(this.endpoint, async (req, res) => {
-            await this.transport.handleRequest(req, res);
-        });
-
-        // Support for separate messages endpoint if needed, but StreamableHTTPServerTransport handles it
-        this.app.post(`${this.endpoint}/messages`, async (req, res) => {
-            await this.transport.handleRequest(req, res);
-        });
+    // Authentication Middleware
+    if (options.auth && options.auth.apiKey) {
+      this.app.use((req, res, next) => {
+        const apiKey = req.headers['x-api-key'] || req.query.apiKey;
+        if (!apiKey || apiKey !== options.auth.apiKey) {
+          return res.status(401).json({ error: 'Unauthorized' });
+        }
+        next();
+      });
     }
 
-    async start() {
-        return new Promise((resolve) => {
-            this.server = this.app.listen(this.port, () => {
-                console.error(`MCP HTTP/SSE Server running on port ${this.port} at ${this.endpoint}`);
-                resolve(this.transport);
-            });
-        });
-    }
+    // Initialize StreamableHTTPServerTransport
+    this.transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      enableJsonResponse: false, // Prefer SSE
+      ...options.transportOptions,
+    });
 
-    async close() {
-        if (this.server) {
-            this.server.close();
-        }
-        await this.transport.close();
+    this.setupRoutes();
+  }
+
+  setupRoutes() {
+    // express.json() has already consumed the request stream, so hand over the parsed body
+    this.app.all(this.endpoint, async (req, res) => {
+      await this.transport.handleRequest(req, res, req.body);
+    });
+
+    // Support for separate messages endpoint if needed, but StreamableHTTPServerTransport handles it
+    this.app.post(`${this.endpoint}/messages`, async (req, res) => {
+      await this.transport.handleRequest(req, res, req.body);
+    });
+  }
+
+  async start() {
+    return new Promise((resolve) => {
+      this.server = this.app.listen(this.port, this.host, () => {
+        console.error(
+          `MCP HTTP/SSE Server running at http://${this.host}:${this.port}${this.endpoint}`
+        );
+        resolve(this.transport);
+      });
+    });
+  }
+
+  async close() {
+    if (this.server) {
+      this.server.close();
     }
+    await this.transport.close();
+  }
 }

package/lib/api/rest/server.js

@@ -9,26 +9,32 @@
  * - Authentication (optional)
  */
 
+import fs from 'fs';
 import http from 'http';
+import path from 'path';
 import { URL } from 'url';
 import { getLogger } from '../../utils/logger.js';
 import Scanner from '../../core/Scanner.js';
 import Analyzer from '../../core/Analyzer.js';
 import ContextBuilder from '../../core/ContextBuilder.js';
-import Reporter from '../../core/Reporter.js';
-import GitClient from '../../integrations/git/GitClient.js';
 import DiffAnalyzer from '../../integrations/git/DiffAnalyzer.js';
+import { isValidGitRef } from '../../integrations/git/GitClient.js';
+import { loadPolicy } from '../../policy/policy.js';
+import { guardExport, PolicyViolationError } from '../../policy/enforce.js';
 
 const logger = getLogger('APIServer');
 
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+
 export class APIServer {
   constructor(options = {}) {
     this.options = {
       port: 3000,
       host: 'localhost',
       authToken: null,
-      cors: true,
-      ...options
+      // Off by default: with CORS on, any web page the user opens can read the responses
+      cors: false,
+      ...options,
     };
 
     this.server = null;
@@ -88,6 +94,12 @@ export class APIServer {
    * @param {http.ServerResponse} res
    */
   async handleRequest(req, res) {
+    // DNS-rebinding guard: a server bound to loopback only answers to loopback host names
+    if (LOOPBACK_HOSTS.has(this.options.host) && !this.isLoopbackHostHeader(req.headers.host)) {
+      this.sendError(res, 403, 'Forbidden host');
+      return;
+    }
+
     // CORS headers
     if (this.options.cors) {
       res.setHeader('Access-Control-Allow-Origin', '*');
@@ -122,7 +134,7 @@ export class APIServer {
       }
     } catch (error) {
       logger.error(`Request error: ${error.message}`);
-      this.sendError(res, 500, error.message);
+      this.sendError(res, error.statusCode || 500, error.message);
     }
   }
 
@@ -201,21 +213,31 @@ export class APIServer {
       return;
     }
 
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+      this.sendError(res, 404, `File not found: ${filePath}`);
+      return;
+    }
+
     // Analyze single file
     const analyzer = new Analyzer({ methodLevel: true });
     const fileInfo = {
       path: filePath,
       relativePath: filePath,
       name: path.basename(filePath),
-      extension: path.extname(filePath)
+      extension: path.extname(filePath),
     };
 
     const analysis = await analyzer.analyzeFile(fileInfo);
+    // analyzeFile() returns null for binary and other non-source files
+    if (!analysis) {
+      this.sendError(res, 400, `Not a text source file: ${filePath}`);
+      return;
+    }
 
     this.sendJSON(res, {
       file: filePath,
       methods: analysis.methods || [],
-      totalMethods: analysis.methodCount || 0
+      totalMethods: analysis.methodCount || 0,
     });
   }
 
@@ -243,6 +265,11 @@ export class APIServer {
     const projectPath = params.path || process.cwd();
     const since = params.since || null;
 
+    if (since && !isValidGitRef(since)) {
+      this.sendError(res, 400, 'Invalid "since" parameter: expected a branch, tag or commit');
+      return;
+    }
+
     const diffAnalyzer = new DiffAnalyzer(projectPath);
     const analysis = diffAnalyzer.analyzeChanges(since);
 
@@ -260,11 +287,15 @@ export class APIServer {
       methodLevel: body.methodLevel || false,
       targetModel: body.targetModel || null,
       targetTokens: body.targetTokens || null,
-      useCase: body.useCase || 'custom'
+      useCase: body.useCase || 'custom',
     };
 
+    // Export policy of the project: denied files are dropped by the scanner, the rest of the
+    // rules are checked before the context is sent
+    const policy = loadPolicy(projectPath);
+
     // Build context
-    const scanner = new Scanner(projectPath);
+    const scanner = new Scanner(projectPath, { policy });
     const files = scanner.scan();
 
     const analyzer = new Analyzer(options);
@@ -273,6 +304,32 @@ export class APIServer {
     const builder = new ContextBuilder(options);
     const context = builder.build(result);
 
+    if (policy.active) {
+      context.metadata.removedByPolicy = scanner.getStats().filesDenied;
+      const exported = Object.values(context.files || {}).flat();
+      try {
+        guardExport(policy, {
+          command: 'rest POST /api/v1/context',
+          root: projectPath,
+          destination: 'rest',
+          format: 'json',
+          targetModel: options.targetModel,
+          files: exported,
+          removedByPolicy: context.metadata.removedByPolicy,
+          // Same serialization as sendJSON(), so the hash matches the response body
+          text: JSON.stringify(context, null, 2),
+        });
+      } catch (error) {
+        if (!(error instanceof PolicyViolationError)) throw error;
+        this.sendJSON(
+          res,
+          { error: error.message, statusCode: 403, violations: error.violations },
+          403
+        );
+        return;
+      }
+    }
+
     this.sendJSON(res, context);
   }
 
@@ -289,24 +346,24 @@ export class APIServer {
           description: 'Analyze project files and get token counts',
           parameters: {
             path: 'Project path (optional, defaults to cwd)',
-            methods: 'Include method-level analysis (true/false)'
-          }
+            methods: 'Include method-level analysis (true/false)',
+          },
         },
         {
           path: '/api/v1/methods',
           method: 'GET',
           description: 'Extract methods from a file',
           parameters: {
-            file: 'File path (required)'
-          }
+            file: 'File path (required)',
+          },
         },
         {
           path: '/api/v1/stats',
           method: 'GET',
           description: 'Get project statistics',
           parameters: {
-            path: 'Project path (optional)'
-          }
+            path: 'Project path (optional)',
+          },
         },
         {
           path: '/api/v1/diff',
@@ -314,8 +371,8 @@ export class APIServer {
           description: 'Analyze git diff',
           parameters: {
             path: 'Project path (optional)',
-            since: 'Git reference (optional, e.g., "main", "HEAD~5")'
-          }
+            since: 'Git reference (optional, e.g., "main", "HEAD~5")',
+          },
         },
         {
           path: '/api/v1/context',
@@ -326,10 +383,10 @@ export class APIServer {
             methodLevel: 'Include methods (boolean)',
             targetModel: 'Target LLM model',
             targetTokens: 'Target token budget',
-            useCase: 'Use case template'
-          }
-        }
-      ]
+            useCase: 'Use case template',
+          },
+        },
+      ],
     };
 
     this.sendJSON(res, docs);
@@ -340,6 +397,21 @@ export class APIServer {
    * @param {http.IncomingMessage} req
    * @returns {boolean}
    */
+  /**
+   * Whether a Host header names this machine's loopback interface
+   * @param {string} hostHeader - e.g. "localhost:3000" or "[::1]:3000"
+   * @returns {boolean}
+   */
+  isLoopbackHostHeader(hostHeader) {
+    if (!hostHeader) return false;
+    try {
+      const { hostname } = new URL(`http://${hostHeader}`);
+      return LOOPBACK_HOSTS.has(hostname.replace(/^\[|\]$/g, ''));
+    } catch (_error) {
+      return false;
+    }
+  }
+
   checkAuth(req) {
     const authHeader = req.headers.authorization;
 
@@ -360,7 +432,7 @@ export class APIServer {
     return new Promise((resolve, reject) => {
       let body = '';
 
-      req.on('data', chunk => {
+      req.on('data', (chunk) => {
         body += chunk.toString();
       });
 
@@ -368,8 +440,9 @@ export class APIServer {
         try {
           const parsed = JSON.parse(body);
           resolve(parsed);
-        } catch (error) {
-          reject(new Error('Invalid JSON'));
+        } catch (_error) {
+          // A malformed body is the client's fault, not a server error
+          reject(Object.assign(new Error('Invalid JSON'), { statusCode: 400 }));
         }
       });
 
@@ -395,10 +468,14 @@ export class APIServer {
    * @param {string} message
    */
   sendError(res, statusCode, message) {
-    this.sendJSON(res, {
-      error: message,
-      statusCode: statusCode
-    }, statusCode);
+    this.sendJSON(
+      res,
+      {
+        error: message,
+        statusCode: statusCode,
+      },
+      statusCode
+    );
   }
 }
 

package/lib/cache/CacheManager.js

@@ -24,7 +24,7 @@ export class CacheManager {
       ttl: 3600, // 1 hour in seconds
       path: '.context-cache',
       maxSize: 100 * 1024 * 1024, // 100MB
-      ...options
+      ...options,
     };
 
     this.memoryCache = new Map();
@@ -33,7 +33,7 @@ export class CacheManager {
       misses: 0,
       writes: 0,
       evictions: 0,
-      errors: 0
+      errors: 0,
     };
 
     // Initialize cache directory
@@ -139,8 +139,7 @@ export class CacheManager {
       this.stats.hits++;
       logger.debug(`Cache hit (disk): ${key}`);
       return cached.data;
-
-    } catch (error) {
+    } catch (_error) {
       this.stats.misses++;
       return null;
     }
@@ -161,7 +160,7 @@ export class CacheManager {
     const cacheEntry = {
       data: analysis,
       timestamp: Date.now(),
-      modifiedTime: modifiedTime
+      modifiedTime: modifiedTime,
     };
 
     try {
@@ -173,7 +172,6 @@ export class CacheManager {
 
       this.stats.writes++;
       logger.debug(`Cache set: ${key}`);
-
     } catch (error) {
       logger.error(`Cache set error: ${error.message}`);
       this.stats.errors++;
@@ -232,10 +230,7 @@ export class CacheManager {
    * @returns {string}
    */
   getCacheKey(filePath) {
-    return crypto
-      .createHash('md5')
-      .update(filePath)
-      .digest('hex');
+    return crypto.createHash('md5').update(filePath).digest('hex');
   }
 
   /**
@@ -296,17 +291,14 @@ export class CacheManager {
    */
   getStats() {
     const totalRequests = this.stats.hits + this.stats.misses;
-    const hitRate = totalRequests > 0
-      ? (this.stats.hits / totalRequests * 100).toFixed(1)
-      : 0;
+    const hitRate = totalRequests > 0 ? ((this.stats.hits / totalRequests) * 100).toFixed(1) : 0;
 
     return {
       ...this.stats,
       totalRequests,
       hitRate: parseFloat(hitRate),
-      cacheSize: this.options.strategy === 'memory'
-        ? this.memoryCache.size
-        : this.getDiskCacheSize()
+      cacheSize:
+        this.options.strategy === 'memory' ? this.memoryCache.size : this.getDiskCacheSize(),
     };
   }
 
@@ -321,7 +313,7 @@ export class CacheManager {
 
       const files = fs.readdirSync(cachePath);
       return files.length;
-    } catch (error) {
+    } catch (_error) {
       return 0;
     }
   }