john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc updates

Browse Source
This commit is contained in:
John Lancaster
2026-08-30 11:49:58 -05:00
parent bbaa84720c
commit 9eb4ccbc6e
9 changed files with 203 additions and 675 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/personal_mcp/docs/copilot.md
+28 -120
View File
@@ -2,148 +2,56 @@
icon: lucide/bot
---
# Copilot MCP Mechanics
# Using With GitHub Copilot
## Purpose
Once Personal MCP is configured as a VS Code MCP server, Copilot can use its resources, prompts, and read-only tools.
This page explains how GitHub Copilot in VS Code consumes native skill resources and prompts from `personal-mcp`.
For general connection details, see [Using Personal MCP](./usage.md). For VS Code setup options, see [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
## Capability Lanes
## Skills And Documentation
Copilot interacts with MCP servers through independently exposed lanes:
Use **MCP: Browse Resources** to inspect the server's resources. Skills appear as `skill://<name>/SKILL.md`; general pages appear under `resource://docs/...`.
1. tools invoked during execution
2. resources attached as read-only context
3. server-provided prompts
For a task that needs guidance:
This server publishes skills as native `skill://` resources, general docs as `resource://docs/{path*}` resources, and workflows as native MCP prompt objects. It also publishes four compatibility tools generated by FastMCP's resource and prompt transforms, so tool-only chat surfaces can reach the same content without relying on resource or prompt UI support.
1. choose the skill whose description best matches the task
2. read its main `SKILL.md`
3. read `_manifest` only when supporting material is needed
4. attach or read only the relevant supporting files
## VS Code Feature Coverage
When the current chat surface supports MCP resource attachments, the same resources are available from **Add Context**.
The server uses every FastMCP feature that applies to its read-only guidance workload:
## Prompts
| 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 | `list_resources` and `read_resource` expose skills and docs; `list_prompts` and `get_prompt` expose prompt discovery and rendering. All four are generated by FastMCP transforms and delegate to the native server surfaces. |
| 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 explicit `/<server>.<prompt>` invocation in VS Code chat. |
| Argument completion | Prompt arguments with authored `choices` are returned through `completion/complete` as the user types. |
Personal MCP prompts appear as `/<server>.<prompt>` chat commands. Select a command and fill in its arguments to start the workflow. Arguments with a fixed list of choices offer completion as you type.
[FastMCP server identity](https://gofastmcp.com/servers/server), [resource tools](https://gofastmcp.com/servers/transforms/resources-as-tools), [prompt tools](https://gofastmcp.com/servers/transforms/prompts-as-tools), and [argument completion](https://gofastmcp.com/servers/completions) define the implementation details. [VS Code's MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) describes how tools, resources, prompts, and MCP Apps appear in the client.
## Automatic Use
The following capabilities are conditional rather than useful by default:
Copilot can use four fallback tools when the chat surface does not expose resources or prompts directly:
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.
- `list_resources` and `read_resource`
- `list_prompts` and `get_prompt`
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](https://gofastmcp.com/apps/overview), [sampling](https://gofastmcp.com/servers/sampling), [elicitation](https://gofastmcp.com/servers/elicitation), [progress reporting](https://gofastmcp.com/servers/progress), and [MCP context](https://gofastmcp.com/servers/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. browse native resources and compare skill descriptions
2. read one relevant `skill://<name>/SKILL.md`
3. read `_manifest` only if supporting detail may be needed
4. read only selected supporting files
For manual context attachment, browse the server's resources and attach the same bounded set of files.
## Tool Fallbacks
When a chat surface cannot browse or attach MCP resources:
1. Call `list_resources` to see every skill and docs resource, including manifests and supporting-file templates.
2. Call `read_resource` with the exact `uri` (or a filled-in template such as `skill://<name>/<path>`) to fetch content.
When an agent needs to discover or render prompts without explicit slash-command invocation:
1. Call `list_prompts` to get each prompt's name, description, and required or optional arguments.
2. Call `get_prompt` with the prompt `name` and an optional `arguments` object.
3. Treat the returned JSON `messages` array as the rendered workflow context.
These tools route through the same native resource and prompt surfaces, so provider validation, middleware, visibility, and live prompt discovery still apply.
## Prompt Examples
Resource attachment:
These tools access the same content as the native features. A repository instruction can guide Copilot toward the intended order:
```text
Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.
```
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 browse MCP resources and select one `skill://<name>/SKILL.md` by description.
3. Read 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.
1. Prefer an attached skill resource, or browse resources and choose one by description.
2. Read its main file and load supporting material only when needed.
3. Reconcile the guidance with the current repository before editing.
```
Instructions steer behavior but do not force VS Code to attach resources automatically.
## Prompt Objects
Prompts remain separate from skills. VS Code presents native MCP prompts as explicit `/<server>.<prompt>` commands that users select in chat; this is the preferred path for a user intentionally starting a known parameterized workflow. Native prompt argument completion uses the authored choices where available.
The compatibility tools cover the autonomous path: an agent can call `list_prompts`, select a workflow by its description, and call `get_prompt` with matching arguments. `get_prompt` returns the same rendered prompt as JSON containing its ordered MCP messages rather than starting a second chat request itself.
Each authored `PROMPT.md` is the complete source of truth for metadata, arguments, and prose. Both native prompt requests and compatibility-tool calls resolve through the same provider, so changes are loaded on the next request.
Instructions guide resource use but do not force VS Code to attach resources automatically.
## 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 `Add Context > MCP Resources` lists server resources in the active chat surface.
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.
2. Use `MCP: Browse Resources` to confirm resources are available.
3. Restart the MCP server after changing its content.
4. Reload the VS Code window if the server is healthy but the resource or tool list remains stale.
## 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)
1. [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
2. [Managing context in VS Code](https://code.visualstudio.com/docs/chat/copilot-chat-context)
3. [Using Personal MCP](./usage.md)