gitx.do 0.0.1 → 0.0.3

package/dist/mcp/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/mcp/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/mcp/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,SAAS,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oBAAY,YAAY;IACtB,uDAAuD;IACvD,WAAW,SAAS;IACpB,6EAA6E;IAC7E,eAAe,SAAS;IACxB,gFAAgF;IAChF,gBAAgB,SAAS;IACzB,4DAA4D;IAC5D,cAAc,SAAS;IACvB,wDAAwD;IACxD,cAAc,SAAS;IAEvB,0EAA0E;IAC1E,kBAAkB,SAAS;IAC3B,8EAA8E;IAC9E,cAAc,SAAS;IACvB,sEAAsE;IACtE,gBAAgB,SAAS;IACzB,kFAAkF;IAClF,wBAAwB,SAAS;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,yBAAyB;IACzB,IAAI,EAAE,YAAY,CAAA;IAClB,qCAAqC;IACrC,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;;;;;OAMG;gBACS,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAO/D;;;;OAIG;IACH,MAAM,IAAI;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;CAUlE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAA;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,YAAY,CAAC,EAAE,aAAa,EAAE,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,OAAO,EAAE,KAAK,CAAA;IACd,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,OAAO,EAAE,KAAK,CAAA;IACd,wDAAwD;IACxD,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpB,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,KAAK,CAAC,EAAE;QACN,yBAAyB;QACzB,IAAI,EAAE,MAAM,CAAA;QACZ,mCAAmC;QACnC,OAAO,EAAE,MAAM,CAAA;QACf,4BAA4B;QAC5B,IAAI,CAAC,EAAE,OAAO,CAAA;KACf,CAAA;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAA;QACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,CAAA;IACD,4CAA4C;IAC5C,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;CACrE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC7C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uBAAuB;IACvB,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC/B,iDAAiD;IACjD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QACnD,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,CAAA;YACZ,OAAO,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,CAAA;SACxC,CAAC,CAAA;KACH,CAAC,CAAA;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,UAAU;IACrB,gBAAgB;IAChB,OAAO,CAAC,MAAM,CAA2B;IACzC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAAiB;IACpC,gBAAgB;IAChB,OAAO,CAAC,KAAK,CAAsC;IACnD,gBAAgB;IAChB,OAAO,CAAC,SAAS,CAA0C;IAC3D,gBAAgB;IAChB,OAAO,CAAC,OAAO,CAAwC;IAEvD;;;;;;;;;;;OAWG;gBACS,MAAM,CAAC,EAAE,eAAe;IAQpC;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,eAAe;IAI5B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO;IAIjD;;;;;;;OAOG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;;;;;;;;;;;OAcG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;;;;;;;;;;;;OAcG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAOzC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOlC;;;;;;;;;;;;;;OAcG;IACH,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAYhD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,SAAS;IAU/D;;;;;;;;;;;;;OAaG;IACH,gBAAgB,IAAI,IAAI;IAaxB;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,YAAY,EAAE,eAAe,GAAG,IAAI;IAIrD;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI;IAI/C;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAuBhE;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAYxE;;;;;;;;;;;;;;;;;;OAkBG;IACG,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IA2D1E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IA6BxB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;;OAKG;YACW,eAAe;IA2D7B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAkD1B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;;;;OAKG;YACW,mBAAmB;IA0CjC;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;;;;OAKG;YACW,gBAAgB;IAmC9B;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;CAgBtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,CAErE"}

package/dist/mcp/adapter.js

@@ -1,41 +1,142 @@
 /**
- * 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 { gitTools } 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 var MCPErrorCode;
 (function (MCPErrorCode) {
-    // JSON-RPC standard error codes
+    /** Parse error - Invalid JSON was received (-32700) */
     MCPErrorCode[MCPErrorCode["PARSE_ERROR"] = -32700] = "PARSE_ERROR";
+    /** Invalid Request - The JSON sent is not a valid Request object (-32600) */
     MCPErrorCode[MCPErrorCode["INVALID_REQUEST"] = -32600] = "INVALID_REQUEST";
+    /** Method not found - The method does not exist or is not available (-32601) */
     MCPErrorCode[MCPErrorCode["METHOD_NOT_FOUND"] = -32601] = "METHOD_NOT_FOUND";
+    /** Invalid params - Invalid method parameter(s) (-32602) */
     MCPErrorCode[MCPErrorCode["INVALID_PARAMS"] = -32602] = "INVALID_PARAMS";
+    /** Internal error - Internal JSON-RPC error (-32603) */
     MCPErrorCode[MCPErrorCode["INTERNAL_ERROR"] = -32603] = "INTERNAL_ERROR";
-    // MCP-specific error codes (must be < -32000 per JSON-RPC spec)
+    /** Resource not found - The requested resource does not exist (-32001) */
     MCPErrorCode[MCPErrorCode["RESOURCE_NOT_FOUND"] = -32001] = "RESOURCE_NOT_FOUND";
-    // TOOL_NOT_FOUND maps to METHOD_NOT_FOUND as tools are essentially methods
+    /** Tool not found - Maps to METHOD_NOT_FOUND as tools are methods (-32601) */
     MCPErrorCode[MCPErrorCode["TOOL_NOT_FOUND"] = -32601] = "TOOL_NOT_FOUND";
+    /** Prompt not found - The requested prompt does not exist (-32003) */
     MCPErrorCode[MCPErrorCode["PROMPT_NOT_FOUND"] = -32003] = "PROMPT_NOT_FOUND";
+    /** Capability not supported - The requested capability is not enabled (-32004) */
     MCPErrorCode[MCPErrorCode["CAPABILITY_NOT_SUPPORTED"] = -32004] = "CAPABILITY_NOT_SUPPORTED";
 })(MCPErrorCode || (MCPErrorCode = {}));
 /**
- * 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 class MCPError extends Error {
+    /** The MCP error code */
     code;
+    /** Optional additional error data */
     data;
+    /**
+     * 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, message, data) {
         super(message);
         this.code = code;
         this.data = data;
         this.name = 'MCPError';
     }
+    /**
+     * Convert the error to JSON-RPC error format.
+     *
+     * @returns Object suitable for JSON-RPC error responses
+     */
     toJSON() {
         const result = {
             code: this.code,
@@ -48,14 +149,64 @@ export class MCPError extends Error {
     }
 }
 /**
- * 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 class MCPAdapter {
+    /** @internal */
     config;
+    /** @internal */
     initialized = false;
+    /** @internal */
     tools = new Map();
+    /** @internal */
     resources = new Map();
+    /** @internal */
     prompts = new Map();
+    /**
+     * 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) {
         this.config = {
             name: config?.name || 'gitx.do',
@@ -64,25 +215,64 @@ export class MCPAdapter {
         };
     }
     /**
-     * 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() {
         return { ...this.config };
     }
     /**
-     * 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) {
         return this.config.capabilities.includes(capability);
     }
     /**
-     * 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() {
         return this.initialized;
     }
     /**
-     * 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
      */
     async start() {
         if (this.initialized) {
@@ -91,7 +281,19 @@ export class MCPAdapter {
         this.initialized = true;
     }
     /**
-     * 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
      */
     async stop() {
         if (!this.initialized) {
@@ -103,7 +305,25 @@ export class MCPAdapter {
         this.prompts.clear();
     }
     /**
-     * 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) {
         if (this.tools.has(toolInfo.name)) {
@@ -112,7 +332,18 @@ export class MCPAdapter {
         this.tools.set(toolInfo.name, toolInfo);
     }
     /**
-     * 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) {
         if (!this.tools.has(name)) {
@@ -121,7 +352,19 @@ export class MCPAdapter {
         this.tools.delete(name);
     }
     /**
-     * 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() {
         const result = [];
@@ -135,7 +378,20 @@ export class MCPAdapter {
         return result;
     }
     /**
-     * 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) {
         const tool = this.tools.get(name);
@@ -148,7 +404,18 @@ export class MCPAdapter {
         };
     }
     /**
-     * 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() {
         for (const tool of gitTools) {
@@ -163,19 +430,62 @@ export class MCPAdapter {
         }
     }
     /**
-     * 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) {
         this.resources.set(resourceInfo.uri, resourceInfo);
     }
     /**
-     * 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) {
         this.prompts.set(promptInfo.name, promptInfo);
     }
     /**
-     * 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"}'
+     * )
      */
     async handleRawRequest(rawRequest) {
         let request;
@@ -201,7 +511,20 @@ export class MCPAdapter {
         };
     }
     /**
-     * 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: {} }
+     * ])
      */
     async handleBatchRequest(requests) {
         const responses = [];
@@ -215,7 +538,23 @@ export class MCPAdapter {
         return responses;
     }
     /**
-     * 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: {} }
+     * })
      */
     async handleRequest(request) {
         // Handle notifications (no id) - they don't expect a response
@@ -256,7 +595,15 @@ export class MCPAdapter {
         }
     }
     /**
-     * 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
      */
     handleInitialize(request) {
         const params = request.params || {};
@@ -285,7 +632,10 @@ export class MCPAdapter {
         };
     }
     /**
-     * Handle tools/list request
+     * Handle tools/list request.
+     * @param request - The tools/list request
+     * @returns Response with list of registered tools
+     * @internal
      */
     handleToolsList(request) {
         if (!this.hasCapability('tools')) {
@@ -300,7 +650,10 @@ export class MCPAdapter {
         };
     }
     /**
-     * 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
      */
     async handleToolsCall(request) {
         if (!this.hasCapability('tools')) {
@@ -346,7 +699,11 @@ export class MCPAdapter {
         }
     }
     /**
-     * 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
      */
     validateToolParams(tool, params) {
         const errors = [];
@@ -385,7 +742,10 @@ export class MCPAdapter {
         return { valid: errors.length === 0, errors };
     }
     /**
-     * Handle resources/list request
+     * Handle resources/list request.
+     * @param request - The resources/list request
+     * @returns Response with list of registered resources
+     * @internal
      */
     handleResourcesList(request) {
         if (!this.hasCapability('resources')) {
@@ -404,7 +764,10 @@ export class MCPAdapter {
         };
     }
     /**
-     * Handle resources/read request
+     * Handle resources/read request.
+     * @param request - The resources/read request with URI
+     * @returns Response with resource content
+     * @internal
      */
     async handleResourcesRead(request) {
         if (!this.hasCapability('resources')) {
@@ -436,7 +799,10 @@ export class MCPAdapter {
         };
     }
     /**
-     * Handle prompts/list request
+     * Handle prompts/list request.
+     * @param request - The prompts/list request
+     * @returns Response with list of registered prompts
+     * @internal
      */
     handlePromptsList(request) {
         if (!this.hasCapability('prompts')) {
@@ -454,7 +820,10 @@ export class MCPAdapter {
         };
     }
     /**
-     * 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
      */
     async handlePromptsGet(request) {
         if (!this.hasCapability('prompts')) {
@@ -479,7 +848,13 @@ export class MCPAdapter {
         };
     }
     /**
-     * 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
      */
     errorResponse(id, code, message, data) {
         const response = {
@@ -494,7 +869,25 @@ export class MCPAdapter {
     }
 }
 /**
- * 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 function createMCPAdapter(config) {
     return new MCPAdapter(config);