Skip to content

notque/vexjoy-agent / skills/programming/programming

programming

Flagged

Language 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.

FileKindSize
SKILL.mdskill md19.3 KB
references/go/code-review.mdmarkdown12.0 KB
references/go/code-review/common-review-comments.mdmarkdown6.6 KB
references/go/concurrency.mdmarkdown11.5 KB
references/go/concurrency/concurrency-patterns.mdmarkdown5.7 KB
references/go/error-handling.mdmarkdown10.8 KB
references/go/error-handling/patterns.mdmarkdown4.2 KB
references/go/google-style-guide/SHA256SUMSother313 B
references/go/google-style-guide/UPSTREAM_REVISIONother41 B
references/go/google-style-guide/best-practices/part-01.mdmarkdown10.0 KB
references/go/google-style-guide/best-practices/part-02.mdmarkdown15.0 KB
references/go/google-style-guide/best-practices/part-03.mdmarkdown14.1 KB
references/go/google-style-guide/best-practices/part-04.mdmarkdown13.5 KB
references/go/google-style-guide/best-practices/part-05.mdmarkdown10.5 KB
references/go/google-style-guide/best-practices/part-06.mdmarkdown14.4 KB
references/go/google-style-guide/best-practices/part-07.mdmarkdown16.1 KB
references/go/google-style-guide/best-practices/part-08.mdmarkdown11.4 KB
references/go/google-style-guide/best-practices/part-09.mdmarkdown13.7 KB
references/go/google-style-guide/best-practices/part-10.mdmarkdown16.9 KB
references/go/google-style-guide/decisions/part-01.mdmarkdown15.0 KB
references/go/google-style-guide/decisions/part-02.mdmarkdown12.5 KB
references/go/google-style-guide/decisions/part-03.mdmarkdown11.5 KB
references/go/google-style-guide/decisions/part-04.mdmarkdown8.4 KB
references/go/google-style-guide/decisions/part-05.mdmarkdown9.8 KB
references/go/google-style-guide/decisions/part-06.mdmarkdown14.7 KB
references/go/google-style-guide/decisions/part-07.mdmarkdown13.3 KB
references/go/google-style-guide/decisions/part-08.mdmarkdown14.3 KB
references/go/google-style-guide/decisions/part-09.mdmarkdown15.3 KB
references/go/google-style-guide/decisions/part-10.mdmarkdown8.3 KB
references/go/google-style-guide/guide/part-01.mdmarkdown16.3 KB
references/go/google-style-guide/guide/part-02.mdmarkdown3.0 KB
references/go/google-style-guide/index.mdmarkdown8.4 KB
references/go/preferred-patterns.mdmarkdown12.5 KB
references/go/preferred-patterns/code-examples.mdmarkdown11.6 KB
references/go/quality-gate.mdmarkdown7.3 KB
references/go/quality-gate/common-lint-errors.jsonconfig7.6 KB
references/go/quality-gate/examples.mdmarkdown11.0 KB
references/go/quality-gate/makefile-targets.jsonconfig5.1 KB
references/go/sapcc-conventions.mdmarkdown34.6 KB
references/go/sapcc-conventions/api-design-detailed.mdmarkdown22.7 KB
references/go/sapcc-conventions/architecture-patterns.mdmarkdown18.6 KB
references/go/sapcc-conventions/build-ci-detailed.mdmarkdown18.7 KB
references/go/sapcc-conventions/error-handling-detailed.mdmarkdown20.1 KB
references/go/sapcc-conventions/extended-patterns.mdmarkdown7.1 KB
references/go/sapcc-conventions/go-bits-philosophy-detailed.mdmarkdown24.5 KB
references/go/sapcc-conventions/library-reference.mdmarkdown14.0 KB
references/go/sapcc-conventions/pr-mining-insights.mdmarkdown17.5 KB
references/go/sapcc-conventions/review-standards.mdmarkdown10.5 KB
references/go/sapcc-conventions/sapcc-code-patterns.mdmarkdown46.2 KB
references/go/testing.mdmarkdown9.7 KB
references/go/testing/go-benchmark-and-concurrency.mdmarkdown5.6 KB
references/go/testing/go-test-patterns.mdmarkdown9.0 KB
references/golang-general.mdmarkdown8.9 KB
references/golang-general/go-modern-code.mdmarkdown17.2 KB
references/golang-general/go-verification-workflow.mdmarkdown5.0 KB
references/golang-general/go-version-idioms.mdmarkdown6.8 KB
references/kotlin-general.mdmarkdown7.5 KB
references/kotlin-general/kotlin-patterns.mdmarkdown7.9 KB
references/kotlin-general/kotlin-security-testing.mdmarkdown4.4 KB
references/kotlin-general/kotlin-security.mdmarkdown11.1 KB
references/kotlin/concurrency-patterns.mdmarkdown5.4 KB
references/kotlin/kotlin-testing.mdmarkdown7.9 KB
references/mcp-local-docs.mdmarkdown6.9 KB
references/mcp-local-docs/mcp-patterns.mdmarkdown9.6 KB
references/mcp-local-docs/mcp-preferred-patterns.mdmarkdown6.9 KB
references/mcp-local-docs/server-templates.mdmarkdown4.4 KB
references/mcp-local-docs/typescript-async-patterns.mdmarkdown8.9 KB
references/nodejs-api.mdmarkdown7.3 KB
references/nodejs-api/auth-patterns.mdmarkdown10.0 KB
references/nodejs-api/middleware-patterns.mdmarkdown10.5 KB
references/nodejs-api/nodejs-security.mdmarkdown12.3 KB
references/nodejs-api/webhook-patterns.mdmarkdown9.9 KB
references/php-general.mdmarkdown4.7 KB
references/php-general/php-behaviors.mdmarkdown5.2 KB
references/php-general/php-conventions.mdmarkdown5.8 KB
references/php/modern-php-features.mdmarkdown4.4 KB
references/php/testing-patterns.mdmarkdown7.5 KB
references/python-general.mdmarkdown7.7 KB
references/python-general/flask-jinja-webapp.mdmarkdown5.7 KB
references/python-general/python-local-gates.mdmarkdown4.4 KB
references/python-general/python-modern-code.mdmarkdown23.1 KB
references/python-openstack.mdmarkdown5.2 KB
references/python-openstack/error-handling.mdmarkdown658 B
references/python-openstack/hacking-rules.mdmarkdown4.1 KB
references/python-openstack/openstack-patterns.mdmarkdown1.2 KB
references/python-openstack/oslo-patterns.mdmarkdown6.4 KB
references/python-openstack/output-format.mdmarkdown2.4 KB
references/python-openstack/preferred-patterns.mdmarkdown1.9 KB
references/python-openstack/rpc-versioning.mdmarkdown5.3 KB
references/rust-general.mdmarkdown8.2 KB
references/rust-general/rust-modern-code.mdmarkdown13.4 KB
references/rust-general/rust-verification-workflow.mdmarkdown5.5 KB
references/rust-general/rust-version-idioms.mdmarkdown7.0 KB
references/swift-general.mdmarkdown5.7 KB
references/swift-general/swift-patterns.mdmarkdown6.7 KB
references/swift-general/swift-security-testing.mdmarkdown6.6 KB
references/swift-general/swift-security.mdmarkdown13.3 KB
references/swift/preferred-patterns.mdmarkdown2.4 KB
references/swift/swift-testing.mdmarkdown6.6 KB
references/swift/task-patterns.mdmarkdown3.6 KB
references/typescript-debugging.mdmarkdown9.3 KB
references/typescript-debugging/debugging-workflows-async-memory.mdmarkdown5.8 KB
references/typescript-debugging/debugging-workflows.mdmarkdown5.6 KB
scripts/bench-compare.shscript7.1 KB
scripts/check-errors.shscript7.1 KB
scripts/check-interface-compliance.shscript6.4 KB
scripts/check-sapcc-auth-ordering.shscript5.5 KB
scripts/check-sapcc-httptest.shscript4.4 KB
scripts/check-sapcc-identify-endpoint.shscript5.8 KB
scripts/check-sapcc-json-strict.shscript4.9 KB
scripts/check-sapcc-time-now.shscript4.2 KB
scripts/check-sapcc-todo-format.shscript4.1 KB
scripts/gen-table-test.shscript4.2 KB
scripts/quality_checker.pyscript16.2 KB
scripts/sync-google-style-guide.pyscript2.5 KB
scripts/validate.pyscript6.3 KB

references/mcp-local-docs.md

View on GitHub
---
description: "Building MCP servers for local documentation access in TypeScript/Node.js and Go: JSON-RPC 2.0, Hugo front matter, indexing, caching, docs:// URIs."
type: reference
---

# MCP Local Docs Servers

Rules for protocol-compliant, efficient MCP servers that give local access to
documentation.

Not for: using existing MCP tools or servers (only building local-docs MCP
servers); web performance or LCP optimization (use the `frontend` skill);
writing the documentation content, API references, or runbooks (use the
`writing` skill).

## Expertise areas

- **MCP protocol:** JSON-RPC 2.0, resource management, tool schemas, server
  lifecycle.
- **Documentation parsing:** Hugo front matter (YAML/TOML), markdown
  processing, metadata normalization.
- **Server architecture:** TypeScript/Node.js and Go implementations,
  performance, error handling.
- **File system:** efficient traversal, change detection, concurrent access.

## Hard rules

- **Read the file before editing.** Never edit a file you have not read in this
  session.
- **Run build and tests before reporting completion:** `npm run build`
  (TypeScript) or `go build ./...` (Go). Show the actual output, not "build
  succeeds".
- **Feature branch, never main.** If on main, create a branch before committing.
- **Verify dependencies exist before importing them.** Check `package.json` for
  `@modelcontextprotocol/sdk` or `go.mod` for required modules.
- **JSON-RPC 2.0 compliance** for all protocol interactions, with proper
  request/response structures.
- **Standard MCP methods only** (`resources/list`, `resources/read`,
  `tools/call`); no custom extensions.
- **Indexing budget:** initial indexing of 1000+ files completes within 30
  seconds.
- **Validate Hugo front matter** (YAML/TOML) before parsing, so bad files cannot
  crash the server.

## Defaults (on unless disabled)

- In-memory cache of parsed docs, invalidated by file modification time.
- Incremental indexing: after the initial load, re-parse only files whose mtime
  changed.
- Graceful degradation: return partial results with error metadata when some
  files fail to parse.
- Strip Hugo shortcodes and internal links from returned content.

## Off unless requested

- Full-text search index (only when a `search_docs` tool is requested).
- Cross-reference resolution of internal doc links.
- Content summarization for long documents.
- Watch mode with hot reload (development mode only).

## Scope

In scope:

- TypeScript/Node.js MCP servers using `@modelcontextprotocol/sdk`.
- Go MCP servers with standard-library patterns.
- Hugo front matter parsing (YAML and TOML) with validation.
- Efficient indexing (1000+ files in under 30 s).
- MCP tools for search and filtering.
- Large documentation repositories with caching.
- Graceful error handling and partial results.

Out of scope (explain the limit and suggest an alternative):

- **Extending the MCP protocol:** standard methods only.
- **Real-time sync:** indexing is incremental by mtime, not instant file watch.
- **Non-Hugo content:** specialized for Hugo documentation structure.
- **Encrypted content:** plain-text markdown only.

## Output format (Implementation Schema)

```markdown
## Analysis
[What the current state is and what needs to be implemented]

## Implementation Plan
[Step-by-step approach]

## Changes Made
[Actual file modifications with paths and descriptions]

## Verification Steps
[How to test the implementation]

## Next Steps
[What remains or follow-up tasks]
```

## Implementation patterns

Server scaffolding for TypeScript/Node.js (`DocsServer` class with `Server`,
`StdioServerTransport`, handler setup, `run()`) and Go (`DocsServer` struct with
`sync.RWMutex`, `IndexDocs()` via `filepath.WalkDir`) is in
[server-templates.md](mcp-local-docs/server-templates.md).

Key patterns: async file I/O only (no `readFileSync`); index once at startup,
then serve from a `Map`; use the `docs://` URI scheme (never expose filesystem
paths); wrap front matter parsing in try-catch.

## Reference loading table

| Signal | Load |
|------|------|
| Scaffolding a new server, TypeScript DocsServer class, Go DocsServer struct | [server-templates.md](mcp-local-docs/server-templates.md) |
| MCP server development, tool registration, SDK patterns | [mcp-patterns.md](mcp-local-docs/mcp-patterns.md) |
| Front matter parsing failures, URI issues, shortcode bugs, detection commands | [mcp-preferred-patterns.md](mcp-local-docs/mcp-preferred-patterns.md) |
| Async file I/O, concurrency, EMFILE errors, slow indexing | [typescript-async-patterns.md](mcp-local-docs/typescript-async-patterns.md) |

## Errors

### Front matter parsing failure

**Cause:** invalid YAML/TOML in a markdown file.
**Fix:** wrap parsing in try-catch; log a warning with the file path; continue
indexing the rest; return a partial index with error metadata.

### Slow indexing on a large repository

**Cause:** too many files or inefficient parsing.
**Fix:** profile indexing; parse files in parallel with a concurrency limit; add
mtime-based caching; consider incremental indexing.

### MCP client connection timeout

**Cause:** initial indexing takes too long.
**Fix:** reduce indexing scope temporarily; index in the background; return
partial results while indexing continues; report indexing progress.

## Blockers

Resolve routine issues from repository evidence and existing authorization. When
sure, decide, record the assumption in the report, and continue; ask Jev when
genuinely unsure. Ask only when these situations leave a material decision
uncovered. Rows marked **(owner)** guard production, destructive, credential,
public-exposure, or persistence actions: get explicit owner confirmation first.

| Situation | Why stop | Ask |
|-----------|----------|-----|
| Custom MCP methods requested | Protocol violation | "Standard MCP methods or a workaround using tools?" |
| Non-Hugo documentation format | Out of scope | "Is this Hugo-based docs? If not, a different parser is needed." |
| Authentication/encryption needed **(owner)** | Security scope | "What auth mechanism? MCP doesn't specify one." |
| Real-time sync required | Architecture change | "Real-time vs incremental indexing: what latency is tolerable?" |

Decide explicitly before acting on: authentication for doc access (owner
confirms), custom protocol extensions, performance requirements (indexing and
response time), and documentation structure assumptions (Hugo vs other).

## Rationalizations to reject

| Rationalization | Why it's wrong | Required action |
|-----------------|----------------|-----------------|
| "Custom MCP method is cleaner" | Breaks protocol compliance; clients won't support it | Standard methods + tools |
| "Sync file reading is fine for small docs" | Blocks the event loop; scales poorly | Always async |
| "Re-parsing is simpler than caching" | Destroys performance at scale | Cache from the start |
| "File paths in URIs are convenient" | Security risk; not portable | Custom URI scheme |

## Related skills

- `testing` for TDD, E2E, and verification.
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: 470kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexUnverifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall