prompts/src/personal_mcp/docs/copilot.md

icon

icon
lucide/bot

Copilot MCP Mechanics

Purpose

This page explains how GitHub Copilot in VS Code consumes native skill resources and prompts from personal-mcp.

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 and prompts as native MCP prompt objects. It also exposes search_skills, list_resources, and read_resource tools for agents whose tool catalog does not include direct MCP resource operations.

VS Code Feature Coverage

The server uses every FastMCP feature that applies to its read-only guidance workload:

Feature	Usage
Server identity	The initialize response includes a stable name, usage instructions, and a self-contained icon for VS Code's MCP server UI.
Tools	Compatibility tools have display titles, structured output schemas, and read-only, idempotent, closed-world annotations. FastMCP's default schema dereferencing remains enabled for clients such as VS Code that require flat schemas.
Resources	Documentation and skills use native resources and wildcard resource templates with explicit Markdown MIME types.
Prompts	Declarative workflows use native prompt objects with descriptions, display titles, typed arguments, and slash-command access.
Argument completion	Prompt arguments with authored choices are returned through completion/complete as the user types.

FastMCP server identity, component icons, tool metadata, and argument completion define the implementation details. VS Code's MCP documentation describes how tools, resources, prompts, and MCP Apps appear in the client.

The following capabilities are conditional rather than useful by default:

1. MCP Apps require an interactive tool result such as a form or visualization; this server returns guidance and structured resource data only.
2. Sampling is appropriate only when server-side work must ask VS Code to run an LLM. The current server retrieves authored content and does not generate it.
3. Elicitation is appropriate only when a running operation needs additional user input. Prompt arguments already collect all required input before execution.
4. Progress, client logging, and background tasks require long-running operations. Current reads and prompt rendering are bounded local operations.
5. Client roots matter only when server behavior depends on client filesystem roots. This server reads packaged content and never traverses a client workspace.
6. website_url requires a canonical public deployment URL. None is configured, so the server does not advertise a guessed address.

Add one of these capabilities when a concrete workflow needs it, then cover its negotiated capability and protocol response in the HTTP MCP smoke tests. See the FastMCP Apps overview, sampling, elicitation, progress reporting, and MCP context for the activation criteria.

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. Native resources remain the only skill content and discovery contract; the tools search or delegate to that same resource surface rather than maintaining a parallel 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

For autonomous agents:

1. call search_skills with the task, capability, or technology
2. compare the bounded main-skill matches
3. call read_resource for one relevant skill://<name>/SKILL.md
4. read _manifest only if supporting detail may be needed
5. read only selected supporting files

For manual context attachment, browse the server's resources and attach the same bounded set of files.

Prompt Examples

Resource attachment:

Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.

Direct loading:

Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.

Supporting material:

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:

When a task matches a personal-mcp skill:

1. Prefer an already attached native skill resource.
2. Otherwise call `search_skills` and select one `skill://<name>/SKILL.md` result by description.
3. Call `read_resource` for the selected skill and 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. The generic tools provide an agent-callable fallback when direct resource operations are absent from the deferred-tool catalog.

Prompt Objects

Prompts remain separate from skills. When the client supports MCP prompt APIs, use prompt listing and get_prompt for parameterized workflows. Each authored PROMPT.md is the complete source of truth for its metadata, arguments, and prose; changes are loaded on the next prompt request.

Troubleshooting

1. Use MCP: List Servers to confirm the server is enabled.
2. Use MCP: Browse Resources to confirm native skill resources exist.
3. Confirm search_skills and read_resource appear in the chat tool picker when autonomous retrieval is required.
4. Restart the MCP server after changing skill files because production uses reload=False.
5. Reload the VS Code window if the server is healthy but the resource or tool picker remains stale.

Further Reading

1. FastMCP Skills Provider
2. Add and manage MCP servers
3. MCP configuration reference
4. Manage context for AI
5. Skill Usage Mechanics