Skip to content

Commit 353059f

Browse files
olaservoclaude
olaservo
and
claude
committed
Add architecture diagram for SEP reference implementation
ASCII diagrams showing: overall system structure, URI anatomy, discovery flow, SDK-to-protocol mapping, and what's permanent SEP design vs temporary SDK shims. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8028e6b commit 353059f

1 file changed

Lines changed: 147 additions & 0 deletions

File tree

‎examples/ARCHITECTURE.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Skills Extension SEP — Architecture
2+
3+
## How It All Fits Together
4+
5+
```
6+
┌─────────────────────────────────────────────────────────────────────┐
7+
│ HOST │
8+
│ │
9+
│ ┌───────────────┐ Exposes to model: │
10+
│ │ read_resource │◄── { server, uri } │
11+
│ │ (tool) │ "Read an MCP resource from a connected │
12+
│ └───────┬───────┘ server." │
13+
│ │ │
14+
│ │ Routes by server name │
15+
│ ▼ │
16+
│ ┌───────────────┐ ┌───────────────┐ │
17+
│ │ MCP Client A │ │ MCP Client B │ ... │
18+
│ └───────┬───────┘ └───────────────┘ │
19+
└──────────┼──────────────────────────────────────────────────────────┘
20+
│ stdio / SSE
21+
▼
22+
┌──────────────────────────────────────────────────────────────────────┐
23+
│ MCP SERVER │
24+
│ │
25+
│ capabilities.extensions: { "io.modelcontextprotocol/skills": {} } │
26+
│ │
27+
│ ┌────────────────────────────────────────────────────────────────┐ │
28+
│ │ Skills Extension SDK │ │
29+
│ │ │ │
30+
│ │ discoverSkills(skillsDir) │ │
31+
│ │ ├── Recursively finds SKILL.md files │ │
32+
│ │ ├── Parses YAML frontmatter (name, description) │ │
33+
│ │ ├── Validates: final path segment == frontmatter name │ │
34+
│ │ ├── Enforces no-nesting constraint │ │
35+
│ │ └── Returns Map<skillPath, SkillMetadata> │ │
36+
│ │ │ │
37+
│ │ registerSkillResources(server, skillMap, skillsDir) │ │
38+
│ │ ├── skill://{path}/SKILL.md (listed, per skill) │ │
39+
│ │ ├── skill://{path}/_manifest (listed, per skill) │ │
40+
│ │ ├── skill://{+filePath} (template, supporting) │ │
41+
│ │ └── skill://prompt-xml (optional, XML summary) │ │
42+
│ │ │ │
43+
│ │ SEP-2093 shims (resource-extensions.ts) │ │
44+
│ │ ├── resources/metadata (metadata without content) │ │
45+
│ │ ├── resources/list + uri param (scoped enumeration) │ │
46+
│ │ └── _meta capabilities (per-resource capabilities) │ │
47+
│ └────────────────────────────────────────────────────────────────┘ │
48+
│ │
49+
│ ┌────────────────────────────────────────────────────────────────┐ │
50+
│ │ Skills Directory │ │
51+
│ │ │ │
52+
│ │ sample-skills/ │ │
53+
│ │ ├── code-review/ │ │
54+
│ │ │ ├── SKILL.md ──► skill://code-review/SKILL.md │ │
55+
│ │ │ └── references/ │ │
56+
│ │ │ └── REFERENCE.md ──► skill://code-review/ref...md │ │
57+
│ │ ├── git-commit-review/ │ │
58+
│ │ │ └── SKILL.md ──► skill://git-commit-review/... │ │
59+
│ │ └── acme/ ◄── organizational prefix │ │
60+
│ │ ├── billing/ │ │
61+
│ │ │ └── refunds/ ◄── name = "refunds" │ │
62+
│ │ │ ├── SKILL.md ──► skill://acme/billing/refunds/.. │ │
63+
│ │ │ └── templates/ │ │
64+
│ │ │ └── email ──► skill://acme/billing/refunds/.. │ │
65+
│ │ └── onboarding/ ◄── name = "onboarding" │ │
66+
│ │ └── SKILL.md ──► skill://acme/onboarding/... │ │
67+
│ └────────────────────────────────────────────────────────────────┘ │
68+
└──────────────────────────────────────────────────────────────────────┘
69+
```
70+
71+
## Skill URI Structure
72+
73+
```
74+
skill://<skill-path>/SKILL.md
75+
├──────────┘ └──────┘
76+
│ │
77+
│ └── file-path (always explicit)
78+
│
79+
└── locator: prefix + name
80+
├── prefix: server-chosen (e.g., "acme/billing")
81+
└── name: final segment = frontmatter name (e.g., "refunds")
82+
```
83+
84+
## Discovery Flow
85+
86+
```
87+
Host Server
88+
│ │
89+
│ initialize ──────────────► │
90+
│ ◄──── capabilities: │
91+
│ extensions: │
92+
│ io.modelcontextprotocol/skills: {}
93+
│ │
94+
│ resources/list ──────────► │ Returns all resources
95+
│ ◄──── skill://*/SKILL.md │ (client filters for skill://)
96+
│ entries │
97+
│ │
98+
│ resources/list ──────────► │ SEP-2093: scoped
99+
│ { uri: "skill://" } │ Returns only SKILL.md entries
100+
│ ◄──── filtered list │
101+
│ │
102+
│ resources/metadata ──────► │ SEP-2093: metadata only
103+
│ { uri: "skill://..." } │ No content transferred
104+
│ ◄──── { resource: { name, │
105+
│ description, caps } } │
106+
│ │
107+
│ resources/read ──────────► │ Load skill content
108+
│ { uri: "skill://..." } │
109+
│ ◄──── { contents: [{ text: │
110+
│ "---\nname: ...\n..." │
111+
│ }] } │
112+
│ │
113+
```
114+
115+
## SDK Wrapper Mapping
116+
117+
```
118+
SEP Concept SDK Function Protocol Call
119+
─────────────────────────────────────────────────────────────────────
120+
Host tool for model READ_RESOURCE_TOOL (tool schema)
121+
Discover skills listSkills() resources/list
122+
Scoped discovery listSkillsScoped(uri) resources/list + uri
123+
Read any skill URI readSkillUri(uri) resources/read
124+
Read by path readSkillContent(path) resources/read
125+
Metadata without content fetchSkillMetadata(uri) resources/metadata
126+
File manifest readSkillManifest(path) resources/read
127+
Supporting files readSkillDocument(path,f) resources/read
128+
```
129+
130+
## What's a Shim vs What's the SEP
131+
132+
```
133+
┌──────────────────────────────┬────────────────────────────────────┐
134+
│ SEP (permanent) │ SDK Shims (temporary) │
135+
├──────────────────────────────┼────────────────────────────────────┤
136+
│ skill:// URI convention │ ServerInternals interface │
137+
│ SKILL.md explicit in URI │ _requestHandlers override │
138+
│ Final segment = name │ _capabilities patching │
139+
│ No-nesting constraint │ capabilities in _meta │
140+
│ resources/read for loading │ │
141+
│ resources/list for discovery │ Tracking PRs: │
142+
│ resources/metadata (2093) │ - typescript-sdk#1630 (extensions)│
143+
│ read_resource host tool │ - SEP-2093 (uri param, metadata, │
144+
│ Extension declaration │ per-resource capabilities) │
145+
│ listSkills / readSkillUri │ │
146+
└──────────────────────────────┴────────────────────────────────────┘
147+
```

0 commit comments

Comments
 (0)