notque/vexjoy-agent / skills/programming/programming
programming
FlaggedLanguage rules, workflows, and tooling: Go, Python, Rust, Kotlin, Swift, PHP, TypeScript type checks and debugging, OpenStack Python, MCP local-docs servers, Node.js backend APIs.
references/mcp-local-docs/mcp-preferred-patterns.md
View on GitHub---
description: Common MCP server mistakes with detection commands and fixes — front matter parsing, caching failures, protocol violations
---
# MCP Server Patterns Guide
> **Scope**: MCP documentation server patterns in TypeScript/Node.js. SDK 0.5.0+, Node.js 18+.
## Pattern Catalog
### Wrap Front Matter Parsing in Try/Catch
Parse defensively. A single malformed file must never crash the server.
```typescript
function parseFrontMatter(content: string): { metadata: Partial<DocMetadata>; error?: string } {
const parts = content.split('---');
if (parts.length < 3) {
return { metadata: {}, error: 'No front matter delimiters found' };
}
try {
const metadata = yaml.parse(parts[1]) as DocMetadata;
return { metadata: metadata ?? {} };
} catch (err) {
// Log warning, return empty metadata — do not crash
return { metadata: {}, error: `YAML parse failed: ${(err as Error).message}` };
}
}
// In indexing loop:
const { metadata, error } = parseFrontMatter(content);
if (error) {
console.warn(`[warn] front matter: ${filePath}: ${error}`);
// Continue indexing remaining files
}
```
**Why**: One bad YAML file crashes `yaml.parse()`, exiting the server and making 999 other docs inaccessible.
**Detection**:
```bash
# Find YAML parse calls without try/catch
grep -rn 'yaml\.parse\|yaml\.load\|toml\.parse' --include="*.ts" src/
# Check if they're wrapped in try/catch
grep -B5 'yaml\.parse\|yaml\.load' --include="*.ts" -rn src/
```
**Version note**: `js-yaml` >= 4.0 uses `yaml.load()` not `yaml.safeLoad()`. The `safeLoad` method was removed in 4.0.
---
### Strip Hugo Shortcodes Before Sending Content
Remove `{{< >}}` and `{{% %}}` before returning to clients. LLMs interpret them as noise.
```typescript
function stripHugoShortcodes(content: string): string {
return content
// Remove block shortcodes: {{< name >}}...{{< /name >}}
.replace(/\{\{<\s*\/?\s*\w+[^>]*>\}\}/g, '')
// Remove percent shortcodes: {{% name %}}
.replace(/\{\{%[^%]*%\}\}/g, '')
// Remove inline shortcodes with content
.replace(/\{\{<\s*\w+[^>]*>\}\}[\s\S]*?\{\{<\s*\/\w+\s*>\}\}/g, '')
// Clean up empty lines left by removal
.replace(/\n{3,}/g, '\n\n');
}
```
**Why**: Shortcodes are not markdown. Raw shortcodes cause misinterpretation or hallucinated explanations.
**Detection**:
```bash
# Find files likely to have shortcodes
grep -rn '{{[<%]' --include="*.md" content/ | head -20
# Check if server strips them
grep -rn 'shortcode\|{{%\|{{<' --include="*.ts" src/
```
---
### Declare All Implemented Capabilities
Register `resources` and `tools` in capabilities during init. Omit unused keys.
```typescript
this.server = new Server(
{ name: 'local-docs', version: '1.0.0' },
{
capabilities: {
resources: {}, // Enables resources/list and resources/read
tools: {}, // Enables tools/list and tools/call
// Only add these if you implement them:
// prompts: {},
// logging: {},
},
}
);
```
**Why**: Clients negotiate during `initialize`. Missing `capabilities.resources` = docs never discovered. Missing `capabilities.tools` = invisible tools.
**Detection**:
```bash
grep -rn 'capabilities' --include="*.ts" src/
grep -rn 'new Server(' --include="*.ts" src/ -A5 | grep -v 'capabilities'
```
**Version note**: SDK 0.6.0+ allows omitting empty `{}` for unimplemented capabilities — they default to absent.
---
### Validate URI Paths Against Traversal
Resolve and verify containment within docs root. `path.join` normalizes but does NOT prevent traversal.
```typescript
function safeUriToPath(docsRoot: string, uri: string): string {
if (!uri.startsWith('docs://')) {
throw new McpError(ErrorCode.InvalidParams, `Invalid URI scheme: ${uri}`);
}
const relative = uri.slice('docs://'.length);
const resolved = path.resolve(docsRoot, relative);
// Enforce that resolved path stays within docsRoot
if (!resolved.startsWith(path.resolve(docsRoot) + path.sep) &&
resolved !== path.resolve(docsRoot)) {
throw new McpError(ErrorCode.InvalidParams, 'Path traversal not allowed');
}
return resolved;
}
```
**Why**: `path.join('/docs', '../etc/passwd')` = `/etc/passwd`. Clients can read any accessible file without validation.
**Detection**:
```bash
grep -rn 'uriToPath\|path\.join.*params\.uri\|path\.resolve.*params' --include="*.ts" src/
```
---
### Filter Draft Documents From Resource Lists
Exclude `draft: true` from resource lists.
```typescript
const resources = Array.from(this.docsIndex.values())
.filter((doc) => !doc.metadata.draft)
.map((doc) => ({
uri: doc.uri,
name: doc.metadata.title ?? path.basename(doc.path, '.md'),
description: doc.metadata.description,
mimeType: 'text/markdown',
}));
```
**Why**: Drafts are unpublished. Exposing them lets Claude cite incomplete content as authoritative.
**Detection**:
```bash
# Check if draft filtering exists in list handler
grep -rn 'draft\|isDraft' --include="*.ts" src/
# Check Hugo content for draft: true documents
grep -rn '^draft: true\|^draft: "true"' --include="*.md" content/
```
---
## Error-Fix Mappings
| Error Message | Root Cause | Fix |
|---------------|------------|-----|
| `YAMLException: unexpected end of the stream` | Unclosed YAML string in front matter | Wrap in try/catch, skip file with warning |
| `TypeError: Cannot read properties of null (reading 'title')` | `yaml.parse()` returned null for empty front matter | Check `metadata ?? {}` after parse |
| `McpError: Resource not found` at client | URI uses backslash on Windows (`docs://foo\bar`) | Normalize with `replace(/\\/g, '/')` in `pathToUri` |
| Server exits with code 1 immediately | Uncaught promise rejection in `indexDocs()` | Add `.catch()` to indexing promise or wrap in try/catch |
| Client sees 0 resources | `capabilities.resources` not declared | Add `resources: {}` to server capabilities |
| `tools/list` returns empty array | `capabilities.tools` not declared | Add `tools: {}` to server capabilities |
| `EACCES: permission denied` | Server process lacks read permission | Check file ownership; run with appropriate user |
---
## Detection Commands Reference
```bash
# All YAML/TOML parse calls (verify each has try/catch)
grep -rn 'yaml\.parse\|yaml\.load\|toml\.parse' --include="*.ts" src/
# Hugo shortcodes not stripped
grep -rn '{{[<%]' --include="*.md" content/ | wc -l
# Missing capability declaration
grep -rn 'new Server(' --include="*.ts" src/ -A5 | grep -v 'capabilities'
# Path traversal risk
grep -rn 'path\.join.*params\.' --include="*.ts" src/
# Draft documents in index
grep -rn 'draft' --include="*.ts" src/ | grep -v filter
# Generic Error instead of McpError
grep -rn 'throw new Error(' --include="*.ts" src/
```
---
## See Also
- `mcp-patterns.md` — Correct MCP server development patterns
- Hugo front matter docs: https://gohugo.io/content-management/front-matter/
- MCP error codes: https://spec.modelcontextprotocol.io/specification/server/utilities/logging/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |