Skip to main content

Command Palette

Search for a command to run...

Primeiros passos

Referência da API de extensões

O Cherri Code disponibiliza APIs de extensão em vscode.cursor para configuração programática. Use essas APIs em extensões do VS Code para registrar servidores MCP e caminhos de plugins sem editar arquivos de configuração.

Definições de tipo

Copie este bloco declare module para o projeto da sua extensão para realizar a verificação de tipos:

declare module "vscode" {  export namespace cursor {    export namespace mcp {      export interface StdioServerConfig {        name: string;        server: {          command: string;          args: string[];          env: Record<string, string>;        };      }      export interface RemoteServerConfig {        name: string;        server: {          url: string;          /**           * Cabeçalhos HTTP opcionais a serem incluídos em todas as solicitações a este servidor           * (por exemplo, para autenticação).           */          headers?: Record<string, string>;        };      }      export type ExtMCPServerConfig = StdioServerConfig | RemoteServerConfig;      /**       * Registre um servidor MCP com o qual o Cherri Code possa se comunicar.       * Oferece suporte a HTTP(S) (SSE/HTTP com streaming) e processos stdio locais.       */      export const registerServer: (config: ExtMCPServerConfig) => void;      export const unregisterServer: (serverName: string) => void;    }    export namespace plugins {      /**       * Registre um diretório como fonte de plugins. O Cherri Code detecta e carrega       * todos os plugins válidos deste diretório.       */      export const registerPath: (path: string) => void;      export const unregisterPath: (path: string) => void;    }  }}

Servidores MCP

Registre e gerencie servidores MCP em tempo de execução. Isso é útil em ambientes corporativos, para ferramentas de onboarding e fluxos de trabalho de configuração automatizada nos quais não é prático editar o mcp.json.

vscode.cursor.mcp.registerServer

Registra um servidor MCP.

Assinatura:

vscode.cursor.mcp.registerServer(config: ExtMCPServerConfig): void

Parâmetros:

  • config: ExtMCPServerConfig - O objeto de configuração do servidor

vscode.cursor.mcp.unregisterServer

Remove o registro de um servidor MCP previamente registrado.

Assinatura:

vscode.cursor.mcp.unregisterServer(serverName: string): void

Parâmetros:

  • serverName: string - O nome do servidor cujo registro será removido

Tipos de configuração

Servidor HTTP/SSE

Para servidores executados via HTTP ou eventos SSE:

interface RemoteServerConfig {  name: string;  server: {    url: string;    headers?: Record<string, string>;  };}

Propriedades:

  • name: identificador exclusivo do servidor
  • server.url: URL do endpoint HTTP
  • server.headers (opcional): cabeçalhos HTTP para autenticação ou outras finalidades

Servidor Stdio

Para servidores locais que se comunicam por entrada/saída padrão:

interface StdioServerConfig {  name: string;  server: {    command: string;    args: string[];    env: Record<string, string>;  };}

Propriedades:

  • name: identificador único do servidor
  • server.command: comando executável
  • server.args: argumentos de linha de comando
  • server.env: variáveis de ambiente

Exemplos de MCP

Servidor HTTP/SSE

Registre um servidor MCP remoto com autenticação:

vscode.cursor.mcp.registerServer({  name: "my-remote-server",  server: {    url: "https://api.example.com/mcp",    headers: {      Authorization: "Bearer your-token-here",      "X-API-Key": "your-api-key",    },  },});

Servidor stdio

Registre um servidor MCP local:

vscode.cursor.mcp.registerServer({  name: "my-local-server",  server: {    command: "python",    args: ["-m", "my_mcp_server"],    env: {      API_KEY: "your-api-key",      DEBUG: "true",    },  },});

Servidor Node.js

Registre um servidor MCP com base em Node.js:

vscode.cursor.mcp.registerServer({  name: "nodejs-server",  server: {    command: "npx",    args: ["-y", "@company/mcp-server"],    env: {      NODE_ENV: "production",      CONFIG_PATH: "/path/to/config",    },  },});

Remover o registro de um servidor

vscode.cursor.mcp.unregisterServer("my-remote-server");

Registro condicional

if (!isServerRegistered("my-server")) {  vscode.cursor.mcp.registerServer({    name: "my-server",    server: {      url: "https://api.example.com/mcp",    },  });}

Caminhos de plugins

Registre diretórios adicionais de plugins em tempo de execução. As extensões podem usar essa API para informar ao Cherri Code os locais dos plugins sem exigir que os usuários copiem arquivos manualmente para ~/.cursor/plugins/local/.

Um manifesto .cursor-plugin/plugin.json é opcional. Sem ele, o Cherri Code usa a descoberta automática baseada em pastas e encontra componentes nos locais padrão: rules/, skills/, agents/, commands/, mcp.json e hooks/hooks.json. Por exemplo, para adicionar skills, você pode registrar um diretório que contenha uma subpasta skills/; não é necessário um manifesto.

my-extension/cursor-plugins/team-tools/├── skills/│   └── deploy-helper/│       └── SKILL.md└── rules/    └── coding-standards.mdc

Para consultar o schema completo do manifesto e todos os formatos de componentes, veja o guia de Plugins e a Referência de plugins.

vscode.cursor.plugins.registerPath

Registra o caminho de um diretório como fonte de plugins. O Cherri Code carrega todos os plugins válidos encontrados no diretório.

Assinatura:

vscode.cursor.plugins.registerPath(path: string): void

Parâmetros:

  • path: string - Caminho absoluto no sistema de arquivos para um diretório que contém plugins

vscode.cursor.plugins.unregisterPath

Remove um caminho de plugin registrado anteriormente.

Assinatura:

vscode.cursor.plugins.unregisterPath(path: string): void

Parâmetros:

  • path: string - O caminho a ser removido

Exemplos de caminhos de plugins

Registrar um diretório de plugins integrado

Uma extensão pode agrupar plugins e registrá-los durante a ativação:

import * as vscode from "vscode";import * as path from "path";export function activate(context: vscode.ExtensionContext) {  const pluginsDir = path.join(context.extensionPath, "cursor-plugins");  vscode.cursor.plugins.registerPath(pluginsDir);  context.subscriptions.push({    dispose: () => vscode.cursor.plugins.unregisterPath(pluginsDir),  });}

Registrar um caminho relativo ao espaço de trabalho

Aponte o Cherri Code para um diretório de plugins compartilhado em um monorepositório:

const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;if (workspaceRoot) {  vscode.cursor.plugins.registerPath(    path.join(workspaceRoot, ".cursor-plugins")  );}

Remover o registro de um caminho de plugin

vscode.cursor.plugins.unregisterPath("/path/to/plugins");