AeonDave MCP Patterns
Local-first guidance for building MCP servers without turning the protocol surface into a bag of random decorators.
When to activate
- Building a new local MCP server, mainly in Python
- Refactoring an MCP server that mixed protocol glue with business logic
- Deciding whether a feature should be a tool, resource, prompt, root-aware flow, or sampling-assisted path
- Wiring a server into Claude Desktop or another local MCP host
- Debugging transport, lifecycle, capability, or host-integration issues
- Preparing a local server for packaging or distribution
Outcome expectations
- The server uses the official MCP Python SDK as the default path.
- Protocol choices are explicit: tools vs resources vs prompts, stdio vs local HTTP, baseline vs optional capabilities.
- Local integrations are secure by default: least privilege, absolute paths, no stdout logging on stdio.
- Testing starts with Inspector, then a local client harness, then the target host.
- Packaging happens only after the manual local workflow is already stable.
Core patterns
- Prefer the official
mcpPython SDK and explicit imports such asfrom mcp.server.fastmcp import FastMCP. - Keep business logic separate from MCP wrappers. The protocol layer should mostly validate inputs, call helpers, and shape outputs.
- Start with stdio unless you have a concrete reason to run a local HTTP service.
- Use tools for actions and parameterized computation, resources for read-only context, and prompts for reusable user-invoked workflows.
- Treat roots and sampling as optional, capability-gated features. Do not make a basic local server depend on them.
- For stdio servers, never write logs to stdout.
- Optimize for agent cognition: search/filter over dump-all, concise outputs first, rich details on demand.
- Pair with
python-patternsfor broader Python code quality, and withsystematic-debuggingwhen the failure source is unclear.
Recommended workflow
- Load references/architecture.md to lock in the host/client/server mental model.
- Load references/python-local-servers.md for the official Python baseline and project skeleton.
- Load the specific capability reference you need:
- references/tools.md
- references/resources.md
- references/prompts.md
- Load references/lifecycle-capabilities.md and references/transports.md when wiring or debugging protocol behavior.
- Load references/local-host-integration.md before connecting the server to Claude Desktop or a similar host.
- Load references/debugging-testing.md before guessing at failures.
- Load references/security-boundaries.md before exposing broader local access, switching to HTTP, or preparing distribution.
- Load references/packaging-distribution.md only after the server works locally.
- Load references/server-instructions.md only if the server has cross-tool workflows that tool descriptions alone do not communicate well.
Reference map
| Topic | File | Load when |
|---|---|---|
| Roles and control model | references/architecture.md | You need the host/client/server mental model or primitive-selection rules |
| Python baseline | references/python-local-servers.md | You are creating the project, server skeleton, or local client harness |
| Lifecycle and capabilities | references/lifecycle-capabilities.md | initialize, capability negotiation, notifications, errors, cancellation |
| Transports | references/transports.md | Choosing stdio vs local HTTP or debugging transport-specific failures |
| Tools | references/tools.md | Designing callable capabilities, schemas, outputs, and tool errors |
| Resources | references/resources.md | Designing read-only context, URI templates, MIME types, annotations |
| Prompts | references/prompts.md | Building reusable prompt templates or prompt-returning workflows |
| Roots | references/roots.md | Consuming client-provided workspace or path scope safely |
| Sampling | references/sampling.md | Considering server-initiated model calls or sampling callbacks |
| Host wiring | references/local-host-integration.md | Registering and launching the server from a desktop host |
| Debugging and tests | references/debugging-testing.md | Inspector, logs, local harnesses, capability mismatch diagnosis |
| Security | references/security-boundaries.md | Least privilege, local-server compromise, auth/session pitfalls |
| Packaging | references/packaging-distribution.md | Moving from local dev to portable distribution |
| Server instructions | references/server-instructions.md | Adding concise workflow guidance beyond tool descriptions |
Resources
Load the minimum reference file that matches the current task. Keep SKILL.md as the navigation layer; keep the heavy detail in references/.