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

mcp updates

Browse Source
This commit is contained in:
John Lancaster
2026-08-27 18:48:21 -05:00
parent e999437b93
commit f3bbbfc25f
8 changed files with 43 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/personal_mcp/docs/contracts/uris.md
+1 -3
View File
@@ -60,9 +60,7 @@ For skills:
4. read `_manifest` when supporting material may be needed
5. fetch only the supporting paths relevant to the task
Tool-only agents may call `search_skills` instead of retrieving the complete resource list. Search results contain only provider-derived names, descriptions, and canonical main-resource URIs; skill content remains available exclusively through the native resource contract.
For prompts, use the native MCP prompt APIs or their generic tool projection.
For prompts, use the native MCP prompt APIs.
## Stability Policy
src/personal_mcp/docs/copilot.md
+10 -11
View File
@@ -16,7 +16,7 @@ Copilot interacts with MCP servers through independently exposed lanes:
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.
This server publishes skills as native `skill://` resources, general docs as `resource://docs/{path*}` resources, and workflows as native MCP prompt objects. It intentionally publishes no compatibility tools that mirror resources or prompts.
## VS Code Feature Coverage
@@ -25,7 +25,7 @@ The server uses every FastMCP feature that applies to its read-only guidance wor
| 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. |
| Tools | No tools are published for this documentation-only server surface. Resource and prompt operations stay on native MCP capabilities. |
| 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. |
@@ -66,11 +66,10 @@ A successful `resources/list` response does not guarantee the picker appears in
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
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.
@@ -102,13 +101,13 @@ A repo-level instruction should name the native retrieval order and context budg
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.
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.
```
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.
Instructions steer behavior but do not force VS Code to attach resources automatically.
## Prompt Objects
@@ -118,7 +117,7 @@ Prompts remain separate from skills. When the client supports MCP prompt APIs, u
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.
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.
src/personal_mcp/docs/skills/mcp-details/references/sdk-and-fastmcp.md
+6 -2
View File
@@ -14,14 +14,18 @@ Use this page for implementation-oriented links across MCP SDKs and FastMCP.
!!! info "FastMCP sources"
- [FastMCP project documentation](https://gofastmcp.com/)
- [FastMCP server identity and behavior](https://gofastmcp.com/servers/server)
- [FastMCP providers overview](https://gofastmcp.com/servers/providers/overview)
- [FastMCP custom providers](https://gofastmcp.com/servers/providers/custom)
- [FastMCP skills provider](https://gofastmcp.com/servers/providers/skills)
- [FastMCP tools and annotations](https://gofastmcp.com/servers/tools)
- [FastMCP resources and templates](https://gofastmcp.com/servers/resources)
- [FastMCP prompts](https://gofastmcp.com/servers/prompts)
- [FastMCP filesystem provider](https://gofastmcp.com/servers/providers/filesystem)
- [FastMCP argument completion](https://gofastmcp.com/servers/completions)
- [FastMCP component icons](https://gofastmcp.com/servers/icons)
- [FastMCP Apps](https://gofastmcp.com/apps/overview)
- [FastMCP GitHub repository](https://github.com/jlowin/fastmcp)
- [FastMCP examples directory](https://github.com/jlowin/fastmcp/tree/main/examples)
- [FastMCP GitHub repository](https://github.com/PrefectHQ/fastmcp)
- [FastMCP examples directory](https://github.com/PrefectHQ/fastmcp/tree/main/examples)
- [FastMCP PyPI package](https://pypi.org/project/fastmcp/)
## Server Implementation Patterns
src/personal_mcp/docs/usage.md
+3 -3
View File
@@ -53,15 +53,15 @@ These utilities operate directly on the native `skill://` contract and require n
In VS Code, skills can arrive through:
1. explicit attachment from `Add Context > MCP Resources` or `MCP: Browse Resources`
2. the `search_skills` and `read_resource` tools for autonomous agents
2. direct resource reads on selected `skill://<name>/SKILL.md` entries
3. a slash-command prompt that names a specific native skill URI
Instructions can steer retrieval, but they do not guarantee automatic resource attachment in every chat surface. When the deferred-tool catalog omits direct MCP resource operations, use the tools; search derives matches from native provider metadata and `read_resource` delegates to the provider without duplicating skill content.
Instructions can steer retrieval, but they do not guarantee automatic resource attachment in every chat surface. Use `MCP: Browse Resources` to confirm server-side availability, then attach only the minimum skill resources needed for the current task.
A reliable prompt is:
```text
Call search_skills with the task or capability and select the best matching skill://.../SKILL.md result. Use read_resource for one selected skill, inspect its _manifest only if supporting detail is needed, and reconcile the guidance with this workspace.
Browse MCP resources, select the best matching skill://.../SKILL.md entry by description, inspect its _manifest only if supporting detail is needed, and reconcile the guidance with this workspace.
```
## Thin Shim Pattern
src/personal_mcp/mcp.py
+6 -147
View File
@@ -1,15 +1,10 @@
from __future__ import annotations
import re
from typing import Annotated
from fastmcp import FastMCP
from mcp.types import CompletionArgument
from mcp.types import CompletionContext
from mcp.types import Icon
from mcp.types import PromptReference
from pydantic import BaseModel
from pydantic import Field
from mcp_types import CompletionArgument
from mcp_types import CompletionContext
from mcp_types import Icon
from mcp_types import PromptReference
from personal_mcp.prompts import create_prompts_provider
from personal_mcp.prompts.models import MarkdownPrompt
@@ -21,9 +16,8 @@ from personal_mcp.skills import create_skills_provider
_SERVER_INSTRUCTIONS = """Personal development guidance exposed as native MCP resources and prompts.
Use prompts for parameterized workflows. For task-specific guidance, search skills, select one
skill://<name>/SKILL.md result, and read its manifest only when supporting detail is needed. Read-only
compatibility tools expose the same resource catalog to clients without native resource access.
Use prompts for parameterized workflows. For task-specific guidance, browse native skill resources,
select one skill://<name>/SKILL.md resource, and read its manifest only when supporting detail is needed.
"""
_SERVER_ICON = Icon(
src=(
@@ -47,51 +41,6 @@ def _ro_annotations() -> dict[str, bool]:
}
class SkillSearchResult(BaseModel):
"""Metadata needed to select a native skill resource."""
name: str
description: str
uri: str
class SkillSearchResponse(BaseModel):
"""Bounded skill matches for an agent search query."""
results: list[SkillSearchResult]
def _skill_search_score(name: str, description: str, query: str) -> int:
normalized_name = name.casefold().replace("-", " ")
normalized_description = description.casefold()
normalized_query = " ".join(query.casefold().split())
terms = tuple(dict.fromkeys(re.findall(r"[a-z0-9]+", normalized_query)))
if not terms:
return 0
name_terms = set(normalized_name.split())
description_terms = set(re.findall(r"[a-z0-9]+", normalized_description))
score = 100 if normalized_query == normalized_name else 0
matched_terms = 0
for term in terms:
term_score = 0
if term in name_terms:
term_score = 20
elif term in normalized_name:
term_score = 10
elif term in description_terms:
term_score = 4
elif term in normalized_description:
term_score = 1
if term_score:
matched_terms += 1
score += term_score
if matched_terms == len(terms):
score += 10
return score
def _register_components(mcp: FastMCP, registry: DocsRegistry) -> None:
@mcp.resource(
"resource://docs/{path*}",
@@ -106,95 +55,6 @@ def _register_components(mcp: FastMCP, registry: DocsRegistry) -> None:
return read_docs_markdown_path(registry, path)
def _register_resource_tools(mcp: FastMCP) -> None:
@mcp.tool(
name="search_skills",
title="Search Skills",
description=(
"Find task-specific skill guidance by capability, technology, problem, or workflow. "
"Returns skill metadata and canonical URIs only; use read_resource to load a selected result."
),
tags={"search", "skills"},
annotations=_ro_annotations(),
)
async def search_skills(
query: Annotated[
str,
Field(
min_length=2,
max_length=300,
description="Capability, technology, problem, or workflow to find.",
),
],
limit: Annotated[
int,
Field(ge=1, le=10, description="Maximum number of matches to return."),
] = 5,
) -> SkillSearchResponse:
resources = await mcp.list_resources()
matches: list[tuple[int, SkillSearchResult]] = []
for resource in resources:
uri = str(resource.uri)
if not uri.startswith("skill://") or not uri.endswith("/SKILL.md"):
continue
name = uri.removeprefix("skill://").removesuffix("/SKILL.md")
description = resource.description or ""
score = _skill_search_score(name, description, query)
if score:
matches.append(
(
score,
SkillSearchResult(name=name, description=description, uri=uri),
)
)
matches.sort(key=lambda match: (-match[0], match[1].name))
return SkillSearchResponse(results=[match[1] for match in matches[:limit]])
@mcp.tool(
name="list_resources",
title="List Resources",
description=(
"List available MCP resources and URI templates. Use before read_resource to discover skill guidance."
),
annotations=_ro_annotations(),
)
async def list_resources() -> dict[str, list[dict[str, str | None]]]:
resources = await mcp.list_resources()
templates = await mcp.list_resource_templates()
return {
"resources": [
{
"uri": str(resource.uri),
"name": resource.name,
"description": resource.description,
"mime_type": resource.mime_type,
}
for resource in resources
],
"templates": [
{
"uri_template": template.uri_template,
"name": template.name,
"description": template.description,
"mime_type": template.mime_type,
}
for template in templates
],
}
@mcp.tool(
name="read_resource",
title="Read Resource",
description="Read a resource URI returned by list_resources, including skill files, manifests, and references.",
annotations=_ro_annotations(),
)
async def read_resource(uri: str) -> dict[str, object]:
result = await mcp.read_resource(uri)
return result.model_dump(mode="json", exclude_none=True)
def _register_prompt_completions(mcp: FastMCP, provider: MarkdownPromptsProvider) -> None:
@mcp.completion
async def complete_prompt_argument(
@@ -230,6 +90,5 @@ def create_mcp() -> FastMCP:
prompts_provider = create_prompts_provider()
mcp.add_provider(prompts_provider)
mcp.add_provider(create_skills_provider())
_register_resource_tools(mcp)
_register_prompt_completions(mcp, prompts_provider)
return mcp