119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
---
|
|
icon: lucide/bot
|
|
---
|
|
|
|
# Copilot MCP Mechanics
|
|
|
|
## Purpose
|
|
|
|
This page explains how GitHub Copilot in VS Code consumes native skill resources from `personal-mcp`, including sessions where tools are visible but resource attachment is not.
|
|
|
|
## Capability Lanes
|
|
|
|
Copilot interacts with MCP servers through independently exposed lanes:
|
|
|
|
1. tools invoked during execution
|
|
2. resources attached as read-only context
|
|
3. server-provided prompts
|
|
|
|
This server publishes skills as native `skill://` resources, prompts through registry-backed resources and MCP prompt objects, and generic resource fallback tools through FastMCP.
|
|
|
|
## Native Skill Resources
|
|
|
|
For every skill, Copilot can discover:
|
|
|
|
1. `skill://<name>/SKILL.md`
|
|
2. `skill://<name>/_manifest`
|
|
3. `skill://<name>/{path*}` supporting-file template
|
|
|
|
The main resource description comes from `SKILL.md`. The manifest discloses supporting paths, sizes, and SHA256 hashes. This is the only skill discovery contract; there is no parallel skill catalog.
|
|
|
|
## Resource Picker Availability
|
|
|
|
`MCP Resources...` in Add Context requires both:
|
|
|
|
1. a connected server advertising resource capability
|
|
2. a chat surface that exposes MCP resource attachment
|
|
|
|
A successful `resources/list` response does not guarantee the picker appears in every session type. Use `MCP: Browse Resources` to distinguish server availability from chat UI availability.
|
|
|
|
## Recommended Workflow
|
|
|
|
When resource attachment is available:
|
|
|
|
1. browse the server's resources
|
|
2. attach one relevant `skill://<name>/SKILL.md`
|
|
3. attach `_manifest` only if supporting detail may be needed
|
|
4. attach only selected supporting files
|
|
|
|
When only tools are available:
|
|
|
|
1. call `list_resources`
|
|
2. select a native main skill URI by name and description
|
|
3. call `read_resource` for that URI
|
|
4. read `_manifest` and supporting files only as needed
|
|
|
|
Both paths resolve through the same FastMCP provider.
|
|
|
|
## Prompt Examples
|
|
|
|
Resource attachment:
|
|
|
|
```text
|
|
Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.
|
|
```
|
|
|
|
Tool-only discovery:
|
|
|
|
```text
|
|
Call list_resources, choose the best matching skill://.../SKILL.md resource, and read it. Inspect its _manifest only if a supporting file is needed. Load at most two candidate skills.
|
|
```
|
|
|
|
Direct loading:
|
|
|
|
```text
|
|
Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.
|
|
```
|
|
|
|
Supporting material:
|
|
|
|
```text
|
|
Read skill://pytesting/_manifest, select the one reference relevant to async test lifecycle, and use that file with the main skill instructions.
|
|
```
|
|
|
|
## Repository Instruction Pattern
|
|
|
|
A repo-level instruction should name the native retrieval order and context budget:
|
|
|
|
```md
|
|
When a task matches a personal-mcp skill:
|
|
|
|
1. Prefer an already attached native skill resource.
|
|
2. Otherwise use `list_resources` and select one `skill://<name>/SKILL.md` resource by description.
|
|
3. Read `_manifest` only when supporting material is needed.
|
|
4. Load at most two candidate main files and only the relevant supporting paths.
|
|
5. Reconcile guidance with the current repository before editing.
|
|
```
|
|
|
|
Instructions steer behavior but do not force VS Code to attach resources automatically.
|
|
|
|
## Prompt Objects
|
|
|
|
Prompt modules remain separate from skills. When the client supports MCP prompt APIs, use prompt listing and `get_prompt` for parameterized workflows. Authored `PROMPT.md` remains the source of truth for each prompt.
|
|
|
|
## Troubleshooting
|
|
|
|
1. Use `MCP: List Servers` to confirm the server is enabled.
|
|
2. Use `MCP: Browse Resources` to confirm native skill resources exist.
|
|
3. Restart the MCP server after changing skill files because production uses `reload=False`.
|
|
4. Reload the VS Code window if the server is healthy but the resource picker remains stale.
|
|
5. In tool-only sessions, verify `list_resources` and `read_resource` are visible.
|
|
|
|
## Further Reading
|
|
|
|
1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
|
|
2. [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
|
3. [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
|
|
4. [Manage context for AI](https://code.visualstudio.com/docs/chat/copilot-chat-context)
|
|
5. [Skill Usage Mechanics](./usage.md)
|