gitx.do 0.0.1 → 0.0.3

package/dist/mcp/adapter.d.ts

@@ -1,32 +1,136 @@
 /**
- * MCP (Model Context Protocol) SDK Adapter
+ * @fileoverview MCP (Model Context Protocol) SDK Adapter
  *
  * This module provides an adapter that bridges the MCP protocol to git operations,
  * handling request/response, tool registration/invocation, resource listing,
- * and error handling.
+ * and error handling. It implements the JSON-RPC 2.0 specification for MCP
+ * communication.
+ *
+ * The adapter supports:
+ * - Tool registration and invocation with schema validation
+ * - Resource registration and reading
+ * - Prompt registration and retrieval
+ * - Standard and custom MCP error codes
+ * - Batch request processing
+ * - Capability negotiation
+ *
+ * @module mcp/adapter
+ *
+ * @example
+ * // Create and configure an MCP adapter
+ * import { createMCPAdapter, MCPAdapter } from './adapter'
+ *
+ * const adapter = createMCPAdapter({
+ *   name: 'my-git-server',
+ *   version: '1.0.0',
+ *   capabilities: ['tools', 'resources']
+ * })
+ *
+ * // Register git tools and start
+ * adapter.registerGitTools()
+ * await adapter.start()
+ *
+ * // Handle incoming requests
+ * const response = await adapter.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'tools/list',
+ *   params: {}
+ * })
+ *
+ * @example
+ * // Handle raw JSON requests
+ * const rawResponse = await adapter.handleRawRequest(
+ *   '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+ * )
  */
 import { type MCPToolResult } from './tools';
 /**
- * JSON-RPC 2.0 error codes and MCP-specific error codes
+ * JSON-RPC 2.0 error codes and MCP-specific error codes.
+ *
+ * @description
+ * Enumeration of error codes used in MCP responses. Includes standard
+ * JSON-RPC 2.0 error codes (negative 32xxx range) and MCP-specific
+ * error codes for resource, tool, and prompt operations.
+ *
+ * @enum {number}
+ *
+ * @example
+ * // Using error codes in responses
+ * if (!tool) {
+ *   return {
+ *     jsonrpc: '2.0',
+ *     id: requestId,
+ *     error: {
+ *       code: MCPErrorCode.TOOL_NOT_FOUND,
+ *       message: 'Tool not found'
+ *     }
+ *   }
+ * }
  */
 export declare enum MCPErrorCode {
+    /** Parse error - Invalid JSON was received (-32700) */
     PARSE_ERROR = -32700,
+    /** Invalid Request - The JSON sent is not a valid Request object (-32600) */
     INVALID_REQUEST = -32600,
+    /** Method not found - The method does not exist or is not available (-32601) */
     METHOD_NOT_FOUND = -32601,
+    /** Invalid params - Invalid method parameter(s) (-32602) */
     INVALID_PARAMS = -32602,
+    /** Internal error - Internal JSON-RPC error (-32603) */
     INTERNAL_ERROR = -32603,
+    /** Resource not found - The requested resource does not exist (-32001) */
     RESOURCE_NOT_FOUND = -32001,
+    /** Tool not found - Maps to METHOD_NOT_FOUND as tools are methods (-32601) */
     TOOL_NOT_FOUND = -32601,
+    /** Prompt not found - The requested prompt does not exist (-32003) */
     PROMPT_NOT_FOUND = -32003,
+    /** Capability not supported - The requested capability is not enabled (-32004) */
     CAPABILITY_NOT_SUPPORTED = -32004
 }
 /**
- * Custom error class for MCP errors
+ * Custom error class for MCP errors.
+ *
+ * @description
+ * Error class that encapsulates MCP error information including a numeric
+ * error code, human-readable message, and optional additional data. Can be
+ * serialized to JSON-RPC error format using the toJSON() method.
+ *
+ * @class MCPError
+ * @extends Error
+ *
+ * @example
+ * // Throw an MCP error
+ * throw new MCPError(
+ *   MCPErrorCode.TOOL_NOT_FOUND,
+ *   'Tool "unknown_tool" not found',
+ *   { toolName: 'unknown_tool' }
+ * )
+ *
+ * @example
+ * // Convert to JSON-RPC error format
+ * const error = new MCPError(MCPErrorCode.INVALID_PARAMS, 'Missing required field')
+ * const jsonError = error.toJSON()
+ * // { code: -32602, message: 'Missing required field' }
  */
 export declare class MCPError extends Error {
+    /** The MCP error code */
     code: MCPErrorCode;
+    /** Optional additional error data */
     data?: unknown;
+    /**
+     * Create a new MCP error.
+     *
+     * @param code - The MCP error code
+     * @param message - Human-readable error message
+     * @param data - Optional additional error data
+     */
     constructor(code: MCPErrorCode, message: string, data?: unknown);
+    /**
+     * Convert the error to JSON-RPC error format.
+     *
+     * @returns Object suitable for JSON-RPC error responses
+     */
     toJSON(): {
         code: MCPErrorCode;
         message: string;
@@ -34,79 +138,224 @@ export declare class MCPError extends Error {
     };
 }
 /**
- * MCP capability types
+ * MCP capability types.
+ *
+ * @description
+ * Type representing the different capabilities an MCP server can support.
+ * Capabilities are negotiated during initialization.
+ *
+ * @typedef {'tools' | 'resources' | 'prompts'} MCPCapability
  */
 export type MCPCapability = 'tools' | 'resources' | 'prompts';
 /**
- * Server configuration for MCP adapter
+ * Server configuration for MCP adapter.
+ *
+ * @description
+ * Configuration options for initializing an MCP adapter instance.
+ * All fields are optional with sensible defaults.
+ *
+ * @interface MCPServerConfig
+ *
+ * @example
+ * const config: MCPServerConfig = {
+ *   name: 'my-git-server',
+ *   version: '1.0.0',
+ *   capabilities: ['tools', 'resources']
+ * }
  */
 export interface MCPServerConfig {
+    /** Server name (default: 'gitx.do') */
     name?: string;
+    /** Server version (default: '1.0.0') */
     version?: string;
+    /** Enabled capabilities (default: ['tools']) */
     capabilities?: MCPCapability[];
 }
 /**
- * MCP request structure (JSON-RPC 2.0)
+ * MCP request structure (JSON-RPC 2.0).
+ *
+ * @description
+ * Represents an incoming MCP request following the JSON-RPC 2.0 specification.
+ * Requests without an id are treated as notifications.
+ *
+ * @interface MCPRequest
+ *
+ * @example
+ * const request: MCPRequest = {
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'tools/call',
+ *   params: { name: 'git_status', arguments: {} }
+ * }
  */
 export interface MCPRequest {
+    /** JSON-RPC version (must be '2.0') */
     jsonrpc: '2.0';
+    /** Request identifier (omit for notifications) */
     id?: string | number;
+    /** The method to invoke */
     method: string;
+    /** Method parameters */
     params?: Record<string, unknown>;
 }
 /**
- * MCP response structure (JSON-RPC 2.0)
+ * MCP response structure (JSON-RPC 2.0).
+ *
+ * @description
+ * Represents an outgoing MCP response. Contains either a result or an error,
+ * never both. Responses include the id from the corresponding request.
+ *
+ * @interface MCPResponse
+ *
+ * @example
+ * // Success response
+ * const success: MCPResponse = {
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   result: { tools: [...] }
+ * }
+ *
+ * // Error response
+ * const error: MCPResponse = {
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   error: { code: -32601, message: 'Method not found' }
+ * }
  */
 export interface MCPResponse {
+    /** JSON-RPC version (always '2.0') */
     jsonrpc: '2.0';
+    /** Request identifier from the corresponding request */
     id?: string | number;
+    /** Result data (mutually exclusive with error) */
     result?: unknown;
+    /** Error information (mutually exclusive with result) */
     error?: {
+        /** Numeric error code */
         code: number;
+        /** Human-readable error message */
         message: string;
+        /** Additional error data */
         data?: unknown;
     };
 }
 /**
- * Tool information for registration
+ * Tool information for registration.
+ *
+ * @description
+ * Complete tool definition including metadata, input schema, and handler
+ * function. Used when registering tools with the adapter.
+ *
+ * @interface MCPToolInfo
+ *
+ * @example
+ * const toolInfo: MCPToolInfo = {
+ *   name: 'my_tool',
+ *   description: 'Does something useful',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { input: { type: 'string' } },
+ *     required: ['input']
+ *   },
+ *   handler: async (params) => ({
+ *     content: [{ type: 'text', text: 'Result' }]
+ *   })
+ * }
  */
 export interface MCPToolInfo {
+    /** Unique tool name */
     name: string;
+    /** Human-readable description */
     description: string;
+    /** JSON Schema for input parameters */
     inputSchema: {
         type: string;
         properties?: Record<string, unknown>;
         required?: string[];
     };
+    /** Async function that executes the tool */
     handler: (params: Record<string, unknown>) => Promise<MCPToolResult>;
 }
 /**
- * Resource information for registration
+ * Resource information for registration.
+ *
+ * @description
+ * Defines a resource that can be read via the resources/read method.
+ * Resources have a URI, name, and optional handler for dynamic content.
+ *
+ * @interface MCPResourceInfo
+ *
+ * @example
+ * const resource: MCPResourceInfo = {
+ *   uri: 'git://repo/HEAD',
+ *   name: 'Current HEAD',
+ *   mimeType: 'text/plain',
+ *   description: 'The current HEAD commit',
+ *   handler: async () => ({ content: 'abc123...' })
+ * }
  */
 export interface MCPResourceInfo {
+    /** Unique resource URI */
     uri: string;
+    /** Human-readable name */
     name: string;
+    /** MIME type of the resource content */
     mimeType?: string;
+    /** Human-readable description */
     description?: string;
+    /** Async function to retrieve resource content */
     handler?: () => Promise<{
         content: string;
     }>;
 }
 /**
- * Prompt argument definition
+ * Prompt argument definition.
+ *
+ * @description
+ * Defines an argument that can be passed to a prompt template.
+ *
+ * @interface MCPPromptArgument
  */
 export interface MCPPromptArgument {
+    /** Argument name */
     name: string;
+    /** Human-readable description */
     description?: string;
+    /** Whether this argument is required */
     required?: boolean;
 }
 /**
- * Prompt information for registration
+ * Prompt information for registration.
+ *
+ * @description
+ * Defines a prompt template that can be retrieved via prompts/get.
+ * Prompts can have arguments and a handler to generate messages.
+ *
+ * @interface MCPPromptInfo
+ *
+ * @example
+ * const prompt: MCPPromptInfo = {
+ *   name: 'commit-message',
+ *   description: 'Generate a commit message',
+ *   arguments: [
+ *     { name: 'changes', description: 'Description of changes', required: true }
+ *   ],
+ *   handler: async (args) => ({
+ *     messages: [{
+ *       role: 'user',
+ *       content: { type: 'text', text: `Write commit message for: ${args.changes}` }
+ *     }]
+ *   })
+ * }
  */
 export interface MCPPromptInfo {
+    /** Unique prompt name */
     name: string;
+    /** Human-readable description */
     description?: string;
+    /** Prompt arguments */
     arguments?: MCPPromptArgument[];
+    /** Async function to generate prompt messages */
     handler?: (args: Record<string, unknown>) => Promise<{
         messages: Array<{
             role: string;
@@ -118,114 +367,406 @@ export interface MCPPromptInfo {
     }>;
 }
 /**
- * MCP Adapter class that bridges MCP protocol to git operations
+ * MCP Adapter class that bridges MCP protocol to git operations.
+ *
+ * @description
+ * The main adapter class that handles MCP protocol communication. It manages
+ * tool, resource, and prompt registrations, processes JSON-RPC requests,
+ * and returns properly formatted responses.
+ *
+ * The adapter supports the following MCP methods:
+ * - initialize: Server initialization and capability negotiation
+ * - tools/list: List all registered tools
+ * - tools/call: Invoke a registered tool
+ * - resources/list: List all registered resources
+ * - resources/read: Read a resource's content
+ * - prompts/list: List all registered prompts
+ * - prompts/get: Get a prompt's generated messages
+ *
+ * @class MCPAdapter
+ *
+ * @example
+ * // Create and use an adapter
+ * const adapter = new MCPAdapter({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   capabilities: ['tools']
+ * })
+ *
+ * adapter.registerGitTools()
+ * await adapter.start()
+ *
+ * const response = await adapter.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'tools/list'
+ * })
  */
 export declare class MCPAdapter {
+    /** @internal */
     private config;
+    /** @internal */
     private initialized;
+    /** @internal */
     private tools;
+    /** @internal */
     private resources;
+    /** @internal */
     private prompts;
+    /**
+     * Create a new MCP adapter instance.
+     *
+     * @param config - Optional configuration options
+     *
+     * @example
+     * const adapter = new MCPAdapter({
+     *   name: 'git-mcp-server',
+     *   version: '2.0.0',
+     *   capabilities: ['tools', 'resources', 'prompts']
+     * })
+     */
     constructor(config?: MCPServerConfig);
     /**
-     * Get the server configuration
+     * Get the server configuration.
+     *
+     * @description
+     * Returns a copy of the current server configuration including name,
+     * version, and enabled capabilities.
+     *
+     * @returns A copy of the server configuration
+     *
+     * @example
+     * const config = adapter.getConfig()
+     * console.log(`Server: ${config.name} v${config.version}`)
      */
     getConfig(): MCPServerConfig;
     /**
-     * Check if adapter has a specific capability
+     * Check if adapter has a specific capability.
+     *
+     * @description
+     * Tests whether a specific capability is enabled for this adapter.
+     * Used internally to determine which methods are available.
+     *
+     * @param capability - The capability to check ('tools', 'resources', or 'prompts')
+     * @returns True if the capability is enabled
+     *
+     * @example
+     * if (adapter.hasCapability('resources')) {
+     *   adapter.registerResource(myResource)
+     * }
      */
     hasCapability(capability: MCPCapability): boolean;
     /**
-     * Check if the adapter is initialized
+     * Check if the adapter is initialized.
+     *
+     * @description
+     * Returns whether the adapter has been started and is ready to handle requests.
+     *
+     * @returns True if the adapter is initialized and running
      */
     isInitialized(): boolean;
     /**
-     * Start the MCP adapter
+     * Start the MCP adapter.
+     *
+     * @description
+     * Initializes the adapter and prepares it to handle requests.
+     * Must be called before processing any MCP requests.
+     *
+     * @returns Promise that resolves when the adapter is started
+     * @throws {Error} If the adapter is already started
+     *
+     * @example
+     * const adapter = new MCPAdapter()
+     * await adapter.start()
+     * // Adapter is now ready to handle requests
      */
     start(): Promise<void>;
     /**
-     * Stop the MCP adapter
+     * Stop the MCP adapter.
+     *
+     * @description
+     * Shuts down the adapter and clears all registered tools, resources,
+     * and prompts. After stopping, the adapter must be restarted before
+     * handling new requests.
+     *
+     * @returns Promise that resolves when the adapter is stopped
+     * @throws {Error} If the adapter is not currently running
+     *
+     * @example
+     * await adapter.stop()
+     * // All registrations are cleared
      */
     stop(): Promise<void>;
     /**
-     * Register a tool
+     * Register a tool.
+     *
+     * @description
+     * Adds a tool to the adapter's registry. The tool will be available
+     * for listing via tools/list and invocation via tools/call.
+     *
+     * @param toolInfo - The tool definition to register
+     * @returns void
+     * @throws {Error} If a tool with the same name is already registered
+     *
+     * @example
+     * adapter.registerTool({
+     *   name: 'my_tool',
+     *   description: 'Does something',
+     *   inputSchema: { type: 'object', properties: {} },
+     *   handler: async (params) => ({
+     *     content: [{ type: 'text', text: 'Done' }]
+     *   })
+     * })
      */
     registerTool(toolInfo: MCPToolInfo): void;
     /**
-     * Unregister a tool by name
+     * Unregister a tool by name.
+     *
+     * @description
+     * Removes a tool from the adapter's registry. The tool will no longer
+     * be available for listing or invocation.
+     *
+     * @param name - The name of the tool to unregister
+     * @returns void
+     * @throws {Error} If no tool with the given name exists
+     *
+     * @example
+     * adapter.unregisterTool('my_tool')
      */
     unregisterTool(name: string): void;
     /**
-     * List all registered tools (without handlers)
+     * List all registered tools (without handlers).
+     *
+     * @description
+     * Returns an array of all registered tools with their metadata.
+     * Handler functions are omitted for serialization safety.
+     *
+     * @returns Array of tool definitions without handlers
+     *
+     * @example
+     * const tools = adapter.listTools()
+     * for (const tool of tools) {
+     *   console.log(`${tool.name}: ${tool.description}`)
+     * }
      */
     listTools(): Array<Omit<MCPToolInfo, 'handler'>>;
     /**
-     * Get a tool by name (without handler)
+     * Get a tool by name (without handler).
+     *
+     * @description
+     * Retrieves a single tool's metadata by name. Returns undefined if
+     * the tool is not found.
+     *
+     * @param name - The name of the tool to retrieve
+     * @returns The tool definition without handler, or undefined if not found
+     *
+     * @example
+     * const tool = adapter.getTool('git_status')
+     * if (tool) {
+     *   console.log(tool.description)
+     * }
      */
     getTool(name: string): Omit<MCPToolInfo, 'handler'> | undefined;
     /**
-     * Register all git tools
+     * Register all git tools.
+     *
+     * @description
+     * Convenience method that registers all built-in git tools from the
+     * tools module. Skips any tools that are already registered.
+     *
+     * @returns void
+     *
+     * @example
+     * const adapter = new MCPAdapter()
+     * adapter.registerGitTools()
+     * // All 18 git tools are now registered
      */
     registerGitTools(): void;
     /**
-     * Register a resource
+     * Register a resource.
+     *
+     * @description
+     * Adds a resource to the adapter's registry. The resource will be
+     * available for listing and reading via the resources/* methods.
+     *
+     * @param resourceInfo - The resource definition to register
+     * @returns void
+     *
+     * @example
+     * adapter.registerResource({
+     *   uri: 'git://repo/config',
+     *   name: 'Repository Config',
+     *   mimeType: 'application/json',
+     *   handler: async () => ({ content: JSON.stringify(config) })
+     * })
      */
     registerResource(resourceInfo: MCPResourceInfo): void;
     /**
-     * Register a prompt
+     * Register a prompt.
+     *
+     * @description
+     * Adds a prompt template to the adapter's registry. The prompt will
+     * be available for listing and retrieval via the prompts/* methods.
+     *
+     * @param promptInfo - The prompt definition to register
+     * @returns void
+     *
+     * @example
+     * adapter.registerPrompt({
+     *   name: 'review-code',
+     *   description: 'Review code changes',
+     *   handler: async () => ({
+     *     messages: [{ role: 'user', content: { type: 'text', text: '...' } }]
+     *   })
+     * })
      */
     registerPrompt(promptInfo: MCPPromptInfo): void;
     /**
-     * Handle a raw JSON string request
+     * Handle a raw JSON string request.
+     *
+     * @description
+     * Parses a raw JSON string as an MCP request and processes it.
+     * Returns a parse error response if the JSON is invalid.
+     *
+     * @param rawRequest - Raw JSON string containing the request
+     * @returns Promise resolving to the MCP response
+     *
+     * @example
+     * const response = await adapter.handleRawRequest(
+     *   '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+     * )
      */
     handleRawRequest(rawRequest: string): Promise<MCPResponse>;
     /**
-     * Handle a batch of requests
+     * Handle a batch of requests.
+     *
+     * @description
+     * Processes multiple MCP requests sequentially. Notifications (requests
+     * without an id) are processed but do not produce responses.
+     *
+     * @param requests - Array of MCP requests to process
+     * @returns Promise resolving to array of responses (excluding notifications)
+     *
+     * @example
+     * const responses = await adapter.handleBatchRequest([
+     *   { jsonrpc: '2.0', id: 1, method: 'tools/list' },
+     *   { jsonrpc: '2.0', id: 2, method: 'initialize', params: {} }
+     * ])
      */
     handleBatchRequest(requests: MCPRequest[]): Promise<MCPResponse[]>;
     /**
-     * Handle a single MCP request
+     * Handle a single MCP request.
+     *
+     * @description
+     * Main request handler that routes MCP requests to the appropriate
+     * method handler. Supports initialize, tools/*, resources/*, and prompts/*
+     * methods. Returns undefined for notifications (requests without id).
+     *
+     * @param request - The MCP request to handle
+     * @returns Promise resolving to response, or undefined for notifications
+     *
+     * @example
+     * const response = await adapter.handleRequest({
+     *   jsonrpc: '2.0',
+     *   id: 1,
+     *   method: 'tools/call',
+     *   params: { name: 'git_status', arguments: {} }
+     * })
      */
     handleRequest(request: MCPRequest): Promise<MCPResponse | undefined>;
     /**
-     * Handle initialize request
+     * Handle initialize request.
+     *
+     * @description
+     * Processes the MCP initialize request and returns server information
+     * and capabilities. This is the first request a client should send.
+     *
+     * @param request - The initialize request
+     * @returns Response with server info and capabilities
+     * @internal
      */
     private handleInitialize;
     /**
-     * Handle tools/list request
+     * Handle tools/list request.
+     * @param request - The tools/list request
+     * @returns Response with list of registered tools
+     * @internal
      */
     private handleToolsList;
     /**
-     * Handle tools/call request
+     * Handle tools/call request.
+     * @param request - The tools/call request with tool name and arguments
+     * @returns Response with tool execution result
+     * @internal
      */
     private handleToolsCall;
     /**
-     * Validate tool parameters against schema
+     * Validate tool parameters against schema.
+     * @param tool - The tool to validate parameters for
+     * @param params - The parameters to validate
+     * @returns Validation result with errors array
+     * @internal
      */
     private validateToolParams;
     /**
-     * Handle resources/list request
+     * Handle resources/list request.
+     * @param request - The resources/list request
+     * @returns Response with list of registered resources
+     * @internal
      */
     private handleResourcesList;
     /**
-     * Handle resources/read request
+     * Handle resources/read request.
+     * @param request - The resources/read request with URI
+     * @returns Response with resource content
+     * @internal
      */
     private handleResourcesRead;
     /**
-     * Handle prompts/list request
+     * Handle prompts/list request.
+     * @param request - The prompts/list request
+     * @returns Response with list of registered prompts
+     * @internal
      */
     private handlePromptsList;
     /**
-     * Handle prompts/get request
+     * Handle prompts/get request.
+     * @param request - The prompts/get request with name and arguments
+     * @returns Response with generated prompt messages
+     * @internal
      */
     private handlePromptsGet;
     /**
-     * Create an error response
+     * Create an error response.
+     * @param id - Request ID
+     * @param code - Error code
+     * @param message - Error message
+     * @param data - Optional additional error data
+     * @returns Formatted error response
+     * @internal
      */
     private errorResponse;
 }
 /**
- * Factory function to create an MCP adapter
+ * Factory function to create an MCP adapter.
+ *
+ * @description
+ * Convenience function for creating a new MCP adapter instance.
+ * Equivalent to using `new MCPAdapter(config)`.
+ *
+ * @param config - Optional server configuration
+ * @returns A new MCPAdapter instance
+ *
+ * @example
+ * import { createMCPAdapter } from './adapter'
+ *
+ * const adapter = createMCPAdapter({
+ *   name: 'my-git-server',
+ *   capabilities: ['tools', 'resources']
+ * })
+ *
+ * adapter.registerGitTools()
+ * await adapter.start()
  */
 export declare function createMCPAdapter(config?: MCPServerConfig): MCPAdapter;
 //# sourceMappingURL=adapter.d.ts.map