@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/workbench/contrib/mcp/common/mcpRegistryTypes.service.d.ts

@@ -10,25 +10,34 @@ import { McpCollectionDefinition, LazyCollectionState, McpDefinitionReference, M
 export declare const IMcpRegistry: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IMcpRegistry>;
 export interface IMcpRegistry {
     readonly _serviceBrand: undefined;
+    /** Fired when the user provides more inputs when creating a connection. */
     readonly onDidChangeInputs: Event<void>;
     readonly collections: IObservable<readonly McpCollectionDefinition[]>;
     readonly delegates: IObservable<readonly IMcpHostDelegate[]>;
+    /** Whether there are new collections that can be resolved with a discover() call */
     readonly lazyCollectionState: IObservable<{
         state: LazyCollectionState;
         collections: McpCollectionDefinition[];
     }>;
+    /** Helper function to observe a definition by its reference. */
     getServerDefinition(collectionRef: McpDefinitionReference, definitionRef: McpDefinitionReference): IObservable<{
         server: McpServerDefinition | undefined;
         collection: McpCollectionDefinition | undefined;
     }>;
+    /** Discover new collections, returning newly-discovered ones. */
     discoverCollections(): Promise<McpCollectionDefinition[]>;
     registerDelegate(delegate: IMcpHostDelegate): IDisposable;
     registerCollection(collection: McpCollectionDefinition): IDisposable;
+    /** Resets any saved inputs for the input, or globally. */
     clearSavedInputs(scope: StorageScope, inputId?: string): Promise<void>;
+    /** Edits a previously-saved input. */
     editSavedInput(inputId: string, folderData: IWorkspaceFolderData | undefined, configSection: string, target: ConfigurationTarget): Promise<void>;
+    /** Updates a saved input. */
     setSavedInput(inputId: string, target: ConfigurationTarget, value: string): Promise<void>;
+    /** Gets saved inputs from storage. */
     getSavedInputs(scope: StorageScope): Promise<{
         [id: string]: IResolvedValue;
     }>;
+    /** Creates a connection for the collection and definition. */
     resolveConnection(options: IMcpResolveConnectionOptions): Promise<IMcpServerConnection | undefined>;
 }

package/vscode/src/vs/workbench/contrib/mcp/common/mcpTypes.d.ts

@@ -19,23 +19,44 @@ import { MCP } from "./modelContextProtocol.js";
 import { UriTemplate } from "@codingame/monaco-vscode-mcp-service-override/vscode/vs/workbench/contrib/mcp/common/uriTemplate";
 export declare const extensionMcpCollectionPrefix = "ext.";
 export declare function extensionPrefixedIdentifier(identifier: ExtensionIdentifier, id: string): string;
+/**
+ * An McpCollection contains McpServers. There may be multiple collections for
+ * different locations servers are discovered.
+ */
 export interface McpCollectionDefinition {
+    /** Origin authority from which this collection was discovered. */
     readonly remoteAuthority: string | null;
+    /** Globally-unique, stable ID for this definition */
     readonly id: string;
+    /** Human-readable label for the definition */
     readonly label: string;
+    /** Definitions this collection contains. */
     readonly serverDefinitions: IObservable<readonly McpServerDefinition[]>;
+    /**
+     * Trust behavior of the servers. `Trusted` means it will run without a prompt, always.
+     * `TrustedOnNonce` means it will run without a prompt as long as the nonce matches.
+     */
     readonly trustBehavior: McpServerTrust.Kind.Trusted | McpServerTrust.Kind.TrustedOnNonce;
+    /** Scope where associated collection info should be stored. */
     readonly scope: StorageScope;
+    /** Configuration target where configuration related to this server should be stored. */
     readonly configTarget: ConfigurationTarget;
+    /** Resolves a server definition. If present, always called before a server starts. */
     resolveServerLanch?(definition: McpServerDefinition): Promise<McpServerLaunch | undefined>;
+    /** For lazy-loaded collections only: */
     readonly lazy?: {
+        /** True if `serverDefinitions` were loaded from the cache */
         isCached: boolean;
+        /** Triggers a load of the real server definition, which should be pushed to the IMcpRegistry. If not this definition will be removed. */
         load(): Promise<void>;
+        /** Called after `load()` if the extension is not found. */
         removed?(): void;
     };
     readonly source?: IWorkbenchMcpServer | ExtensionIdentifier;
     readonly presentation?: {
+        /** Sort order of the collection. */
         readonly order?: number;
+        /** Place where this collection is configured, used in workspace trust prompts and "show config" */
         readonly origin?: URI;
     };
 }
@@ -60,15 +81,24 @@ export declare namespace McpCollectionDefinition {
     function equals(a: McpCollectionDefinition, b: McpCollectionDefinition): boolean;
 }
 export interface McpServerDefinition {
+    /** Globally-unique, stable ID for this definition */
     readonly id: string;
+    /** Human-readable label for the definition */
     readonly label: string;
+    /** Descriptor defining how the configuration should be launched. */
     readonly launch: McpServerLaunch;
+    /** Explicit roots. If undefined, all workspace folders. */
     readonly roots?: URI[] | undefined;
+    /** If set, allows configuration variables to be resolved in the {@link launch} with the given context */
     readonly variableReplacement?: McpServerDefinitionVariableReplacement;
+    /** Nonce used for caching the server. Changing the nonce will indicate that tools need to be refreshed. */
     readonly cacheNonce: string;
+    /** Dev mode configuration for the server */
     readonly devMode?: IMcpDevModeConfig;
     readonly presentation?: {
+        /** Sort order of the definition. */
         readonly order?: number;
+        /** Place where this server is configured, used in workspace trust prompts and "show config" */
         readonly origin?: Location;
     };
 }
@@ -117,6 +147,7 @@ export interface McpDefinitionReference {
     label: string;
 }
 export declare class McpStartServerInteraction {
+    /** @internal */
     readonly participants: ObservableMap<string, {
         s: "unknown" | "resolved";
     } | {
@@ -127,16 +158,32 @@ export declare class McpStartServerInteraction {
     choice?: Promise<string[] | undefined>;
 }
 export interface IMcpServerStartOpts {
+    /**
+     * Automatically trust if changed. This should ONLY be set for afforances that
+     * ensure the user sees the config before it gets started (e.g. code lenses)
+     */
     autoTrustChanges?: boolean;
+    /**
+     * When to trigger the trust prompt.
+     * - only-new: only prompt for servers that are not previously explicitly untrusted (default)
+     * - all-untrusted: prompt for all servers that are not trusted
+     * - never: don't prompt, fail silently when trying to start an untrusted server
+     */
     promptType?: "only-new" | "all-untrusted" | "never";
+    /** True if th servre should be launched with debugging. */
     debug?: boolean;
+    /** Correlate multiple interactions such that any trust prompts are presented in combination. */
     interaction?: McpStartServerInteraction;
 }
 export declare namespace McpServerTrust {
     enum Kind {
+        /** The server is trusted */
         Trusted = 0,
+        /** The server is trusted as long as its nonce matches */
         TrustedOnNonce = 1,
+        /** The server trust was denied. */
         Untrusted = 2,
+        /** The server is not yet trusted or untrusted. */
         Unknown = 3
     }
 }
@@ -149,22 +196,44 @@ export interface IMcpServer extends IDisposable {
         serverName?: string;
         serverInstructions?: string;
     } | undefined>;
+    /**
+     * Full definition as it exists in the MCP registry. Unlike the references
+     * in `collection` and `definition`, this may change over time.
+     */
     readDefinitions(): IObservable<{
         server: McpServerDefinition | undefined;
         collection: McpCollectionDefinition | undefined;
     }>;
     showOutput(): void;
+    /**
+     * Starts the server and returns its resulting state. One of:
+     * - Running, if all good
+     * - Error, if the server failed to start
+     * - Stopped, if the server was disposed or the user cancelled the launch
+     */
     start(opts?: IMcpServerStartOpts): Promise<McpConnectionState>;
     stop(): Promise<void>;
     readonly cacheState: IObservable<McpServerCacheState>;
     readonly tools: IObservable<readonly IMcpTool[]>;
     readonly prompts: IObservable<readonly IMcpPrompt[]>;
     readonly capabilities: IObservable<McpCapability | undefined>;
+    /**
+     * Lists all resources on the server.
+     */
     resources(token?: CancellationToken): AsyncIterable<IMcpResource[]>;
+    /**
+     * List resource templates on the server.
+     */
     resourceTemplates(token?: CancellationToken): Promise<IMcpResourceTemplate[]>;
 }
+/**
+ * A representation of an MCP resource. The `uri` is namespaced to VS Code and
+ * can be used in filesystem APIs.
+ */
 export interface IMcpResource {
+    /** Identifier for the file in VS Code and operable with filesystem API */
     readonly uri: URI;
+    /** Identifier of the file as given from the MCP server. */
     readonly mcpUri: string;
     readonly name: string;
     readonly title?: string;
@@ -178,17 +247,25 @@ export interface IMcpResourceTemplate {
     readonly description?: string;
     readonly mimeType?: string;
     readonly template: UriTemplate;
+    /** Gets string completions for the given template part. */
     complete(templatePart: string, prefix: string, alreadyResolved: Record<string, string | string[]>, token: CancellationToken): Promise<string[]>;
+    /** Gets the resolved URI from template parts. */
     resolveURI(vars: Record<string, unknown>): URI;
 }
 export declare const isMcpResourceTemplate: (obj: IMcpResource | IMcpResourceTemplate) => obj is IMcpResourceTemplate;
 export declare const isMcpResource: (obj: IMcpResource | IMcpResourceTemplate) => obj is IMcpResource;
 export declare enum McpServerCacheState {
+    /** Tools have not been read before */
     Unknown = 0,
+    /** Tools were read from the cache */
     Cached = 1,
+    /** Tools were read from the cache or live, but they may be outdated. */
     Outdated = 2,
+    /** Tools are refreshing for the first time */
     RefreshingFromUnknown = 3,
+    /** Tools are refreshing and the current tools are cached */
     RefreshingFromCached = 4,
+    /** Tool state is live, server is connected */
     Live = 5
 }
 export interface IMcpPrompt {
@@ -197,6 +274,7 @@ export interface IMcpPrompt {
     readonly title?: string;
     readonly description?: string;
     readonly arguments: readonly MCP.PromptArgument[];
+    /** Gets string completions for the given prompt part. */
     complete(argument: string, prefix: string, alreadyResolved: Record<string, string>, token: CancellationToken): Promise<string[]>;
     resolve(args: Record<string, string | undefined>, token?: CancellationToken): Promise<IMcpPromptMessage[]>;
 }
@@ -210,15 +288,30 @@ export interface IMcpToolCallContext {
 }
 export interface IMcpTool {
     readonly id: string;
+    /** Name for #referencing in chat */
     readonly referenceName: string;
     readonly definition: MCP.Tool;
+    /**
+     * Calls a tool
+     * @throws {@link MpcResponseError} if the tool fails to execute
+     * @throws {@link McpConnectionFailedError} if the connection to the server fails
+     */
     call(params: Record<string, unknown>, context?: IMcpToolCallContext, token?: CancellationToken): Promise<MCP.CallToolResult>;
+    /**
+     * Identical to {@link call}, but reports progress.
+     */
     callWithProgress(params: Record<string, unknown>, progress: ToolProgress, context?: IMcpToolCallContext, token?: CancellationToken): Promise<MCP.CallToolResult>;
 }
 export declare enum McpServerTransportType {
+    /** A command-line MCP server communicating over standard in/out */
     Stdio = 1,
+    /** An MCP server that uses Server-Sent Events */
     HTTP = 2
 }
+/**
+ * MCP server launched on the command line which communicated over stdio.
+ * https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#stdio
+ */
 export interface McpServerTransportStdio {
     readonly type: McpServerTransportType.Stdio;
     readonly cwd: string | undefined;
@@ -227,6 +320,11 @@ export interface McpServerTransportStdio {
     readonly env: Record<string, string | number | null>;
     readonly envFile: string | undefined;
 }
+/**
+ * MCP server launched on the command line which communicated over SSE or Streamable HTTP.
+ * https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse
+ * https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http
+ */
 export interface McpServerTransportHTTP {
     readonly type: McpServerTransportType.HTTP;
     readonly uri: URI;
@@ -256,18 +354,41 @@ export declare namespace McpServerLaunch {
     function fromSerialized(launch: McpServerLaunch.Serialized): McpServerLaunch;
     function hash(launch: McpServerLaunch): Promise<string>;
 }
+/**
+ * An instance that manages a connection to an MCP server. It can be started,
+ * stopped, and restarted. Once started and in a running state, it will
+ * eventually build a {@link IMcpServerConnection.handler}.
+ */
 export interface IMcpServerConnection extends IDisposable {
     readonly definition: McpServerDefinition;
     readonly state: IObservable<McpConnectionState>;
     readonly handler: IObservable<McpServerRequestHandler | undefined>;
+    /**
+     * Resolved launch definition. Might not match the `definition.launch` due to
+     * resolution logic in extension-provided MCPs.
+     */
     readonly launchDefinition: McpServerLaunch;
+    /**
+     * Starts the server if it's stopped. Returns a promise that resolves once
+     * server exits a 'starting' state.
+     */
     start(methods: IMcpClientMethods): Promise<McpConnectionState>;
+    /**
+     * Stops the server.
+     */
     stop(): Promise<void>;
 }
+/** Client methods whose implementations are passed through the server connection. */
 export interface IMcpClientMethods {
+    /** Handler for `sampling/createMessage` */
     createMessageRequestHandler?(req: MCP.CreateMessageRequest["params"]): Promise<MCP.CreateMessageResult>;
+    /** Handler for `elicitation/create` */
     elicitationRequestHandler?(req: MCP.ElicitRequest["params"]): Promise<MCP.ElicitResult>;
 }
+/**
+ * McpConnectionState is the state of the underlying connection and is
+ * communicated e.g. from the extension host to the renderer.
+ */
 export declare namespace McpConnectionState {
     enum Kind {
         Stopped = 0,
@@ -277,7 +398,9 @@ export declare namespace McpConnectionState {
     }
     const toString: (s: McpConnectionState) => string;
     const toKindString: (s: McpConnectionState.Kind) => string;
+    /** Returns if the MCP state is one where starting a new server is valid */
     const canBeStarted: (s: Kind) => s is Kind.Stopped | Kind.Error;
+    /** Gets whether the state is a running state. */
     const isRunning: (s: McpConnectionState) => boolean;
     interface Stopped {
         readonly state: Kind.Stopped;
@@ -377,6 +500,7 @@ export declare namespace McpResourceURI {
         resourceURL: URL;
     };
 }
+/** Warning: this enum is cached in `mcpServer.ts` and all changes MUST only be additive. */
 export declare enum McpCapability {
     Logging = 1,
     Completions = 2,

package/vscode/src/vs/workbench/contrib/mcp/common/mcpTypes.service.d.ts

@@ -12,13 +12,18 @@ export declare const IMcpService: import("../../../../platform/instantiation/com
 export interface IMcpService {
     _serviceBrand: undefined;
     readonly servers: IObservable<readonly IMcpServer[]>;
+    /** Resets the cached tools. */
     resetCaches(): void;
+    /** Resets trusted MCP servers. */
     resetTrust(): void;
+    /** Set if there are extensions that register MCP servers that have never been activated. */
     readonly lazyCollectionState: IObservable<{
         state: LazyCollectionState;
         collections: McpCollectionDefinition[];
     }>;
+    /** Auto-starts pending servers based on user settings. */
     autostart(token?: CancellationToken): Promise<void>;
+    /** Activatese extensions and runs their MCP servers. */
     activateCollections(): Promise<void>;
 }
 export declare const IMcpWorkbenchService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IMcpWorkbenchService>;
@@ -40,7 +45,9 @@ export interface IMcpWorkbenchService {
 export interface IMcpSamplingService {
     _serviceBrand: undefined;
     sample(opts: ISamplingOptions): Promise<ISamplingResult>;
+    /** Whether MCP sampling logs are available for this server */
     hasLogs(server: IMcpServer): boolean;
+    /** Gets a text report of the MCP server's sampling usage */
     getLogText(server: IMcpServer): string;
     getConfig(server: IMcpServer): IMcpServerSamplingConfiguration;
     updateConfig(server: IMcpServer, mutate: (r: IMcpServerSamplingConfiguration) => unknown): Promise<IMcpServerSamplingConfiguration>;
@@ -48,6 +55,14 @@ export interface IMcpSamplingService {
 export declare const IMcpSamplingService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IMcpSamplingService>;
 export interface IMcpElicitationService {
     _serviceBrand: undefined;
+    /**
+    * Elicits a response from the user. The `context` is optional and can be used
+    * to provide additional information about the request.
+    *
+    * @param context Context for the elicitation, e.g. chat session ID.
+    * @param elicitation Request to elicit a response.
+    * @returns A promise that resolves to an {@link ElicitationResult}.
+    */
     elicit(server: IMcpServer, context: IMcpToolCallContext | undefined, elicitation: MCP.ElicitRequest["params"], token: CancellationToken): Promise<MCP.ElicitResult>;
 }
 export declare const IMcpElicitationService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IMcpElicitationService>;