@specforge/mcp 1.1.0

package/dist/config/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * MCP Configuration Module
+ *
+ * Loads and validates configuration from environment variables for
+ * the SpecForge MCP server.
+ */
+/**
+ * MCP Server configuration
+ */
+export interface McpConfig {
+    /** API key for authentication (format: sf_live_*) */
+    apiKey: string;
+    /** API Gateway URL for the SpecForge backend */
+    apiUrl: string;
+    /** Enable debug logging */
+    debug: boolean;
+}
+/**
+ * Environment variable names
+ */
+export declare const ENV_VARS: {
+    readonly API_KEY: "SPECFORGE_API_KEY";
+    readonly API_URL: "SPECFORGE_API_URL";
+    readonly DEBUG: "SPECFORGE_DEBUG";
+};
+/**
+ * Load configuration from environment variables
+ *
+ * @throws {Error} If required environment variables are missing
+ * @returns {McpConfig} Loaded configuration
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * console.log(config.apiUrl);
+ * ```
+ */
+export declare function loadConfig(): McpConfig;
+/**
+ * Validate configuration values
+ *
+ * @param config - Configuration to validate
+ * @throws {Error} If configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * validateConfig(config); // Throws if invalid
+ * ```
+ */
+export declare function validateConfig(config: McpConfig): void;
+/**
+ * Load and validate configuration in one step
+ *
+ * @throws {Error} If configuration is missing or invalid
+ * @returns {McpConfig} Validated configuration
+ *
+ * @example
+ * ```typescript
+ * const config = getConfig();
+ * // Configuration is guaranteed to be valid
+ * ```
+ */
+export declare function getConfig(): McpConfig;
+/**
+ * Check if configuration is available without throwing
+ *
+ * @returns {boolean} True if all required environment variables are set
+ */
+export declare function isConfigured(): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;CAIX,CAAC;AAYX;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,SAAS,CAqBtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuCtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAIrC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/dist/config/index.js

@@ -0,0 +1,120 @@
+/**
+ * MCP Configuration Module
+ *
+ * Loads and validates configuration from environment variables for
+ * the SpecForge MCP server.
+ */
+/**
+ * Environment variable names
+ */
+export const ENV_VARS = {
+    API_KEY: 'SPECFORGE_API_KEY',
+    API_URL: 'SPECFORGE_API_URL', // Optional - for self-hosted deployments
+    DEBUG: 'SPECFORGE_DEBUG',
+};
+/**
+ * Default API URL for SpecForge production
+ */
+const DEFAULT_API_URL = 'https://mcp.specforge.com.br';
+/**
+ * API key prefix for validation
+ */
+const API_KEY_PREFIX = 'sf_live_';
+/**
+ * Load configuration from environment variables
+ *
+ * @throws {Error} If required environment variables are missing
+ * @returns {McpConfig} Loaded configuration
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * console.log(config.apiUrl);
+ * ```
+ */
+export function loadConfig() {
+    const apiKey = process.env[ENV_VARS.API_KEY];
+    const apiUrl = process.env[ENV_VARS.API_URL] || DEFAULT_API_URL;
+    const debug = process.env[ENV_VARS.DEBUG] === 'true';
+    if (!apiKey) {
+        throw new Error(`${ENV_VARS.API_KEY} environment variable is required.\n` +
+            'Get your API key from the SpecForge webapp:\n' +
+            '  1. Go to Settings > API Keys\n' +
+            '  2. Create a new API key\n' +
+            '  3. Copy the key (starts with sf_live_)\n' +
+            `  4. Set: export ${ENV_VARS.API_KEY}="your_key"`);
+    }
+    return {
+        apiKey,
+        apiUrl,
+        debug,
+    };
+}
+/**
+ * Validate configuration values
+ *
+ * @param config - Configuration to validate
+ * @throws {Error} If configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * validateConfig(config); // Throws if invalid
+ * ```
+ */
+export function validateConfig(config) {
+    // Validate API key format
+    if (!config.apiKey.startsWith(API_KEY_PREFIX)) {
+        throw new Error(`Invalid API key format.\n` +
+            `  Expected: Key starting with "${API_KEY_PREFIX}"\n` +
+            `  Got: "${config.apiKey.substring(0, 10)}..."\n` +
+            '\nMake sure you copied the full API key from the SpecForge webapp.');
+    }
+    // Validate API key minimum length (prefix + at least 20 chars)
+    if (config.apiKey.length < API_KEY_PREFIX.length + 20) {
+        throw new Error(`Invalid API key length.\n` +
+            '  API keys should be at least 28 characters long.\n' +
+            '  Make sure you copied the full key.');
+    }
+    // Validate API URL format
+    try {
+        const url = new URL(config.apiUrl);
+        // Must be HTTPS in production
+        if (url.protocol !== 'https:' && !config.debug) {
+            console.warn(`Warning: API URL is not using HTTPS: ${config.apiUrl}\n` +
+                '  This is allowed in debug mode but not recommended for production.');
+        }
+    }
+    catch {
+        throw new Error(`Invalid API URL format.\n` +
+            `  Expected: Valid URL (e.g., https://api.example.com/prod)\n` +
+            `  Got: "${config.apiUrl}"\n` +
+            '\nMake sure you copied the full URL including the protocol.');
+    }
+}
+/**
+ * Load and validate configuration in one step
+ *
+ * @throws {Error} If configuration is missing or invalid
+ * @returns {McpConfig} Validated configuration
+ *
+ * @example
+ * ```typescript
+ * const config = getConfig();
+ * // Configuration is guaranteed to be valid
+ * ```
+ */
+export function getConfig() {
+    const config = loadConfig();
+    validateConfig(config);
+    return config;
+}
+/**
+ * Check if configuration is available without throwing
+ *
+ * @returns {boolean} True if all required environment variables are set
+ */
+export function isConfigured() {
+    return !!process.env[ENV_VARS.API_KEY];
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,mBAAmB;IAC5B,OAAO,EAAE,mBAAmB,EAAE,yCAAyC;IACvE,KAAK,EAAE,iBAAiB;CAChB,CAAC;AAEX;;GAEG;AACH,MAAM,eAAe,GAAG,8BAA8B,CAAC;AAEvD;;GAEG;AACH,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,eAAe,CAAC;IAChE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC;IAErD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,GAAG,QAAQ,CAAC,OAAO,sCAAsC;YACvD,+CAA+C;YAC/C,kCAAkC;YAClC,6BAA6B;YAC7B,4CAA4C;YAC5C,oBAAoB,QAAQ,CAAC,OAAO,aAAa,CACpD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM;QACN,MAAM;QACN,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,MAAiB;IAC9C,0BAA0B;IAC1B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,2BAA2B;YACzB,kCAAkC,cAAc,KAAK;YACrD,WAAW,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ;YACjD,oEAAoE,CACvE,CAAC;IACJ,CAAC;IAED,+DAA+D;IAC/D,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,2BAA2B;YACzB,qDAAqD;YACrD,sCAAsC,CACzC,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEnC,8BAA8B;QAC9B,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC/C,OAAO,CAAC,IAAI,CACV,wCAAwC,MAAM,CAAC,MAAM,IAAI;gBACvD,qEAAqE,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,2BAA2B;YACzB,8DAA8D;YAC9D,WAAW,MAAM,CAAC,MAAM,KAAK;YAC7B,6DAA6D,CAChE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,cAAc,CAAC,MAAM,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SpecForge MCP Server
+ *
+ * This is the main entry point for the SpecForge MCP (Model Context Protocol) server.
+ * It provides tools for AI agents to interact with SpecForge projects, specifications,
+ * epics, and tickets.
+ *
+ * @module @specforge/mcp
+ */
+export { McpConfig, loadConfig, validateConfig, getConfig, isConfigured, ENV_VARS } from './config/index.js';
+export { ApiClient, ApiResponse, ApiKeyValidationResult, ApiRequestOptions } from './client/api-client.js';
+export { createServer, startServer } from './server.js';
+export { getTools, handleToolCall, handleToolCallSafe, Tool } from './tools/index.js';
+export { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, MCPErrorResponse, } from './validation/index.js';
+export * from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7G,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3G,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGtF,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,60 @@
+/**
+ * SpecForge MCP Server
+ *
+ * This is the main entry point for the SpecForge MCP (Model Context Protocol) server.
+ * It provides tools for AI agents to interact with SpecForge projects, specifications,
+ * epics, and tickets.
+ *
+ * @module @specforge/mcp
+ */
+// Export configuration
+export { loadConfig, validateConfig, getConfig, isConfigured, ENV_VARS } from './config/index.js';
+// Export API client
+export { ApiClient } from './client/api-client.js';
+// Export server
+export { createServer, startServer } from './server.js';
+// Export tools
+export { getTools, handleToolCall, handleToolCallSafe } from './tools/index.js';
+// Export validation
+export { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, } from './validation/index.js';
+// Export types
+export * from './types/index.js';
+// Main entry point
+async function main() {
+    // Import dynamically to avoid circular dependency issues
+    const { loadConfig, validateConfig } = await import('./config/index.js');
+    const { createServer, startServer } = await import('./server.js');
+    try {
+        const config = loadConfig();
+        validateConfig(config);
+        if (config.debug) {
+            console.error('[DEBUG] Configuration loaded:', {
+                apiUrl: config.apiUrl,
+                apiKey: config.apiKey.substring(0, 15) + '...',
+                debug: config.debug,
+            });
+        }
+        console.error('[INFO] Starting SpecForge MCP server...');
+        const server = await createServer(config);
+        await startServer(server);
+        if (config.debug) {
+            console.error('[DEBUG] MCP server started and connected');
+        }
+    }
+    catch (error) {
+        console.error('[ERROR] Failed to start MCP server:', error);
+        process.exit(1);
+    }
+}
+// Run if executed directly (not when imported as a library)
+// In ESM, we check if this is the entry point by comparing with process.argv
+const isDirectRun = process.argv[1]?.endsWith('index.js') ||
+    process.argv[1]?.endsWith('index.ts') ||
+    process.argv[1]?.includes('@specforge/mcp');
+if (isDirectRun && !process.env.VITEST) {
+    main().catch((error) => {
+        console.error('[ERROR] Unhandled error:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uBAAuB;AACvB,OAAO,EAAa,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7G,oBAAoB;AACpB,OAAO,EAAE,SAAS,EAA0D,MAAM,wBAAwB,CAAC;AAE3G,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAExD,eAAe;AACf,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,kBAAkB,EAAQ,MAAM,kBAAkB,CAAC;AAEtF,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAE/B,eAAe;AACf,cAAc,kBAAkB,CAAC;AAEjC,mBAAmB;AACnB,KAAK,UAAU,IAAI;IACjB,yDAAyD;IACzD,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACzE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAElE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,cAAc,CAAC,MAAM,CAAC,CAAC;QAEvB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE;gBAC7C,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK;gBAC9C,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAEzD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;QAE1B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,6EAA6E;AAC7E,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAEhE,IAAI,WAAW,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;IACvC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SpecForge MCP Server
+ *
+ * MCP (Model Context Protocol) server implementation using stdio transport.
+ * Provides tools for AI agents to interact with SpecForge projects.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpConfig } from './config/index.js';
+/**
+ * Create and configure the MCP server
+ *
+ * @param config - Configuration for the server
+ * @returns Configured MCP Server instance
+ */
+export declare function createServer(config: McpConfig): Promise<Server>;
+/**
+ * Start the MCP server with stdio transport
+ *
+ * @param server - The MCP server instance
+ */
+export declare function startServer(server: Server): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAOnE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAQ9C;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAkErE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B/D"}

package/dist/server.js

@@ -0,0 +1,100 @@
+/**
+ * SpecForge MCP Server
+ *
+ * MCP (Model Context Protocol) server implementation using stdio transport.
+ * Provides tools for AI agents to interact with SpecForge projects.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { ApiClient } from './client/api-client.js';
+import { getTools, handleToolCall } from './tools/index.js';
+/**
+ * Package version - should match package.json
+ */
+const VERSION = '1.0.0';
+/**
+ * Create and configure the MCP server
+ *
+ * @param config - Configuration for the server
+ * @returns Configured MCP Server instance
+ */
+export async function createServer(config) {
+    const apiClient = new ApiClient(config);
+    const server = new Server({
+        name: 'specforge-mcp',
+        version: VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Handle ListTools requests - return available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        if (config.debug) {
+            console.error('[DEBUG] ListTools request received');
+        }
+        const tools = getTools();
+        if (config.debug) {
+            console.error(`[DEBUG] Returning ${tools.length} tools`);
+        }
+        return { tools };
+    });
+    // Handle CallTool requests - execute the requested tool
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (config.debug) {
+            console.error('[DEBUG] CallTool request:', {
+                name,
+                args: JSON.stringify(args),
+            });
+        }
+        try {
+            const result = await handleToolCall(apiClient, name, args || {}, config.debug);
+            // Format result as text content
+            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            return {
+                content: [{ type: 'text', text }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (config.debug) {
+                console.error(`[DEBUG] Tool ${name} failed:`, message);
+            }
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+/**
+ * Start the MCP server with stdio transport
+ *
+ * @param server - The MCP server instance
+ */
+export async function startServer(server) {
+    const transport = new StdioServerTransport();
+    // Handle graceful shutdown
+    const shutdown = async () => {
+        console.error('[INFO] Shutting down MCP server...');
+        await server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Handle uncaught errors
+    process.on('uncaughtException', (error) => {
+        console.error('[ERROR] Uncaught exception:', error);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        console.error('[ERROR] Unhandled rejection:', reason);
+        process.exit(1);
+    });
+    // Connect to transport
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * MCP Tools Registry
+ *
+ * This module defines and exports all available MCP tools.
+ * All operations from Epics 3-10 are registered here with proper JSON Schema definitions.
+ *
+ * Tool categories:
+ * - Core Operations: Project, Specification, Epic, Ticket, Dependency
+ * - Context & AI: Implementation context, actionable tickets, critical path
+ * - Workflow: Work sessions, progress reporting
+ * - Testing: Test results, validation
+ * - Discovery: Report and resolve discoveries
+ * - Status: Status reports, summaries, analytics
+ * - Search: Search, find by file/tag, find related
+ * - Git: Link commits and PRs, get linked items
+ */
+import { ApiClient } from '../client/api-client.js';
+import { MCPErrorResponse } from '../validation/index.js';
+/**
+ * Tool definition matching MCP protocol schema
+ */
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Get list of all available tools
+ *
+ * This returns the tool definitions that will be sent to the AI client
+ * in response to ListTools requests.
+ *
+ * @returns Array of tool definitions
+ */
+export declare function getTools(): Tool[];
+/**
+ * Tool handler type - processes arguments and returns a result
+ */
+type ToolHandler = (apiClient: ApiClient, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Create tool handlers that call the API with proper request formatting
+ *
+ * Each handler:
+ * - Validates required arguments
+ * - Formats the request for the API
+ * - Parses and transforms the response
+ * - Handles errors appropriately
+ *
+ * @param apiClient - The API client to use for making requests
+ * @returns Record of tool handlers keyed by tool name
+ */
+export declare function createToolHandlers(apiClient: ApiClient): Record<string, ToolHandler>;
+/**
+ * Handle a tool call by routing to the appropriate handler
+ *
+ * @param apiClient - The API client to use for making requests
+ * @param toolName - Name of the tool being called
+ * @param args - Arguments passed to the tool
+ * @param debug - Whether to enable debug logging
+ * @returns Promise resolving to the tool result
+ */
+export declare function handleToolCall(apiClient: ApiClient, toolName: string, args: Record<string, unknown>, debug?: boolean): Promise<unknown>;
+/**
+ * Handle a tool call and return MCP-formatted response
+ * This wraps handleToolCall with proper error formatting for MCP protocol
+ *
+ * @param apiClient - The API client to use for making requests
+ * @param toolName - Name of the tool being called
+ * @param args - Arguments passed to the tool
+ * @param debug - Whether to enable debug logging
+ * @returns Promise resolving to either the result or an MCP error response
+ */
+export declare function handleToolCallSafe(apiClient: ApiClient, toolName: string, args: Record<string, unknown>, debug?: boolean): Promise<unknown | MCPErrorResponse>;
+export { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, type MCPErrorResponse, } from '../validation/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAML,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,IAAI,EAAE,CAuhCjC;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CACjB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AA6EtB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAka7B;AAqCD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CA4DlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAOrC;AAGD,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}