Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 John Lancaster
|
406fd63a07 | ||
|
John Lancaster
|
323f02102d | ||
|
John Lancaster
|
906bba427b | ||
|
John Lancaster
|
06d5fc18f2 | ||
|
John Lancaster
|
38edc4ac36 | ||
|
John Lancaster
|
c73771c2f4 | ||
|
John Lancaster
|
33144da02f | ||
|
John Lancaster
|
0a9dadd5a8 |
@@ -8,7 +8,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
|
||||
3. Phase 1: Define URI contract with explicit break-and-replace policy. Recommend resource://catalog/skills_index, resource://catalog/skills/{skill_id}, resource://skills/{skill_id}/document, resource://skills/{skill_id}/references/{ref_id}, and resource://docs/{path*}. Evolving URIs and reference ids requires direct replacement, with no aliases or compatibility shims. Depends on steps 1-2. Deliverable: update the current docs/ directory with the finalized URI contract and break-and-replace policy from this step.
|
||||
4. Phase 2: Build a docs registry loader that reads packaged docs via importlib.resources.files(...) Traversable APIs, parses SKILL.md frontmatter, validates schema, and creates an in-memory registry keyed by skill_id. Fail fast for duplicate ids, missing files, broken reference mappings, or invalid depends_on. Depends on steps 2-3.
|
||||
5. Phase 2: Register FastMCP resources from the registry using RFC6570 templates (including wildcard paths where appropriate), read-only/idempotent annotations, explicit mime types, and on_duplicate_resources="error" for startup safety. Depends on step 4.
|
||||
6. Phase 2: Add discovery surfaces as resources first, then tool fallback. Keep catalog discovery in resources, then add ResourcesAsTools for tool-only clients. Add thin discovery tools only for parity and optional BM25/regex tool search when catalog/tool volume grows enough to affect token efficiency. Depends on step 5.
|
||||
6. Phase 2: Add discovery surfaces as resources first, then tool fallback. Keep catalog discovery in resources, then add ResourcesAsTools for tool-only clients. Add thin discovery tools only for parity and optional BM25/regex tool search when catalog/tool volume grows enough to affect token efficiency. Define canonical fallback tool names (`list_resources`, `read_resource`, `search_patterns`, `get_pattern_by_id`, `get_skill_document_by_id`), research host-specific naming behavior for GitHub Copilot, Cursor, Claude Desktop, and generic MCP clients, and require client-side name mapping or intentionally documented aliases when providers expose namespaced wrappers. Depends on step 5.
|
||||
7. Phase 3: Implement packaging so docs/ is copied into package resource space at build time (wheel + sdist) while docs/ remains canonical in source control. Use importlib.resources at runtime only; avoid direct filesystem assumptions. Depends on steps 4-6.
|
||||
8. Phase 3: Remove materialization coupling between skill source modules and docs. The website build reads docs/ directly, while MCP reads packaged docs resources from the installed package. This preserves one authored source with two distribution surfaces. Depends on step 7.
|
||||
9. Phase 4: Add validation and CI gates: frontmatter schema checks, URI uniqueness checks, reference integrity checks, docs build check, package content check, and stdio smoke checks that read representative skill/document resources from an installed wheel. Depends on steps 5-8.
|
||||
@@ -31,7 +31,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
|
||||
2. Run uv run pytest -q with tests that validate frontmatter parsing, URI generation, reference mapping, and catalog responses.
|
||||
3. Run a packaging integrity check using importlib.resources.files(...) to confirm packaged docs resources exist and are readable from an installed wheel.
|
||||
4. Run a stdio MCP smoke test that lists resources and reads at least one skill document and one reference document.
|
||||
5. Run fallback-client smoke tests verifying list_resources/read_resource tools work and return expected metadata for both static and templated resources.
|
||||
5. Run fallback-client smoke tests verifying list_resources/read_resource tools work and return expected metadata for both static and templated resources, and that GitHub Copilot, Cursor, Claude Desktop, and protocol-level SDK tests use canonical tool names or documented mapped aliases.
|
||||
|
||||
**Decisions**
|
||||
- Anthropic compatibility: strict skill directory pattern with SKILL.md and references subtree.
|
||||
|
||||
@@ -23,6 +23,41 @@ Normative conclusions from those sources:
|
||||
3. Resources and tools must resolve to the same canonical authored markdown.
|
||||
4. Fallback behavior should keep context bounded and deterministic.
|
||||
|
||||
### FastMCP Source Baseline (Authoritative References)
|
||||
|
||||
Step 6 fallback behavior and compatibility-layer expectations align with:
|
||||
|
||||
1. [FastMCP server concepts](https://gofastmcp.com/servers/server)
|
||||
2. [FastMCP resources and resource templates](https://gofastmcp.com/servers/resources)
|
||||
3. [FastMCP resources-as-tools transform](https://gofastmcp.com/servers/transforms/resources-as-tools)
|
||||
4. [MCP specification: resources](https://modelcontextprotocol.io/specification/latest/server/resources)
|
||||
|
||||
Applied conclusions for this step:
|
||||
|
||||
1. Resource contracts remain canonical and should be surfaced directly when clients support resource attachment.
|
||||
2. Tool-first compatibility layers should wrap canonical resource reads rather than creating alternate authored-content stores.
|
||||
3. URI-template-backed resource identity remains stable across direct-resource and tool-compatibility access paths.
|
||||
|
||||
### Client Tool-Naming Research Baseline
|
||||
|
||||
Authoritative and client-specific references to verify during implementation:
|
||||
|
||||
1. [MCP specification: tools](https://modelcontextprotocol.io/specification/latest/server/tools)
|
||||
2. [MCP client concepts](https://modelcontextprotocol.io/docs/learn/client-concepts)
|
||||
3. [FastMCP tools](https://gofastmcp.com/servers/tools)
|
||||
4. [FastMCP resources-as-tools transform](https://gofastmcp.com/servers/transforms/resources-as-tools)
|
||||
5. [VS Code MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
||||
6. [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
|
||||
7. [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol)
|
||||
8. [Claude Desktop local MCP server setup](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
|
||||
|
||||
Baseline naming conclusions:
|
||||
|
||||
1. MCP protocol tool identity is the server-advertised `name` returned by `tools/list` and used in `tools/call`.
|
||||
2. FastMCP tool identity should be treated as the canonical server contract unless a tool is intentionally registered with an explicit alternate name.
|
||||
3. Clients and host integrations may display, namespace, or internally route tool names with provider-specific prefixes, but those wrappers are not canonical server tool names.
|
||||
4. Compatibility should be validated by observed `tools/list` and successful `tools/call` behavior in each target client rather than by assuming one global host naming convention.
|
||||
|
||||
### Discovery Priority Contract (Normative)
|
||||
|
||||
Preferred sequence for skill discovery and loading:
|
||||
@@ -58,6 +93,19 @@ The fallback tool surface includes:
|
||||
4. `get_pattern_by_id`
|
||||
5. `get_skill_document_by_id`
|
||||
|
||||
Canonical naming rule:
|
||||
|
||||
1. The server-level tool contract uses the exact registered FastMCP tool names above.
|
||||
2. Clients that expose provider-prefixed names (for example, namespaced wrappers) must map those names to the canonical server tool name before invocation.
|
||||
3. `catalog_get_skill_document_by_id` is not a canonical server tool name for this contract unless an explicit alias is intentionally registered.
|
||||
|
||||
Compatibility alias policy:
|
||||
|
||||
1. Prefer canonical server tool names over aliases.
|
||||
2. Add server-side aliases only when a major client cannot reliably map its wrapper name back to the canonical name.
|
||||
3. Any alias must be read-only, delegate to the same payload builder as the canonical tool, and be documented as compatibility-only.
|
||||
4. If aliases are added, canonical and alias tools must return byte-for-byte equivalent payloads for the same input.
|
||||
|
||||
Fallback order:
|
||||
|
||||
1. call `list_resources` to inspect canonical static/template resource surfaces
|
||||
@@ -70,6 +118,40 @@ Tool behavior requirements:
|
||||
2. deterministic ordering and bounded pagination
|
||||
3. explicit not-found responses (`found: false` style) where applicable
|
||||
4. payloads remain schema-aligned with catalog resources
|
||||
5. tool invocation examples and Copilot guidance must use canonical server tool names to avoid unknown-tool errors
|
||||
|
||||
### Major Client Compatibility Plan
|
||||
|
||||
Target clients and expected validation:
|
||||
|
||||
1. GitHub Copilot in VS Code
|
||||
- primary path: attach MCP resources when `MCP Resources...` is available
|
||||
- fallback path: call `list_resources`, `read_resource`, then canonical thin tools only when needed
|
||||
- validation: confirm Copilot-visible tool inventory includes or can invoke `list_resources`, `read_resource`, `search_patterns`, `get_pattern_by_id`, and `get_skill_document_by_id`
|
||||
- compatibility risk: host-generated wrapper names may differ from canonical FastMCP names; document any observed wrapper-to-canonical mapping
|
||||
2. Cursor
|
||||
- primary path: use the client MCP server configuration and resource/tool surfaces supported by the active Cursor version
|
||||
- fallback path: prefer resource-backed tools first, then canonical thin tools
|
||||
- validation: capture Cursor `tools/list` equivalent behavior and verify the canonical tool names or required host mappings
|
||||
- compatibility risk: Cursor may present MCP tools through its own UI labels or internal routing names
|
||||
3. Claude Desktop
|
||||
- primary path: configure the local MCP server and inspect advertised tools/resources in Claude Desktop
|
||||
- fallback path: invoke canonical server tool names exactly as returned by `tools/list`
|
||||
- validation: run a local smoke prompt that reads `resource://catalog/skills_index` and loads one skill document through `read_resource` or `get_skill_document_by_id`
|
||||
- compatibility risk: local server configuration and transport setup may fail before tool-name compatibility is tested
|
||||
4. Generic MCP clients and SDK-based tests
|
||||
- primary path: protocol-level `resources/list`, `resources/read`, `tools/list`, and `tools/call`
|
||||
- fallback path: none beyond the canonical tool contract
|
||||
- validation: automated smoke tests assert exact tool names returned by `tools/list` and successful calls for canonical names
|
||||
- compatibility risk: SDK/client libraries may expose helper names that differ from raw protocol names
|
||||
|
||||
Implementation checklist:
|
||||
|
||||
1. Capture each target client's advertised tool names before adding aliases.
|
||||
2. Prefer fixing documentation or client-side mapping when the server already advertises canonical names correctly.
|
||||
3. Add a server-side alias only for a confirmed major-client incompatibility.
|
||||
4. Add regression tests for canonical names, resource-backed tools, and any intentionally supported aliases.
|
||||
5. Keep public examples centered on `list_resources`/`read_resource` and canonical thin tool names.
|
||||
|
||||
### Resources-As-Tools Compatibility Layer
|
||||
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
name: New Skill Bootstrap
|
||||
description: Create and fully implement a new docs-first skill in this repository.
|
||||
argument-hint: skill-id and goal for the new skill
|
||||
agent: agent
|
||||
---
|
||||
|
||||
# New Skill Bootstrap
|
||||
|
||||
Use the canonical bootstrap guidance in [docs/skills/new-skill/SKILL.md](../../docs/skills/new-skill/SKILL.md).
|
||||
|
||||
If the request is to create or implement a new skill, load that skill document and follow it as the source of truth.
|
||||
@@ -124,7 +124,7 @@ Repository indexing metadata is declared in `x-personal-mcp`:
|
||||
3. tags
|
||||
4. capabilities
|
||||
5. depends_on
|
||||
6. references map (ref id to relative path and optional metadata)
|
||||
6. optional references map (for nested entries, overrides, and aliases)
|
||||
|
||||
No `metadata.yaml` sidecar is part of the end-state contract.
|
||||
|
||||
@@ -143,7 +143,9 @@ For the full URI semantics, parameter validation rules, and compatibility policy
|
||||
Validation rules:
|
||||
|
||||
1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract.
|
||||
2. `ref_id` is lowercase kebab-case and must be declared in the skill references manifest.
|
||||
2. `ref_id` is lowercase kebab-case and must resolve from either:
|
||||
- top-level auto-discovery of `references/*.md` filename stems, or
|
||||
- an explicit `x-personal-mcp.references` entry.
|
||||
3. `path*` resolves only to normalized markdown paths under `docs/`.
|
||||
|
||||
### Resource Registration Contract
|
||||
|
||||
+1
-1
@@ -43,7 +43,7 @@ Rules:
|
||||
|
||||
1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
|
||||
2. No `metadata.yaml` sidecar exists in the end state.
|
||||
3. Reference lookup metadata, including reference id to relative path mappings, is declared from `SKILL.md` frontmatter rather than inferred as a hidden global convention.
|
||||
3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed.
|
||||
|
||||
## Skill Id Contract
|
||||
|
||||
|
||||
@@ -69,6 +69,15 @@ When resource attachment is unavailable in the active session, use ResourcesAsTo
|
||||
4. `get_pattern_by_id`
|
||||
5. `get_skill_document_by_id`
|
||||
|
||||
Canonical naming policy:
|
||||
|
||||
1. Prefer the five canonical tool names above in prompts and instructions.
|
||||
2. For compatibility with clients that emit `catalog_*` naming, the server also exposes:
|
||||
- `catalog_search_patterns`
|
||||
- `catalog_get_pattern_by_id`
|
||||
- `catalog_get_skill_document_by_id`
|
||||
3. Canonical and compatibility alias tools return equivalent payloads for the same input.
|
||||
|
||||
The first two are generated from the canonical resource surface and should be preferred in tool-only clients.
|
||||
|
||||
These should stay read-only, minimal, and schema-aligned with catalog resources.
|
||||
|
||||
@@ -107,6 +107,28 @@ Reference entry rules:
|
||||
6. `title` is an optional display label.
|
||||
7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
|
||||
|
||||
## Auto-Generated Reference IDs
|
||||
|
||||
Top-level markdown files directly under `references/` are auto-registered as MCP references even when `x-personal-mcp.references` is empty.
|
||||
|
||||
How `ref-id` is derived:
|
||||
|
||||
1. Start from the filename stem (without `.md`).
|
||||
2. Normalize to lowercase kebab-case.
|
||||
3. Publish at `resource://skills/<skill-id>/references/<ref-id>`.
|
||||
|
||||
Examples:
|
||||
|
||||
1. `references/ruff-docs.md` -> `ref-id: ruff-docs`
|
||||
2. `references/Ruff Integrations.md` -> `ref-id: ruff-integrations`
|
||||
3. `references/python_logging_docs.md` -> `ref-id: python-logging-docs`
|
||||
|
||||
When to use explicit `x-personal-mcp.references` entries:
|
||||
|
||||
1. The file is nested, for example `references/guides/ci.md`.
|
||||
2. You need to override defaults (`title`, `mime_type`, or custom `ref-id`).
|
||||
3. You need compatibility aliases during a rename.
|
||||
|
||||
## Validation Models
|
||||
|
||||
The normative model uses Pydantic v2 with change-friendly validation:
|
||||
|
||||
@@ -1,129 +0,0 @@
|
||||
---
|
||||
icon: lucide/file-plus
|
||||
---
|
||||
|
||||
# Hooking Up a New Skill
|
||||
|
||||
Use this checklist to add a new skill in the docs-first model.
|
||||
|
||||
For the full contract details, see [Content Contract](./content.md), [Frontmatter Contract](./frontmatter.md), and [URI Contract](./uris.md).
|
||||
|
||||
## Canonical Skill Shape
|
||||
|
||||
Create one skill directory under `docs/skills/`:
|
||||
|
||||
```text
|
||||
docs/
|
||||
skills/
|
||||
<skill-id>/
|
||||
SKILL.md
|
||||
references/
|
||||
... (optional markdown files, nested folders allowed)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `SKILL.md` is required.
|
||||
2. All skill-specific supporting docs live under `references/`.
|
||||
3. Skill directories are ownership boundaries; no cross-skill writes.
|
||||
4. `skill-id` is lowercase kebab-case and should remain stable.
|
||||
|
||||
## SKILL.md Frontmatter
|
||||
|
||||
`SKILL.md` frontmatter is authoritative for metadata.
|
||||
|
||||
Required top-level fields:
|
||||
|
||||
1. `name`
|
||||
2. `description`
|
||||
3. `x-personal-mcp`
|
||||
|
||||
Required `x-personal-mcp` fields:
|
||||
|
||||
1. `id`
|
||||
2. `version`
|
||||
3. `capabilities`
|
||||
|
||||
Optional `x-personal-mcp` fields:
|
||||
|
||||
1. `tags`
|
||||
2. `depends_on`
|
||||
3. `references`
|
||||
|
||||
Canonical frontmatter template:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-id>
|
||||
description: <what this skill does and when to use it>
|
||||
|
||||
x-personal-mcp:
|
||||
id: <skill-id>
|
||||
version: 1.0.0
|
||||
tags: []
|
||||
capabilities:
|
||||
- resource://skills/<skill-id>/document
|
||||
depends_on: []
|
||||
# Optional: only for nested references or metadata overrides.
|
||||
references:
|
||||
<ref-id>:
|
||||
path: references/<file>.md
|
||||
mime_type: text/markdown
|
||||
title: <optional short title>
|
||||
---
|
||||
```
|
||||
|
||||
Reference manifest rules:
|
||||
|
||||
1. `ref-id` is lowercase kebab-case.
|
||||
2. `path` is skill-relative and must stay under `references/`.
|
||||
3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
|
||||
4. Nested `references/**` markdown files must be declared explicitly.
|
||||
5. Reference paths are markdown files.
|
||||
|
||||
No `metadata.yaml` sidecar is part of this model.
|
||||
|
||||
## URI Surface
|
||||
|
||||
Canonical resource URIs for a skill:
|
||||
|
||||
1. `resource://skills/<skill_id>/document`
|
||||
2. `resource://skills/<skill_id>/references/<ref_id>`
|
||||
|
||||
Canonical discovery URIs:
|
||||
|
||||
1. `resource://catalog/skills_index`
|
||||
2. `resource://catalog/skills/{skill_id}`
|
||||
|
||||
Docs passthrough URI:
|
||||
|
||||
1. `resource://docs/{path*}`
|
||||
|
||||
Compatibility rule:
|
||||
|
||||
1. Keep URI families unversioned by default.
|
||||
2. For breaking changes, update clients to the canonical replacement URIs directly.
|
||||
|
||||
## Checklist
|
||||
|
||||
1. Create `docs/skills/<skill-id>/SKILL.md`.
|
||||
2. Add optional references under `docs/skills/<skill-id>/references/`.
|
||||
3. Populate frontmatter with `name`, `description`, and `x-personal-mcp` metadata.
|
||||
4. Ensure `x-personal-mcp.id` equals `name` and directory `<skill-id>`.
|
||||
5. Ensure `capabilities` includes `resource://skills/<skill-id>/document`.
|
||||
6. Add supporting docs under `references/`; top-level markdown files are exposed automatically.
|
||||
7. Declare `x-personal-mcp.references` only for nested paths or to override defaults.
|
||||
|
||||
## Quick Validation
|
||||
|
||||
1. Confirm docs build succeeds:
|
||||
|
||||
```bash
|
||||
uv run zensical build
|
||||
```
|
||||
|
||||
2. Confirm tests succeed:
|
||||
|
||||
```bash
|
||||
uv run pytest -q
|
||||
```
|
||||
@@ -30,7 +30,12 @@ Use this skill when a task is about changing how GitHub Copilot or VS Code agent
|
||||
|
||||
## When to Use
|
||||
|
||||
- Creating or updating `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or `*.instructions.md` files.
|
||||
- Creating or updating:
|
||||
- `.github/copilot-instructions.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `*.instructions.md` files
|
||||
- `*.prompt.md` files
|
||||
- Creating prompt files, custom agents, hooks, or Agent Skills.
|
||||
- Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
|
||||
- Debugging why a customization is not discovered, loaded, or invoked.
|
||||
@@ -55,6 +60,60 @@ If the request is ambiguous, ask only for the missing axis that changes the file
|
||||
|
||||
Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.
|
||||
|
||||
## Repo Shim Pattern For Personal MCP
|
||||
|
||||
Use a shim when you want another repository to consume this server as a preference and documentation source without duplicating methodology content.
|
||||
|
||||
### What the shim does
|
||||
|
||||
1. Tells the agent when to consult this MCP server.
|
||||
2. Tells the agent how to retrieve relevant guidance.
|
||||
3. Keeps repo-local behavior thin while canonical guidance stays in Personal MCP resources.
|
||||
|
||||
### Shim formats
|
||||
|
||||
Use either:
|
||||
|
||||
1. A repo instruction file (`*.instructions.md`) for always-on or file-scoped behavior.
|
||||
2. A prompt file (`*.prompt.md`) for explicit, on-demand guidance retrieval.
|
||||
|
||||
### Retrieval strategies
|
||||
|
||||
Choose one of these patterns:
|
||||
|
||||
1. Direct URI strategy:
|
||||
- Reference known resources directly, such as:
|
||||
- `resource://catalog/skills_index`
|
||||
- `resource://catalog/skills/{skill_id}`
|
||||
- `resource://skills/<skill-id>/document`
|
||||
- `resource://skills/<skill-id>/references/<ref-id>`
|
||||
2. Discovery-first strategy:
|
||||
- Start at catalog discovery (`resource://catalog/skills_index`), select the best skill match, then load the skill document and only the minimal references needed.
|
||||
|
||||
### Authoring guidance for shims
|
||||
|
||||
1. Keep shim content short and procedural; avoid copying large guidance blocks from Personal MCP.
|
||||
2. State trigger conditions clearly (for example: "when creating a new skill" or "when editing docs contracts").
|
||||
3. Specify whether to use direct URIs or discovery for that repo's common workflows.
|
||||
4. Prefer loading only the most relevant skill document first; expand to references only when needed.
|
||||
5. For stable repeated workflows, use explicit URIs. For broader or ambiguous requests, use discovery-first.
|
||||
|
||||
### Minimal shim examples
|
||||
|
||||
Instruction-style shim intent:
|
||||
|
||||
1. "For markdown edits (`applyTo: '**/*.md'`), load `resource://skills/zensical-docs/document` and apply Zensical-native documentation conventions unless they conflict with expected MkDocs compatibility."
|
||||
|
||||
Prompt-style shim intent:
|
||||
|
||||
1. "For docs authoring tasks, consult `resource://skills/zensical-docs/document`, summarize the relevant authoring constraints, then propose the smallest markdown change for this repository."
|
||||
|
||||
### Validation for shim implementation
|
||||
|
||||
1. Confirm the shim triggers in expected contexts.
|
||||
2. Confirm resource loading path is unambiguous (direct URI or discovery).
|
||||
3. Confirm repo-local customization remains thin and references Personal MCP as source of truth.
|
||||
|
||||
## Workspace Customization Workflow
|
||||
|
||||
1. Identify the customization primitive and scope.
|
||||
@@ -66,20 +125,6 @@ Use [VS Code customization references](./references/vscode-customization.md) for
|
||||
7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
|
||||
8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.
|
||||
|
||||
## Repo Integration Workflow
|
||||
|
||||
When adding a new skill to this `personal-mcp` repo, follow the resource-first pattern:
|
||||
|
||||
1. Search the catalog for `new skill` and load `resource://skills/new-skill/document`.
|
||||
2. Create authored docs under `docs/skills/<skill-id>/SKILL.md`, with optional nested `references/` markdown files.
|
||||
3. Keep `skill-id` stable and consistent across directory name, `name`, and `x-personal-mcp.id`.
|
||||
4. Put discovery metadata in `SKILL.md` frontmatter under `x-personal-mcp`.
|
||||
5. Declare `resource://skills/<skill-id>/document` in `x-personal-mcp.capabilities`.
|
||||
6. Declare references in `x-personal-mcp.references` as `ref-id -> references/<file>.md` mappings.
|
||||
7. Validate with the registry loader and `uv run zensical build`.
|
||||
|
||||
Keep runtime implementation registry-driven in `src/personal_mcp/mcp.py`; do not add per-skill Python server modules.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before finishing:
|
||||
|
||||
@@ -19,14 +19,125 @@ x-personal-mcp:
|
||||
|
||||
# New Skill Bootstrap
|
||||
|
||||
Use this skill to bootstrap a new skill in the docs-first architecture.
|
||||
Use this skill to bootstrap a new skill in the docs-first architecture. Try to use the `/create-skill` where possible to structure the output, but place it alongside the other skills in this repo.
|
||||
|
||||
## Inputs
|
||||
|
||||
1. New skill id (lowercase kebab-case)
|
||||
2. One-sentence capability statement (what it does and when to use it)
|
||||
3. Optional list of references to include under `references/`
|
||||
|
||||
## Source of Truth and Required References
|
||||
|
||||
1. Use this file as the baseline template for new skill authoring.
|
||||
2. Read and follow these docs before implementing a new skill:
|
||||
- [docs/architecture.md](../../architecture.md)
|
||||
- [docs/content.md](../../content.md)
|
||||
- [docs/frontmatter.md](../../frontmatter.md)
|
||||
- [docs/mcp_layout.md](../../mcp_layout.md)
|
||||
- [docs/uris.md](../../uris.md)
|
||||
|
||||
## Canonical Skill Shape
|
||||
|
||||
Create one skill directory under `docs/skills/`:
|
||||
|
||||
```text
|
||||
docs/
|
||||
skills/
|
||||
<skill-id>/
|
||||
SKILL.md
|
||||
references/
|
||||
... (optional markdown files, nested folders allowed)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `SKILL.md` is required.
|
||||
2. All skill-specific supporting docs live under `references/`.
|
||||
3. Skill directories are ownership boundaries; no cross-skill writes.
|
||||
4. `skill-id` is lowercase kebab-case and should remain stable.
|
||||
|
||||
### Framing
|
||||
|
||||
Phrasing and language in the skills should reflect the intent of providing preferences and reference documentation, rather than being for a migration or transition. When a particular resource is brought in, it should focus the general way something is done.
|
||||
|
||||
## SKILL.md Frontmatter Contract
|
||||
|
||||
`SKILL.md` frontmatter is authoritative for skill metadata.
|
||||
|
||||
Required top-level fields:
|
||||
|
||||
1. `name`
|
||||
2. `description`
|
||||
3. `x-personal-mcp`
|
||||
|
||||
Required `x-personal-mcp` fields:
|
||||
|
||||
1. `id`
|
||||
2. `version`
|
||||
3. `capabilities`
|
||||
|
||||
Optional `x-personal-mcp` fields:
|
||||
|
||||
1. `tags`
|
||||
2. `depends_on`
|
||||
3. `references`
|
||||
|
||||
Canonical frontmatter template:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-id>
|
||||
description: <what this skill does and when to use it>
|
||||
|
||||
x-personal-mcp:
|
||||
id: <skill-id>
|
||||
version: 1.0.0
|
||||
tags: []
|
||||
capabilities:
|
||||
- resource://skills/<skill-id>/document
|
||||
depends_on: []
|
||||
# Optional: only for nested references or metadata overrides.
|
||||
references:
|
||||
<ref-id>:
|
||||
path: references/<file>.md
|
||||
mime_type: text/markdown
|
||||
title: <optional short title>
|
||||
---
|
||||
```
|
||||
|
||||
Reference manifest rules:
|
||||
|
||||
1. `ref-id` is lowercase kebab-case.
|
||||
2. `path` is skill-relative and must stay under `references/`.
|
||||
3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
|
||||
4. Nested `references/**` markdown files must be declared explicitly.
|
||||
5. Reference paths are markdown files.
|
||||
|
||||
## URI Surface
|
||||
|
||||
Canonical resource URIs for a skill:
|
||||
|
||||
1. `resource://skills/<skill_id>/document`
|
||||
2. `resource://skills/<skill_id>/references/<ref_id>`
|
||||
|
||||
Canonical discovery URIs:
|
||||
|
||||
1. `resource://catalog/skills_index`
|
||||
2. `resource://catalog/skills/{skill_id}`
|
||||
|
||||
Compatibility rule:
|
||||
|
||||
1. Keep URI families unversioned by default.
|
||||
2. For breaking changes, update clients to the canonical replacement URIs directly.
|
||||
|
||||
## Scope
|
||||
|
||||
1. Create docs under docs/skills/<skill-id>/.
|
||||
2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields.
|
||||
3. Declare references via x-personal-mcp.references when needed.
|
||||
4. Validate the docs build and MCP resource reads.
|
||||
3. Treat top-level `references/*.md` as auto-discovered references with `ref-id` generated from filename.
|
||||
4. Declare `x-personal-mcp.references` only when you need overrides or nested `references/**` entries.
|
||||
5. Validate the docs build and MCP resource reads.
|
||||
|
||||
## Authoring Checklist
|
||||
|
||||
@@ -35,8 +146,26 @@ Use this skill to bootstrap a new skill in the docs-first architecture.
|
||||
3. Keep skill id and directory name aligned.
|
||||
4. Keep frontmatter name equal to x-personal-mcp.id.
|
||||
5. Include resource://skills/<skill-id>/document in capabilities.
|
||||
6. For each top-level `references/<name>.md`, expect `resource://skills/<skill-id>/references/<name>` (normalized to lowercase kebab-case).
|
||||
7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides.
|
||||
|
||||
## Required Outcomes
|
||||
|
||||
1. Create `docs/skills/<skill-id>/SKILL.md` with valid frontmatter and a practical skill body.
|
||||
2. Create and populate `docs/skills/<skill-id>/references/` with any needed markdown references.
|
||||
3. Ensure frontmatter follows repository contract, including `x-personal-mcp` fields and canonical capabilities.
|
||||
4. Keep URI and reference mapping consistent with repository conventions.
|
||||
5. Reconcile all updates with repository implementation and avoid introducing parallel metadata systems.
|
||||
|
||||
## Validation
|
||||
|
||||
1. uv run zensical build
|
||||
2. uv run pytest -q
|
||||
|
||||
## Output Contract
|
||||
|
||||
Return:
|
||||
|
||||
1. Files created or updated
|
||||
2. Validation results
|
||||
3. Follow-up suggestions for improving the skill
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
name: ruff-linting-formating
|
||||
description: "Reference-first Ruff skill for repository preferences, baseline defaults, and source links. Use to pick consistent Ruff conventions and integration references, not to run migration playbooks."
|
||||
argument-hint: "Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?"
|
||||
x-personal-mcp:
|
||||
id: ruff-linting-formating
|
||||
version: 1.0.0
|
||||
tags:
|
||||
- ruff
|
||||
- linting
|
||||
- formatting
|
||||
- python
|
||||
- ci
|
||||
capabilities:
|
||||
- resource://skills/ruff-linting-formating/document
|
||||
depends_on: []
|
||||
---
|
||||
|
||||
# Ruff Preferences and References
|
||||
|
||||
Use this skill as a reference index for Ruff preferences, conventions, and source documentation.
|
||||
|
||||
This document is intentionally not a migration or transition playbook.
|
||||
|
||||
Load references only when needed:
|
||||
- Ruff core documentation: [Ruff docs](./references/ruff-docs.md)
|
||||
- Tooling integrations (pre-commit and GitHub Actions): [Ruff integrations](./references/ruff-integrations.md)
|
||||
|
||||
## When To Use
|
||||
|
||||
- You want canonical Ruff preferences for this repository context.
|
||||
- You need source links for rule selection, formatter behavior, and integrations.
|
||||
- You are deciding configuration defaults, not planning a migration sequence.
|
||||
|
||||
## Preference Baseline
|
||||
|
||||
Use these as default preferences unless the target repository states otherwise:
|
||||
|
||||
1. Keep linting and formatting both enabled.
|
||||
2. Keep imports sorted via Ruff (`I` rules) rather than a separate import tool.
|
||||
3. Prefer explicit, small rule-family selection first (`E`, `F`, `I`, `UP`) and expand deliberately.
|
||||
4. Keep line length, target Python, and formatter settings aligned to repository policy.
|
||||
5. Keep local and CI execution behavior equivalent.
|
||||
|
||||
### Rule Link Requirement
|
||||
|
||||
When adding a specific rule or ruleset to `ruff.toml`, search for the authoritative Ruff documentation page for that rule or ruleset and include a link to it. You may add the URL as a nearby comment in `ruff.toml` or record it in the repository docs (for example in a CONTRIBUTING or linting section). Prefer links to the official [Ruff rules reference](https://docs.astral.sh/ruff/rules/).
|
||||
|
||||
### Version Discovery Requirement
|
||||
|
||||
When integrating Ruff or any third-party Action for the first time, always search for the latest stable release of:
|
||||
|
||||
- the `ruff` package ([releases](https://github.com/astral-sh/ruff/releases))
|
||||
- the `astral-sh/ruff-pre-commit` hook ([releases](https://github.com/astral-sh/ruff-pre-commit/releases))
|
||||
- the `astral-sh/ruff-action` ([releases](https://github.com/astral-sh/ruff-action/releases))
|
||||
- the `astral-sh/setup-uv` action ([releases](https://github.com/astral-sh/setup-uv/releases))
|
||||
|
||||
Document the version you chose in the example snippet or in a nearby docs file and prefer pinning to a released tag in CI examples. If you intentionally use `latest`, note the reason and the associated risk in repo docs.
|
||||
|
||||
## Decision Inputs
|
||||
|
||||
Collect only the minimum context needed for preference decisions:
|
||||
|
||||
1. Supported Python versions.
|
||||
2. Existing `pyproject.toml` constraints.
|
||||
3. CI provider and required checks.
|
||||
4. Whether pre-commit is in use.
|
||||
|
||||
## Template
|
||||
|
||||
[Full template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
|
||||
|
||||
```toml title="Preferred Baseline"
|
||||
line-length = 120
|
||||
indent-width = 4
|
||||
target-version = "py313"
|
||||
|
||||
exclude = [
|
||||
".git",
|
||||
".venv",
|
||||
".devenv",
|
||||
]
|
||||
|
||||
[lint]
|
||||
extend-fixable = ["ALL"]
|
||||
extend-select = [
|
||||
"C4", # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
|
||||
"E", "W", # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
|
||||
"F", # https://docs.astral.sh/ruff/rules/#pyflakes-f
|
||||
"FURB", # https://docs.astral.sh/ruff/rules/#refurb-furb
|
||||
"I", # https://docs.astral.sh/ruff/rules/#isort-i
|
||||
"N", # https://docs.astral.sh/ruff/rules/#pep8-naming-n
|
||||
"PD", # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
|
||||
"PTH", # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
|
||||
"UP", # https://docs.astral.sh/ruff/rules/#pyupgrade-up
|
||||
"SIM", # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
|
||||
]
|
||||
|
||||
[lint.isort]
|
||||
force-single-line = true
|
||||
|
||||
[format]
|
||||
quote-style = "double"
|
||||
indent-style = "space"
|
||||
skip-magic-trailing-comma = false
|
||||
line-ending = "auto"
|
||||
```
|
||||
|
||||
## Reference Map
|
||||
|
||||
1. Rules and settings source of truth: [Ruff docs](./references/ruff-docs.md)
|
||||
2. pre-commit and GitHub Actions examples: [Ruff integrations](./references/ruff-integrations.md)
|
||||
3. Template to copy from or compare against: [python-template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
|
||||
|
||||
## Non-Goals
|
||||
|
||||
This skill does not define:
|
||||
|
||||
1. Step-by-step migration phases.
|
||||
2. Rollout modes or cutover timelines.
|
||||
3. Mechanical rewrite plans for legacy tooling.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Ruff Source Documentation
|
||||
|
||||
Use this reference when implementing or tuning Ruff in repositories.
|
||||
|
||||
## Core Docs
|
||||
|
||||
- [Ruff overview](https://docs.astral.sh/ruff/)
|
||||
- [Rules reference](https://docs.astral.sh/ruff/rules/)
|
||||
- [Settings reference](https://docs.astral.sh/ruff/settings/)
|
||||
- [Formatter docs](https://docs.astral.sh/ruff/formatter/)
|
||||
- [The Ruff linter](https://docs.astral.sh/ruff/linter/)
|
||||
|
||||
## Migration And Integration
|
||||
|
||||
- [Migrating from Black](https://docs.astral.sh/ruff/formatter/#migrating-from-black)
|
||||
- [Migrating from Flake8](https://docs.astral.sh/ruff/linter/#migrating-from-flake8)
|
||||
- [Migrating from isort](https://docs.astral.sh/ruff/formatter/#sorting-imports)
|
||||
- [Pre-commit integration](https://docs.astral.sh/ruff/integrations/#pre-commit)
|
||||
- [GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions)
|
||||
|
||||
## Python Packaging Context
|
||||
|
||||
- [PEP 621 project metadata in pyproject.toml](https://peps.python.org/pep-0621/)
|
||||
- [uv project and workflow docs](https://docs.astral.sh/uv/)
|
||||
|
||||
## Suggested Reading Order
|
||||
|
||||
1. Overview and settings.
|
||||
2. Rules and linter behavior.
|
||||
3. Formatter and migration references.
|
||||
4. CI and pre-commit integration notes.
|
||||
@@ -0,0 +1,128 @@
|
||||
# Ruff Integrations: Tooling Patterns
|
||||
|
||||
Use this page when wiring Ruff into local developer workflows and CI.
|
||||
|
||||
## Scope
|
||||
|
||||
This reference covers:
|
||||
|
||||
1. [pre-commit](https://pre-commit.com/) hooks for local and pre-push enforcement.
|
||||
2. [GitHub Actions](https://docs.github.com/en/actions) checks for pull request and branch protection gates.
|
||||
|
||||
For Ruff-specific flags and settings, see [Ruff docs](./ruff-docs.md).
|
||||
|
||||
## pre-commit Integration
|
||||
|
||||
### Why use it
|
||||
|
||||
Use pre-commit when you want fast feedback before code reaches CI and consistent checks across contributors.
|
||||
|
||||
### Add hooks
|
||||
|
||||
Create or update [.pre-commit-config.yaml](https://pre-commit.com/#2-add-a-pre-commit-configuration) with Ruff hooks from [astral-sh/ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit):
|
||||
|
||||
```yaml title=".pre-commit-config.yaml"
|
||||
repos:
|
||||
- repo: https://github.com/astral-sh/ruff-pre-commit
|
||||
rev: v0.15.18
|
||||
hooks:
|
||||
- id: ruff-check
|
||||
args: [--fix]
|
||||
- id: ruff-format
|
||||
```
|
||||
|
||||
Pin the hook revision and update intentionally during dependency maintenance.
|
||||
|
||||
### Install and run
|
||||
|
||||
```bash
|
||||
uv run pre-commit install
|
||||
uv run pre-commit run --all-files
|
||||
```
|
||||
|
||||
If the project does not manage pre-commit via uv, use your standard Python environment installation path.
|
||||
|
||||
### Recommended policy
|
||||
|
||||
1. Keep auto-fix enabled locally with ruff-check --fix.
|
||||
2. Keep CI in check-only mode so violations fail loudly.
|
||||
3. Run hooks on all files in migration PRs to avoid drift.
|
||||
|
||||
## GitHub Actions Integration
|
||||
|
||||
### Why use it
|
||||
|
||||
Use GitHub Actions when you need required status checks on pull requests and a single source of truth for lint and format gates.
|
||||
|
||||
### Minimal workflow
|
||||
|
||||
Create [.github/workflows/ruff.yml](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions):
|
||||
|
||||
```yaml title=".github/workflows/ruff.yml"
|
||||
name: Ruff
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
ruff:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Install uv
|
||||
uses: astral-sh/setup-uv@v8.2.0
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install project dependencies
|
||||
run: uv sync --dev
|
||||
|
||||
- name: Ruff lint
|
||||
run: uv run ruff check .
|
||||
|
||||
- name: Ruff format check
|
||||
run: uv run ruff format --check .
|
||||
```
|
||||
|
||||
### Alternative: official Ruff action
|
||||
|
||||
If you want an action-focused setup, see [Ruff GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions). The official Ruff action is commonly used pinned at `astral-sh/[email protected]`. Keep behavior equivalent to local commands so results do not diverge.
|
||||
|
||||
## Alignment Checklist
|
||||
|
||||
Keep local hooks and CI checks aligned:
|
||||
|
||||
1. Same rule set from pyproject.toml.
|
||||
2. Same target Python version and dependency graph.
|
||||
3. Clear developer remediation command in docs:
|
||||
- uv run ruff check . --fix
|
||||
- uv run ruff format .
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook passes locally but CI fails
|
||||
|
||||
1. Ensure CI uses the same pyproject.toml and not a stale cache.
|
||||
2. Confirm matching Ruff versions in local and CI environments.
|
||||
3. Verify CI is not running on a different Python target than local config.
|
||||
|
||||
### CI is slow
|
||||
|
||||
1. Keep Ruff in a dedicated job so failures return early.
|
||||
2. Use dependency caching from your package workflow.
|
||||
3. Avoid running both legacy linters and Ruff after migration completion.
|
||||
|
||||
## Source Links
|
||||
|
||||
- [Ruff integrations](https://docs.astral.sh/ruff/integrations/)
|
||||
- [Ruff pre-commit docs](https://docs.astral.sh/ruff/integrations/#pre-commit)
|
||||
- [Ruff GitHub Actions docs](https://docs.astral.sh/ruff/integrations/#github-actions)
|
||||
- [pre-commit official docs](https://pre-commit.com/)
|
||||
- [GitHub Actions documentation](https://docs.github.com/en/actions)
|
||||
@@ -22,12 +22,20 @@ x-personal-mcp:
|
||||
|
||||
Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows.
|
||||
|
||||
Primary VS Code source docs:
|
||||
|
||||
- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
|
||||
- [Debug configuration (`launch.json`)](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
- [Tasks (`tasks.json`)](https://code.visualstudio.com/docs/editor/tasks)
|
||||
- [MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
||||
|
||||
## When to Use
|
||||
|
||||
- You need to create or fix `.vscode/launch.json` debug profiles.
|
||||
- You need robust Python debugging with `debugpy`.
|
||||
- You need FastAPI-specific launch profiles (app module, host/port, reload options, env files).
|
||||
- You need `.vscode/tasks.json` build/test/run tasks and optional debug pre-launch integration.
|
||||
- You need `.vscode/mcp.json` workspace or user profile MCP server configuration.
|
||||
- You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup.
|
||||
|
||||
## Progressive References
|
||||
@@ -37,6 +45,7 @@ Load only the page that matches the current request:
|
||||
- Launch profile mechanics and debugpy patterns: [debug launch configurations](./references/debug-launch-configurations.md)
|
||||
- FastAPI-focused debug profiles using debugpy: [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md)
|
||||
- Task runner setup in VS Code: [tasks.json project tasks](./references/tasks-json-configuration.md)
|
||||
- MCP server setup in VS Code: [mcp.json MCP server configuration](./references/mcp-server-configuration.md)
|
||||
|
||||
## Procedure
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Debug Launch Configurations in VS Code
|
||||
|
||||
This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.
|
||||
This reference focuses on Python debugging through [`debugpy`](https://github.com/microsoft/debugpy) using [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration).
|
||||
|
||||
## Core Structure
|
||||
|
||||
@@ -15,15 +15,15 @@ A minimal launch file:
|
||||
|
||||
Useful fields for Python configs:
|
||||
|
||||
- `type`: Use `debugpy`.
|
||||
- `type`: Use [`debugpy`](https://code.visualstudio.com/docs/python/debugging).
|
||||
- `request`: Usually `launch`, sometimes `attach`.
|
||||
- `name`: Friendly profile name shown in the Run and Debug panel.
|
||||
- `program`: Script path for script-based entry.
|
||||
- `module`: Module name for `python -m ...` style launches.
|
||||
- `args`: CLI arguments.
|
||||
- `cwd`: Working directory.
|
||||
- `env` / `envFile`: Environment variables.
|
||||
- `console`: `integratedTerminal` is usually most practical.
|
||||
- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
|
||||
- `env` / `envFile`: Environment variables (commonly from [environment variable definitions files](https://code.visualstudio.com/docs/python/environments#_environment-variable-definitions-file)).
|
||||
- `console`: `integratedTerminal` is usually most practical ([launch options](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes)).
|
||||
- `justMyCode`: `true` by default; set `false` when stepping into dependencies.
|
||||
|
||||
## Launch vs Attach
|
||||
@@ -46,7 +46,7 @@ Attach profile example:
|
||||
}
|
||||
```
|
||||
|
||||
Remote process side command example:
|
||||
Remote process side command example (from [debugpy CLI usage](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging)):
|
||||
|
||||
```bash
|
||||
python -m debugpy --listen 5678 -m your_package.main
|
||||
@@ -90,6 +90,13 @@ Prefer module mode when imports depend on package layout.
|
||||
- Keep secrets out of committed launch configs.
|
||||
- Ensure the selected VS Code interpreter matches project tooling.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
|
||||
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
- [Variables reference](https://code.visualstudio.com/docs/editor/variables-reference)
|
||||
- [debugpy project](https://github.com/microsoft/debugpy)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If breakpoints do not hit:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# FastAPI Debug Launch with debugpy
|
||||
|
||||
This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
|
||||
This reference provides practical [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration) patterns for [FastAPI](https://fastapi.tiangolo.com/) applications started with [uvicorn](https://www.uvicorn.org/).
|
||||
|
||||
## Launch FastAPI via Module
|
||||
|
||||
@@ -57,9 +57,11 @@ If app is created via factory function:
|
||||
}
|
||||
```
|
||||
|
||||
Factory mode is powered by uvicorn's [`--factory`](https://www.uvicorn.org/settings/#application) option.
|
||||
|
||||
## Attach to an Existing FastAPI Process
|
||||
|
||||
If the app is launched externally, start with debugpy:
|
||||
If the app is launched externally, start with [`debugpy`](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging):
|
||||
|
||||
```bash
|
||||
python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
|
||||
@@ -96,3 +98,10 @@ A profile is considered valid when:
|
||||
2. A breakpoint inside an endpoint is hit on request.
|
||||
3. A breakpoint in startup/lifespan logic is hit at app boot.
|
||||
4. Terminal output appears in integrated terminal with expected log level.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [FastAPI docs](https://fastapi.tiangolo.com/)
|
||||
- [Uvicorn settings and CLI options](https://www.uvicorn.org/settings/)
|
||||
- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
|
||||
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# Configure MCP Servers in VS Code
|
||||
|
||||
Use this reference to configure MCP servers for GitHub Copilot chat in VS Code with `.vscode/mcp.json` (workspace) or profile-level `mcp.json` (user scope).
|
||||
|
||||
## Where Configuration Lives
|
||||
|
||||
VS Code supports two MCP configuration locations:
|
||||
|
||||
- Workspace scope: `.vscode/mcp.json` in the repository.
|
||||
- User profile scope: open with the `MCP: Open User Configuration` command.
|
||||
|
||||
Use workspace scope for shared team configuration, and user scope for personal or machine-specific servers.
|
||||
|
||||
## Minimal mcp.json
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://api.githubcopilot.com/mcp"
|
||||
},
|
||||
"playwright": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@microsoft/mcp-server-playwright"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `servers` object keys are logical server names shown in VS Code MCP management surfaces.
|
||||
|
||||
## Add Servers Through VS Code UI
|
||||
|
||||
1. Run `MCP: Add Server` from the Command Palette.
|
||||
2. Choose Workspace or Global target.
|
||||
3. Review generated config in `mcp.json`.
|
||||
4. Start or restart the server from `MCP: List Servers`.
|
||||
|
||||
This guided flow is usually safer than manual edits when onboarding teammates.
|
||||
|
||||
## Security and Secrets
|
||||
|
||||
1. Do not hardcode tokens or API keys in `mcp.json`.
|
||||
2. Prefer input variables or environment-file patterns supported by the MCP configuration schema.
|
||||
3. Start only trusted servers, because local servers can execute code on your machine.
|
||||
4. Use trust prompts as a checkpoint instead of bypassing review.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. Apply least privilege by default.
|
||||
2. Keep workspace `mcp.json` limited to team-safe, non-secret configuration.
|
||||
3. Keep personal credentials and machine-specific settings in user-scope configuration, not repository files.
|
||||
4. Prefer explicit allowlists for filesystem writes and outbound network access when sandboxing is enabled.
|
||||
5. Use one server per trust boundary instead of one large multi-purpose server.
|
||||
6. Review server `command` and `args` as code during pull requests.
|
||||
7. Disable or uninstall unused MCP servers to reduce attack surface.
|
||||
8. Use HTTPS endpoints for remote MCP servers whenever available.
|
||||
9. Pin server packages or versions where practical to avoid accidental supply-chain drift.
|
||||
10. Reset trust and re-review configuration after major server changes.
|
||||
|
||||
### Operational Guardrails
|
||||
|
||||
1. Treat MCP resources as publishable unless an explicit access control layer exists.
|
||||
2. Capture server logs during onboarding so failures and suspicious behavior are easier to detect.
|
||||
3. Define ownership for each server entry, including who approves changes and who rotates secrets.
|
||||
4. Document upgrade triggers: if a server starts reading private data or executing side-effectful actions, require stronger access controls before rollout.
|
||||
|
||||
### Team Review Checklist
|
||||
|
||||
Use this checklist before merging workspace MCP configuration changes:
|
||||
|
||||
1. No plaintext secrets in `mcp.json`.
|
||||
2. `command` and `args` are from trusted publishers and expected binaries.
|
||||
3. Server scope is correct (workspace vs user profile).
|
||||
4. Sandboxing is enabled for local `stdio` servers when supported.
|
||||
5. Sandbox allowlists are narrow (minimum paths and domains).
|
||||
6. The change includes an owner and rollback path.
|
||||
|
||||
## Sandbox Local stdio Servers (Linux/macOS)
|
||||
|
||||
For local `stdio` servers, enable sandboxing when possible:
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"myServer": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@example/mcp-server"],
|
||||
"sandboxEnabled": true
|
||||
}
|
||||
},
|
||||
"sandbox": {
|
||||
"filesystem": {
|
||||
"allowWrite": ["${workspaceFolder}"]
|
||||
},
|
||||
"network": {
|
||||
"allowedDomains": ["api.example.com"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Sandboxing is currently available on Linux and macOS, not Windows.
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
1. Open server logs from `MCP: List Servers` -> `Show Output`.
|
||||
2. Confirm trust state (or run `MCP: Reset Trust` if needed).
|
||||
3. Confirm server command and arguments run outside VS Code.
|
||||
4. Confirm workspace-vs-user scope matches where you expect the server to run.
|
||||
5. If using remote development, configure the server in the remote scope when needed.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
||||
- [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
|
||||
- [Input variables for sensitive data](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_input-variables-for-sensitive-data)
|
||||
- [Sandbox configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_sandbox-configuration)
|
||||
- [AI security guidance in VS Code](https://code.visualstudio.com/docs/agents/security)
|
||||
- [Model Context Protocol overview](https://modelcontextprotocol.io/docs/getting-started/intro)
|
||||
@@ -1,6 +1,6 @@
|
||||
# Configure Project Tasks in tasks.json
|
||||
|
||||
Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging.
|
||||
Use [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) to define repeatable project commands and optional hooks for debugging.
|
||||
|
||||
## Minimal File
|
||||
|
||||
@@ -14,12 +14,12 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
|
||||
## Task Fields You Will Use Most
|
||||
|
||||
- `label`: Task name shown in VS Code.
|
||||
- `type`: Usually `shell`.
|
||||
- `type`: Usually [`shell`](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks).
|
||||
- `command`: Executable to run.
|
||||
- `args`: Command arguments.
|
||||
- `options.cwd`: Working directory.
|
||||
- `group`: Mark default build or test tasks.
|
||||
- `problemMatcher`: Parse errors into the Problems panel.
|
||||
- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
|
||||
- `group`: Mark default build or test tasks ([task groups](https://code.visualstudio.com/docs/editor/tasks#_grouping-tasks)).
|
||||
- `problemMatcher`: Parse errors into the Problems panel ([problem matchers](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher)).
|
||||
- `isBackground`: `true` for long-running tasks (for example dev server watch).
|
||||
|
||||
## Python Project Example
|
||||
@@ -56,7 +56,7 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
|
||||
|
||||
## Connect Tasks to Debug Profiles
|
||||
|
||||
In `launch.json`, you can run a task first:
|
||||
In [`launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration), you can run a task first with [`preLaunchTask`](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -90,3 +90,10 @@ If a task fails unexpectedly:
|
||||
3. Confirm tool availability in environment path.
|
||||
4. Confirm quoting and argument boundaries in `args`.
|
||||
5. Confirm the task is not blocked by an outdated background process.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [VS Code Tasks (official)](https://code.visualstudio.com/docs/editor/tasks)
|
||||
- [Tasks Appendix (schema and interfaces)](https://code.visualstudio.com/docs/reference/tasks-appendix)
|
||||
- [Variables Reference](https://code.visualstudio.com/docs/editor/variables-reference)
|
||||
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
|
||||
@@ -204,6 +204,14 @@ Preferred tool fallback order:
|
||||
4. `get_pattern_by_id`
|
||||
5. `get_skill_document_by_id`
|
||||
|
||||
Compatibility aliases for clients that use `catalog_*` naming are also available:
|
||||
|
||||
1. `catalog_search_patterns`
|
||||
2. `catalog_get_pattern_by_id`
|
||||
3. `catalog_get_skill_document_by_id`
|
||||
|
||||
Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.
|
||||
|
||||
If confidence is low after discovery, ask one clarifying question before loading more context.
|
||||
```
|
||||
|
||||
|
||||
@@ -185,4 +185,32 @@ def get_skill_document_by_id(skill_id: str) -> dict[str, Any]:
|
||||
}
|
||||
|
||||
|
||||
@mcp.tool
|
||||
def catalog_search_patterns(
|
||||
query: str = "",
|
||||
tags: list[str] | None = None,
|
||||
skip: int = 0,
|
||||
limit: int = 20,
|
||||
) -> dict[str, Any]:
|
||||
"""Compatibility alias for clients expecting catalog_* tool naming."""
|
||||
return search_patterns(
|
||||
query=query,
|
||||
tags=tags,
|
||||
skip=skip,
|
||||
limit=limit,
|
||||
)
|
||||
|
||||
|
||||
@mcp.tool
|
||||
def catalog_get_pattern_by_id(id: str) -> dict[str, Any]:
|
||||
"""Compatibility alias for clients expecting catalog_* tool naming."""
|
||||
return get_pattern_by_id(id)
|
||||
|
||||
|
||||
@mcp.tool
|
||||
def catalog_get_skill_document_by_id(skill_id: str) -> dict[str, Any]:
|
||||
"""Compatibility alias for clients expecting catalog_* tool naming."""
|
||||
return get_skill_document_by_id(skill_id)
|
||||
|
||||
|
||||
_install_tool_fallback_transforms()
|
||||
|
||||
@@ -108,6 +108,11 @@ nav = [
|
||||
{ "Overview" = "skills/python-logging-dictconfig/SKILL.md" },
|
||||
{ "Docs" = "skills/python-logging-dictconfig/references/python-logging-docs.md" },
|
||||
] },
|
||||
{ "Ruff" = [
|
||||
{ "Overview" = "skills/ruff-linting-formating/SKILL.md" },
|
||||
{ "Docs" = "skills/ruff-linting-formating/references/ruff-docs.md" },
|
||||
{ "Integrations" = "skills/ruff-linting-formating/references/ruff-integrations.md" },
|
||||
] },
|
||||
{ "Zensical" = [
|
||||
{ "Overview" = "skills/zensical-docs/SKILL.md" },
|
||||
{ "Map" = "skills/zensical-docs/references/index.md" },
|
||||
|
||||
Reference in New Issue
Block a user