AGENTS.md · VikashLoomba/copilot-mcp

Sections

1. Engineering Standard
2. Project Shape
3. Build + Run
4. UI Testing Requirements
5. Entry Points
6. View Placement (Current Contract)
7. Directory Map
8. Feature Code Maps
9. RPC Change Checklist
10. Known Gotchas
11. Quick “Where Do I Edit?” Map

First lines (shown under the repo's GPL-3.0 license)

# AGENTS.md

Guidance for coding agents working in this repository. This file focuses on structure and code maps so feature work can be done quickly and safely.

## Engineering Standard
- All changes (workflows, code, tests, docs, and release automation) must follow durable best practices.
- Do not ship temporary hacks, stopgap fixes, or "good for now" implementations.
- Prefer maintainable architecture, deterministic behavior, and clear validation over quick patches.

## Project Shape
- VS Code extension backend: `src/`
- React webview frontend: `web/src/`
- Extension/webview RPC contracts: `src/shared/types/rpcTypes.ts`
- Chat participant (`@mcp`): `src/McpAgent.ts`
- Secondary Side Bar webview + Activity Bar launcher provider/RPC handlers: `src/panels/ExtensionPanel.ts`

## Build + Run
- Install deps (root + web): `npm run install:all`
- Build extension + webview: `npm run build:all`
- Watch mode (extension + web): `npm run watch`
- Lint: `npm run lint`
- Tests: `npm run test`
- Webview unit tests (Vitest): `npm run test:webview`
- Extension UI smoke/E2E harness: `npm run test:ui`
- Combined UI test pass: `npm run test:all-ui`
- Package VSIX: `npm run package-extension`
- CI test workflow: `.github/workflows/tests-on-main.yml` (runs on push/PR to `main`)

Important: the extension webview loads static assets from `web/dist/assets/index.js` and `web/dist/assets/index.css` (see `src/panels/ExtensionPanel.ts`). If you change frontend code, rebuild web assets.
Important (dev Play flow): `.vscode/tasks.json` default `watch` includes `watch:esbuild`, `watch:tsc`, and `watch:webview`. `watch:webview` runs `npm --prefix web run build -- --watch` so `web/dist/assets/*` is regenerated during development.

## UI Testing Requirements
- If you change or add webview UI (`web/src/**`), add or update tests under `web/src/**/*.test.tsx`.
- If you change extension-side UI wiring or view contributions (`src/extension.ts`, `src/panels/**`, related contribution metadata), add or update tests under `src/test/ui/**`.
- Minimum verification for UI-related changes:
  1. `npm run test:webview`
  2. `npm run test:ui`
- Prefer focused smoke tests that verify behavior/contracts over brittle snapshots.
- For regressions, add a test that fails before the fix and passes after it.
- UI copy must describe user value and actions, not internal implementation state.
  - Avoid phrasing like "because X input is empty" or other system-internal explanations.
  - Prefer direct labels/instructions such as "Installed Skills", "Manage...", and "Search above to install...".

## Entry Points
- Extension activation + registrations: `src/extension.ts`
  - Registers webviews: `copilotMcpView` (real UI) and `copilotMcpLauncherView` (launcher)
  - Registers chat participant id: `copilot.mcp-agent`
  - Configures logging + telemetry
- Webview frontend bootstrap: `web/src/main.tsx` -> `web/src/App.tsx` -> `web/src/components/MCPServers.tsx`

## View Placement (Current Contract)
- Real extension UI container: `viewsContainers.secondarySidebar` id `copilotMcpSidebar` in `package.json`.
- Activity Bar icon is a launcher container: `viewsContainers.activitybar` id `copilotMcpLauncher`.
- Launcher view id/type: `copilotMcpLauncherView`; real view id/type: `copilotMcpView`.
- Launcher behavior lives in `src/panels/ExtensionPanel.ts` and should immediately redirect/focus to the secondary container.

## Directory Map
- `src/extension.ts`: extension activation lifecycle.
- `src/panels/ExtensionPanel.ts`: webview backend; most RPC request/notification handling.
- `src/McpAgent.ts`: chat participant command handling (`/search`, `/install`) and README-to-install extraction.
- `src/utilities/repoSearch.ts`: GitHub repository search + README retrieval.
- `src/skills-client.ts`: skills search/list/install orchestration.
- `src/skills.ts`: SKILL.md discovery/parsing/filtering.
- `src/installer.ts`: skill install logic (symlink/copy, canonical paths, global/project scope).
- `src/agents.ts`: supported agent registry + install path detection.
- `src/source-parser.ts`: source string parsing (GitHub/GitLab/local/direct URL/well-known/git).
- `src/shared/types/rpcTypes.ts`: authoritative RPC message contracts.
- `src/telemetry/*` and `src/utilities/outputLogger.ts`: telemetry + output channel logging.
- `web/src/components/*`: sidebar UI and install/search flows.
- `web/src/utils/registryInstall.ts`: Official MCP Registry payload construction for VS Code/Claude/Codex installs.

## Feature Code Maps

### 1) GitHub MCP search (webview tab)
- UI:
  - `web/src/components/SearchMCPServers.tsx`
  - `web/src/components/SearchGitHubServers.tsx`
  - `web/src/components/RepoCard.tsx`
- RPC:
  - request type `searchServersType` in `src/shared/types/rpcTypes.ts`
- Backend:
  - request handler in `src/panels/ExtensionPanel.ts`
  - GitHub API query in `src/utilities/repoSearch.ts` (`searchMcpServers2`)

### 2) AI-assisted install from GitHub README
- UI trigger:
  - Install button in `web/src/components/RepoCard.tsx`
- RPC:
  - request type `aiAssistedSetupType` in `src/shared/types/rpcTypes.ts`
- Backend flow:
  - handler in `src/panels/ExtensionPanel.ts` (`vscodeLMResponse`)
  - README extraction in `src/McpAgent.ts` (`readmeExtractionRequest`)
  - final install URI open in `src/McpAgent.ts` (`openMcpInstallUri`)

### 3) Official MCP Registry search + install
- UI:
  - `web/src/components/SearchRegistryServers.tsx`
  - `web/src/components/RegistryServerCard.tsx`
  - payload builders in `web/src/utils/registryInstall.ts`
- RPC:
  - `registrySearchType`
  - `installFromConfigType`
  - `installClaudeFromConfigType`
  - `installCodexFromConfigType`
- Backend:
  - handlers in `src/panels/ExtensionPanel.ts`
  - VS Code install path -> `openMcpInstallUri`
  - Claude CLI install path -> `runClaudeCliTask`
  - Codex CLI install path -> `runCodexCliTask`

### 4) Installed server management
- UI:
  - `web/src/components/InstalledMCPServers.tsx`
- RPC:
  - `getMcpConfigType`, `updateMcpConfigType`
  - `updateServerEnvVarType`, `deleteServerType`
- Backend:
  - merged server reads from settings + `.vscode/mcp.json` in `src/panels/ExtensionPanel.ts` (`getAllServers`)
  - deletion/update logic in `src/panels/ExtensionPanel.ts`

### 5) Skills search/list/install/manage
- UI:
  - `web/src/components/SearchSkills.tsx`
  - `web/src/components/SkillSearchCard.tsx`
  - `web/src/components/InstalledSkillsList.tsx`
- RPC:
  - `skillsSearchType`
  - `skillsListFromSourceType`
  - `skillsGetAgentsType`
  - `skillsInstallType`
  - `skillsListInstalledType`
  - `skillsUninstallType`
- Backend:
  - orchestrator: `src/skills-client.ts`
  - skill discovery + parsing: `src/skills.ts`
  - install engine: `src/installer.ts`
  - installed-skill list/uninstall handlers: `src/panels/ExtensionPanel.ts`
  - agent capabilities/detection: `src/agents.ts`
  - source parsing + git clone: `src/source-parser.ts`, `src/git.ts`
  - plugin manifest skill discovery: `src/plugin-manifest.ts`

### 6) Chat participant (`@mcp`)
- Registration: `src/extension.ts`
- Handler: `src/McpAgent.ts`
  - `/search`: composed search flow + GitHub tool integration
  - `/install`: README extraction + install URI open

### 7) Telemetry + logging
- Standardized telemetry helpers: `src/telemetry/standardizedTelemetry.ts`
- Event names/types: `src/telemetry/types.ts`
- Telemetry logger wiring: `src/telemetry/index.ts`
- OpenTelemetry sender + export: `src/utilities/signoz.ts`, `src/utilities/logging.ts`
- Human-readable output channel logging: `src/utilities/outputLogger.ts`

## RPC Change Checklist
When adding or changing extension/webview behavior:
1. Update/add message contracts in `src/shared/types/rpcTypes.ts`.
2. Implement extension-side handler in `src/panels/ExtensionPanel.ts`.
3. Wire frontend request/notification in relevant `web/src/components/*`.
4. Ensure payload shapes line up with frontend typed models (often `web/src/types/*`).