MCP Skills

A production-oriented Skill for AI agents that design, implement, audit, secure, test, troubleshoot, and publish Model Context Protocol systems.

mcp-skills turns broad requests such as “build an MCP server for this API” into explicit protocol contracts, primitive schemas, threat models, implementation plans, test matrices, deployment decisions, and repository-ready artifacts. It is designed for ChatGPT Skills, Claude Skills, coding agents, and other filesystem-aware agent runtimes.

What it covers

• MCP host, client, and server architecture
• Protocol lifecycle and capability negotiation
• Tools, resources, resource templates, prompts, roots, sampling, elicitation, logging, completion, and notifications
• Standard stdio and Streamable HTTP transports
• OAuth-based authorization, identity propagation, tenancy, and policy enforcement
• Tool and resource JSON Schema contracts
• Confirmation, idempotency, timeout, cancellation, retry, pagination, and error semantics
• Token passthrough, SSRF, session hijacking, confused-deputy, DNS rebinding, and prompt/tool injection defenses
• Official SDK implementation planning across TypeScript, Python, Go, C#, Java, Rust, and other supported ecosystems
• MCP Inspector, contract tests, negative tests, client compatibility matrices, and conformance evidence
• Registry metadata, server.json planning, packaging, release, observability, scaling, and operational runbooks
• Experimental extensions such as Tasks and MCP Apps, with explicit capability checks and fallbacks

Primary outputs

The Skill can generate:

1. MCP server architecture report
2. MCP Server Blueprint JSON
3. Tool Manifest JSON
4. Primitive contract catalog
5. Authorization and threat-model specification
6. SDK implementation plan or repository scaffold specification
7. Test and client-compatibility matrix
8. Deployment and operations runbook
9. Registry and release checklist
10. Audit or troubleshooting report

Repository layout

mcp-skills/
├── SKILL.md
├── agents/openai.yaml
├── references/
├── scripts/
└── assets/

examples/
├── prompts.md
├── mcp-server-blueprint.json
└── tool-manifest.json

tests/
tools/
docs/
.github/
dist/

Install the Skill

Download dist/skill.zip from this repository or from a GitHub Release, then add it to a compatible Skills interface.

The ZIP contains one Skill entrypoint:

mcp-skills/SKILL.md

Validate the bundled examples

python mcp-skills/scripts/validate_mcp_server_blueprint.py examples/mcp-server-blueprint.json
python mcp-skills/scripts/validate_tool_manifest.py examples/tool-manifest.json

Audit an MCP repository

python mcp-skills/scripts/audit_mcp_package.py /path/to/mcp-repository

The audit performs deterministic static checks for repository health files, possible secrets, unresolved placeholders, large files, transport documentation, authorization posture, timeouts, and schema references. It is a guardrail, not a substitute for protocol conformance or security testing.

Package the Skill locally

python tools/validate_skill.py mcp-skills
python tools/package_skill.py mcp-skills dist

The packager creates dist/skill.zip and refuses invalid Skill metadata.

Example prompts

Design a remote multi-tenant MCP server for our project API. Include tools,
resources, OAuth scopes, a threat model, a client matrix, and an implementation
plan. Return both Markdown and MCP Server Blueprint JSON.

Audit this MCP repository for protocol, schema, transport, authorization,
tenancy, security, testing, and operational gaps. Separate verified findings
from assumptions and produce a prioritized remediation plan.

See examples/prompts.md for more.

Design principles

• Verify the active MCP specification revision and SDK version before implementation.
• Use protocol primitives according to their semantics; do not expose every operation as a tool.
• Prefer narrow, typed, bounded contracts over generic executor tools.
• Treat write, destructive, privileged, external-communication, and high-cost operations as distinct risk classes.
• Keep authorization at the object, tenant, and action level rather than trusting model intent.
• Never embed credentials or production identifiers in generated artifacts.
• Keep optional or experimental capabilities behind negotiation and documented fallbacks.
• Validate generated JSON before presenting it as implementation-ready.

Maintenance

Protocol and SDK details change. See docs/maintenance-guide.md for the source review and update process, and docs/release-checklist.md before publishing a release.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, keep claims grounded in primary MCP documentation or SDK sources, and include tests for validator changes.

Security

Do not report vulnerabilities in a public issue. Follow SECURITY.md.

License

MIT © AmirHesam Piri