Skip to content

blueprint.md

Latest commit

 

History

History
91 lines (65 loc) · 3.16 KB

blueprint.md

File metadata and controls

91 lines (65 loc) · 3.16 KB
Raw

Blueprint

Goal

mcp-saas-foundry should feel like a serious starter, not just a note dump. The repository needs to answer four questions clearly:

  1. What does a production-minded SaaS MCP server repo look like?
  2. Where do transport, provider adapters, and tool contracts live?
  3. What minimum operational and security rules should every starter inherit?
  4. How does a maintainer go from blueprint to publishable repository without improvising structure?

Reference Shape

.
├── docs/
│   ├── blueprint.md
│   ├── checklist.md
│   └── roadmap.md
├── examples/
│   ├── github-issues/
│   └── internal-rest/
├── src/
│   ├── blueprint.mjs
│   └── plan.mjs
├── templates/
│   └── node-starter/
└── test/
    └── blueprint.test.mjs

Core Boundaries

1. Repo Guidance Lives in docs/

The starter should define architecture, release expectations, and implementation gates in markdown first. Teams need a shared definition of "starter quality" before adding SDK-specific code.

2. Copyable Starter Lives in templates/

templates/node-starter/ is the handoff point from planning to execution. It should stay dependency-light, readable, and safe to fork. The template should include:

  • config loading and env naming conventions
  • a manifest or service description module
  • provider adapter boundaries for upstream APIs
  • tool modules with clear naming and input ownership
  • smoke tests for starter invariants

3. Domain Mappings Live in examples/

Examples should not be full products. They should show how real surfaces map onto the starter:

  • public SaaS with scopes, pagination, and user-facing tool names
  • internal APIs with narrower blast radius and stronger governance notes

4. Preview Tooling Lives in src/

The root script should stay lightweight and dependency-free. Its job is to make the blueprint inspectable from the terminal, not to become a framework.

File Ownership Rules

  • docs/ owns architecture guidance, release stages, and definition-of-done content.
  • templates/ owns copyable starter files only.
  • examples/ owns adaptation patterns and sample tool catalogs.
  • src/ owns repo preview scripts and other lightweight helper logic.
  • test/ owns verification for root-level scripts and blueprint integrity.

Starter Expectations

Every starter derived from this repo should eventually include:

  • explicit auth and scope handling rules
  • tool names that reflect business nouns and actions
  • pagination, rate-limit, and retry policies
  • observability hooks for request tracing and support debugging
  • release metadata, onboarding notes, and smoke tests

Non-Goals

This repo should not try to be:

  • a monolithic framework
  • an SDK replacement
  • a giant catalog of every SaaS connector pattern
  • a dependency-heavy demo app

Recommended Adoption Flow

  1. Review this blueprint and remove any starter pieces you do not need.
  2. Fork or copy templates/node-starter/ into a new repository.
  3. Pick the closest example under examples/ and map your real tool surface against it.
  4. Use docs/checklist.md to harden the result before publishing.