@forge-sdk/mcp

import * as api from '@forge-sdk/mcp';

export interface OAuthConfig {
  /** The OAuth client ID. */
  readonly clientId: string;
  /** The OAuth client secret (optional for public clients). */
  readonly clientSecret?: string;
  /** The redirect URI for the authorization callback. */
  readonly redirectUri: string;
  /** The authorization endpoint URL. */
  readonly authUrl: string;
  /** The token endpoint URL. */
  readonly tokenUrl: string;
}

export interface PkceChallenge {
  /** The code verifier (random string). */
  readonly verifier: string;
  /** The code challenge (derived from verifier). */
  readonly challenge: string;
  /** The challenge method ('S256'). */
  readonly method: 'S256';
}

export async function generatePkceChallenge(): Promise<PkceChallenge>;

export interface McpClientConfig {
  /** The transport configuration. */
  readonly transport: TransportConfig;
  /** Optional OAuth configuration for authenticated connections. */
  readonly auth?: OAuthConfig;
}

export class McpClient {
  constructor(config: McpClientConfig);
  async connect(): Promise<void>;
  capabilities(): McpCapabilities | undefined;
  async listTools(): Promise<McpToolDescriptor[]>;
  async callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
  async listResources(): Promise<McpResource[]>;
  async getResource(uri: string): Promise<unknown>;
  async listPrompts(): Promise<McpPrompt[]>;
  async getPrompt(name: string, args?: Record<string, string>): Promise<unknown>;
  async disconnect(): Promise<void>;
  get connected(): boolean;
}

export const ForgeMcpErrorCode /* type inferred in source */;

export type ForgeMcpErrorCodeType = (typeof ForgeMcpErrorCode)[keyof typeof ForgeMcpErrorCode];

export class ForgeMcpError extends Error {
  public readonly code: ForgeMcpErrorCodeType;
  static connectionFailed(url: string, reason: string): ForgeMcpError;
  static transportError(transport: string, reason: string): ForgeMcpError;
  static protocolError(reason: string): ForgeMcpError;
  static toolNotFound(toolName: string): ForgeMcpError;
  static serializationError(reason: string): ForgeMcpError;
  static authError(reason: string): ForgeMcpError;
  static core(reason: string): ForgeMcpError;
}

export { ForgeMcpError, ForgeMcpErrorCode, type ForgeMcpErrorCodeType } from './error.js';

export {
  type McpToolDescriptor,
  type McpResource,
  type McpPrompt,
  type McpPromptArgument,
  type McpRequest,
  type McpResponse,
  type McpErrorObject,
  type McpRequestId,
  type McpCapabilities,
} from './types.js';

export {
  type McpTransport,
  type TransportConfig,
  StdioTransport,
  SseTransport,
  HttpTransport,
  createTransport,
} from './transport.js';

export { McpClient, type McpClientConfig } from './client.js';

export {
  McpServer,
  type McpServerConfig,
  type ToolHandler,
  type ResourceHandler,
  type PromptHandler,
} from './server.js';

export {
  type OAuthConfig,
  type PkceChallenge,
  generatePkceChallenge,
} from './auth.js';

export type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;

export type ResourceHandler = (uri: string) => Promise<unknown>;

export type PromptHandler = (args: Record<string, string>) => Promise<unknown>;

export interface McpServerConfig {
  /** The server name. */
  readonly name: string;
  /** The server version. */
  readonly version: string;
}

export class McpServer {
  constructor(config: McpServerConfig);
  registerTool(descriptor: McpToolDescriptor, handler: ToolHandler): void;
  registerResource(resource: McpResource, handler: ResourceHandler): void;
  registerPrompt(prompt: McpPrompt, handler: PromptHandler): void;
  capabilities(): McpCapabilities;
  async handleRequest(request: McpRequest): Promise<McpResponse>;
}

export type TransportConfig =
  | { readonly type: 'stdio' }
  | { readonly type: 'sse'; readonly url: string }
  | { readonly type: 'http'; readonly url: string };

export interface McpTransport {
  /**
   * Sends a JSON-RPC 2.0 request.
   *
   * @param request - The request to send.
   * @throws {ForgeMcpError} If the send fails.
   */
  send(request: McpRequest): Promise<void>;

  /**
   * Receives the next JSON-RPC 2.0 response.
   *
   * @returns The response message.
   * @throws {ForgeMcpError} If the receive fails or the transport is closed.
   */
  receive(): Promise<McpResponse>;

  /**
   * Closes the transport connection.
   *
   * After closing, no further sends or receives are allowed.
   */
  close(): Promise<void>;
}

export interface StdioLineReader {
  /**
   * Reads the next newline-delimited JSON line.
   *
   * Returns `null` on clean EOF.
   */
  readLine(): Promise<string | null>;
}

export interface StdioLineWriter {
  /**
   * Writes a single JSON line without a trailing newline.
   */
  writeLine(line: string): Promise<void>;
}

export interface StdioTransportOptions {
  readonly reader?: StdioLineReader;
  readonly writer?: StdioLineWriter;
}

export class StdioTransport implements McpTransport {
  constructor(options?: StdioTransportOptions);
  async send(request: McpRequest): Promise<void>;
  async receive(): Promise<McpResponse>;
  async close(): Promise<void>;
}

export class SseTransport implements McpTransport {
  constructor(url: string);
  async send(request: McpRequest): Promise<void>;
  async receive(): Promise<McpResponse>;
  async close(): Promise<void>;
}

export class HttpTransport implements McpTransport {
  constructor(url: string);
  async send(request: McpRequest): Promise<void>;
  async receive(): Promise<McpResponse>;
  async close(): Promise<void>;
}

export function createTransport(config: TransportConfig): McpTransport;

export interface McpToolDescriptor {
  /** The unique name of the tool. */
  readonly name: string;
  /** A human-readable description of the tool's purpose. */
  readonly description: string;
  /** The JSON Schema for the tool's input parameters. */
  readonly inputSchema: Record<string, unknown>;
}

export interface McpResource {
  /** The URI identifying this resource. */
  readonly uri: string;
  /** A human-readable name for the resource. */
  readonly name: string;
  /** An optional description. */
  readonly description?: string;
  /** The MIME type of the resource content. */
  readonly mimeType?: string;
}

export interface McpPromptArgument {
  /** The argument name. */
  readonly name: string;
  /** An optional description. */
  readonly description?: string;
  /** Whether this argument is required. */
  readonly required: boolean;
}

export interface McpPrompt {
  /** The unique name of the prompt. */
  readonly name: string;
  /** An optional description. */
  readonly description?: string;
  /** The prompt's arguments. */
  readonly arguments: readonly McpPromptArgument[];
}

export type McpRequestId = number | string | null;

export interface McpRequest {
  /** JSON-RPC version. Always '2.0'. */
  readonly jsonrpc: '2.0';
  /** The request ID for matching responses. */
  readonly id: McpRequestId;
  /** The method name. */
  readonly method: string;
  /** Optional parameters. */
  readonly params?: Record<string, unknown>;
}

export interface McpErrorObject {
  /** The error code. */
  readonly code: number;
  /** A human-readable error message. */
  readonly message: string;
  /** Optional additional error data. */
  readonly data?: unknown;
}

export interface McpResponse {
  /** JSON-RPC version. Always '2.0'. */
  readonly jsonrpc: '2.0';
  /** The request ID this response corresponds to. */
  readonly id: McpRequestId;
  /** The result on success. */
  readonly result?: unknown;
  /** The error on failure. */
  readonly error?: McpErrorObject;
}

export interface McpCapabilities {
  /** Whether the server provides tools. */
  readonly tools: boolean;
  /** Whether the server provides resources. */
  readonly resources: boolean;
  /** Whether the server provides prompts. */
  readonly prompts: boolean;
}