From ef951a19133601d55c0afa609815209235350731 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Mon, 12 Oct 2026 22:22:09 +0530 Subject: [PATCH] use docs:// instead of doc:// to maintain parity with other mcp docs --- standards/mcp/modules/build_recipe.json | 2 +- standards/mcp/modules/library_registry.json | 2 +- standards/mcp/nav.json | 24 ++++++++++----------- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/standards/mcp/modules/build_recipe.json b/standards/mcp/modules/build_recipe.json index 415bcec..289a526 100644 --- a/standards/mcp/modules/build_recipe.json +++ b/standards/mcp/modules/build_recipe.json @@ -2,7 +2,7 @@ "module": "build_recipe", "content": { "path": "build_recipe", - "docstring": "# Build Recipe\n\n## Summary\n\nThe ordered, deterministic checklist for generating a new application of the\nstandard shape. Every step is fixed; only the resource model (step 2) and the\npipeline family (step 7) need app-specific authoring.\n\nThis page is served by the `standards` MCP as `doc://modules/build_recipe`. The\n`start_app` prompt on that server collects the two axes and hands off here; pull\nexact files with `get_app_component`.\n\n---\n\n## πŸš€ Bootstrap\n\nFrom the standards docs checkout:\n\n```bash\ncp -r /standards/src/templates/app apps/\ncd apps/\n```\n\nInstall the internal libraries β€” editable local checkouts (preferred in\ndevelopment) or the private index (CI / fresh machines). Credentials are\nenvironment-only; never commit them.\n\n```bash\n# local checkouts\npip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa \\\n -e ../aetos/dagpipe -e ../aetos/doc-forge\n# private index\npip install --extra-index-url \\\n \"https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple\" .\n```\n\n---\n\n## πŸ“‹ Agent prompt (copyable)\n\n````markdown\n# Build a new application from the Aetos Standards blueprint\n\nYou are coding a complete new backend application conforming to the Aetos\nstandard app blueprint. Execute every step in order. Only steps 2 and 3 use the\napp-specific details provided by the user; everything else is deterministic.\n\n## Before writing any code\n\nConnect to the `standards` MCP server and read:\n- `doc://nav` (the module list)\n- `doc://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)\n- `doc://modules/layering_rules` (the dependency rules)\n\nThen:\n- call `find_library` with `db`, `di`, `routing`, `ingestion`, `pipeline`, `docs`\n and note the Tier A libraries that already exist β€” never reimplement one;\n- call `list_app_components()` and pull each file you need with\n `get_app_component(kind, resource=..., family=...)` instead of writing it from\n scratch.\n\n## Steps\n\n1. **Scaffold** β€” copy `standards/src/templates/app/` into `apps//`.\n Keep the tree: `domain/`, `infra/`, `interfaces/`, `pipelines/`, `tests/`,\n `scripts/`, plus `pyproject.toml`, `openapi.yaml`, `config.py`, `init.py`,\n `main.py`, `worker.py`, `Dockerfile`, `docker-compose.yaml`, `.env.example`.\n\n2. **Author the spec (app-specific)** β€” write `openapi.yaml`: resources,\n schemas, `operationId`s, security, and extension metadata. This is the\n contract and drives all routing.\n\n3. **Write each CRUD slice (app-specific)** β€” per resource create the four-file\n slice: `models.py`, `ports/db.py`, `ports/service.py`, and optional\n `converters.py`. Follow the CRUD template.\n\n4. **Wire the composition root** β€” in `init.py`, build leaf repositories, then\n dependent repositories, then services; add infra adapters (db, cache, stores,\n progress bus, fetchers). Expose `get_svc` overloads.\n\n5. **Add routes** β€” create `interfaces//routes.py` thin handlers bound\n to `operationId`s and re-export them in `interfaces/openapi.py`. Add the cache\n decorator to read endpoints.\n\n6. **Bootstrap app and worker** β€” confirm `main.py` runs the OpenAPI-first app\n with its lifespan. If the app has long-running jobs, adapt `worker.py` to poll\n the job collection, run the pipeline, and publish progress.\n\n7. **Add pipeline families (only if data-driven)** β€” copy `pipelines/example/`\n to `pipelines//` with `abc.py`, `impl.py`, `pipeline.yaml`,\n `resources/`, and reuse `pipelines/shared/` (loader + registry). Register the\n root. Add fixtures and a parity test.\n\n8. **Add infrastructure only where needed** β€” Tier A capability: use the\n library. Tier B capability: copy the template. Never hand-write a Tier A\n library.\n\n9. **Tests** β€” integration tests with fakes at the HTTP edge; unit tests for\n domain and pipeline logic; a config-consistency test for rule-driven\n pipelines.\n\n10. **Scripts and seeds** β€” operator scripts under `scripts/` using\n `init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.`.\n\n11. **Docs** β€” author GSDFC docstrings, generate `.pyi` stubs, mark the package\n `py.typed`, and build the docs.\n\n**Definition of done:**\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves every operation in the spec; the worker drains its queue.\n- No domain module imports a web framework.\n- No Tier A library was reimplemented.\n````\n\n---\n\n## 🧭 Where the steps land\n\nThe steps map onto the layers as follows:\n\n| Step | Package / file | Depends on |\n|---------------------|-----------------------------------|---------------------------------------------|\n| 1 Β· Scaffold | whole `templates/app/` | β€” |\n| 2 Β· Spec | `openapi.yaml` | β€” |\n| 3 Β· CRUD slices | `domain//` | spec, CRUD template |\n| 4 Β· Wiring | `init.py` | every slice |\n| 5 Β· Routes | `interfaces//` | services, openapi route registry |\n| 6 Β· Bootstrap | `main.py`, `worker.py` | composition root |\n| 7 Β· Pipelines | `pipelines//`, `shared/` | library pipeline engine |\n| 8 Β· Infra | `infra/` | domain ports |\n| 9 Β· Tests | `tests/` | app + fixtures |\n| 10 Β· Scripts | `scripts/` | composition root |\n| 11 Β· Docs | docstrings + docs build | code, Doc Forge |\n\n---\n\n## ⚠️ Definition of done\n\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves the spec's operations; the worker drains its queue.\n- No domain module imports a web framework.\n- No Tier A library was reimplemented.\n\n---\n\n## Related\n\n- [02 – Layering Rules](02_layering_rules.md) Β· [05 – CRUD Template](05_crud_template.md) Β· [06 – Pipeline Scaffold](06_pipeline_scaffold.md) Β· [12 – Genericity Matrix](12_genericity_matrix.md)\n", + "docstring": "# Build Recipe\n\n## Summary\n\nThe ordered, deterministic checklist for generating a new application of the\nstandard shape. Every step is fixed; only the resource model (step 2) and the\npipeline family (step 7) need app-specific authoring.\n\nThis page is served by the `standards` MCP as `docs://modules/build_recipe`. The\n`start_app` prompt on that server collects the two axes and hands off here; pull\nexact files with `get_app_component`.\n\n---\n\n## πŸš€ Bootstrap\n\nFrom the standards docs checkout:\n\n```bash\ncp -r /standards/src/templates/app apps/\ncd apps/\n```\n\nInstall the internal libraries β€” editable local checkouts (preferred in\ndevelopment) or the private index (CI / fresh machines). Credentials are\nenvironment-only; never commit them.\n\n```bash\n# local checkouts\npip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa \\\n -e ../aetos/dagpipe -e ../aetos/doc-forge\n# private index\npip install --extra-index-url \\\n \"https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple\" .\n```\n\n---\n\n## πŸ“‹ Agent prompt (copyable)\n\n````markdown\n# Build a new application from the Aetos Standards blueprint\n\nYou are coding a complete new backend application conforming to the Aetos\nstandard app blueprint. Execute every step in order. Only steps 2 and 3 use the\napp-specific details provided by the user; everything else is deterministic.\n\n## Before writing any code\n\nConnect to the `standards` MCP server and read:\n- `docs://nav` (the module list)\n- `docs://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)\n- `docs://modules/layering_rules` (the dependency rules)\n\nThen:\n- call `find_library` with `db`, `di`, `routing`, `ingestion`, `pipeline`, `docs`\n and note the Tier A libraries that already exist β€” never reimplement one;\n- call `list_app_components()` and pull each file you need with\n `get_app_component(kind, resource=..., family=...)` instead of writing it from\n scratch.\n\n## Steps\n\n1. **Scaffold** β€” copy `standards/src/templates/app/` into `apps//`.\n Keep the tree: `domain/`, `infra/`, `interfaces/`, `pipelines/`, `tests/`,\n `scripts/`, plus `pyproject.toml`, `openapi.yaml`, `config.py`, `init.py`,\n `main.py`, `worker.py`, `Dockerfile`, `docker-compose.yaml`, `.env.example`.\n\n2. **Author the spec (app-specific)** β€” write `openapi.yaml`: resources,\n schemas, `operationId`s, security, and extension metadata. This is the\n contract and drives all routing.\n\n3. **Write each CRUD slice (app-specific)** β€” per resource create the four-file\n slice: `models.py`, `ports/db.py`, `ports/service.py`, and optional\n `converters.py`. Follow the CRUD template.\n\n4. **Wire the composition root** β€” in `init.py`, build leaf repositories, then\n dependent repositories, then services; add infra adapters (db, cache, stores,\n progress bus, fetchers). Expose `get_svc` overloads.\n\n5. **Add routes** β€” create `interfaces//routes.py` thin handlers bound\n to `operationId`s and re-export them in `interfaces/openapi.py`. Add the cache\n decorator to read endpoints.\n\n6. **Bootstrap app and worker** β€” confirm `main.py` runs the OpenAPI-first app\n with its lifespan. If the app has long-running jobs, adapt `worker.py` to poll\n the job collection, run the pipeline, and publish progress.\n\n7. **Add pipeline families (only if data-driven)** β€” copy `pipelines/example/`\n to `pipelines//` with `abc.py`, `impl.py`, `pipeline.yaml`,\n `resources/`, and reuse `pipelines/shared/` (loader + registry). Register the\n root. Add fixtures and a parity test.\n\n8. **Add infrastructure only where needed** β€” Tier A capability: use the\n library. Tier B capability: copy the template. Never hand-write a Tier A\n library.\n\n9. **Tests** β€” integration tests with fakes at the HTTP edge; unit tests for\n domain and pipeline logic; a config-consistency test for rule-driven\n pipelines.\n\n10. **Scripts and seeds** β€” operator scripts under `scripts/` using\n `init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.`.\n\n11. **Docs** β€” author GSDFC docstrings, generate `.pyi` stubs, mark the package\n `py.typed`, and build the docs.\n\n**Definition of done:**\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves every operation in the spec; the worker drains its queue.\n- No domain module imports a web framework.\n- No Tier A library was reimplemented.\n````\n\n---\n\n## 🧭 Where the steps land\n\nThe steps map onto the layers as follows:\n\n| Step | Package / file | Depends on |\n|---------------------|-----------------------------------|---------------------------------------------|\n| 1 Β· Scaffold | whole `templates/app/` | β€” |\n| 2 Β· Spec | `openapi.yaml` | β€” |\n| 3 Β· CRUD slices | `domain//` | spec, CRUD template |\n| 4 Β· Wiring | `init.py` | every slice |\n| 5 Β· Routes | `interfaces//` | services, openapi route registry |\n| 6 Β· Bootstrap | `main.py`, `worker.py` | composition root |\n| 7 Β· Pipelines | `pipelines//`, `shared/` | library pipeline engine |\n| 8 Β· Infra | `infra/` | domain ports |\n| 9 Β· Tests | `tests/` | app + fixtures |\n| 10 Β· Scripts | `scripts/` | composition root |\n| 11 Β· Docs | docstrings + docs build | code, Doc Forge |\n\n---\n\n## ⚠️ Definition of done\n\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves the spec's operations; the worker drains its queue.\n- No domain module imports a web framework.\n- No Tier A library was reimplemented.\n\n---\n\n## Related\n\n- [02 – Layering Rules](02_layering_rules.md) Β· [05 – CRUD Template](05_crud_template.md) Β· [06 – Pipeline Scaffold](06_pipeline_scaffold.md) Β· [12 – Genericity Matrix](12_genericity_matrix.md)\n", "objects": {} } } \ No newline at end of file diff --git a/standards/mcp/modules/library_registry.json b/standards/mcp/modules/library_registry.json index 91684d2..738af31 100644 --- a/standards/mcp/modules/library_registry.json +++ b/standards/mcp/modules/library_registry.json @@ -2,7 +2,7 @@ "module": "library_registry", "content": { "path": "library_registry", - "docstring": "# Library Registry\n\n## Summary\n\nThe Aetos ecosystem provides internal libraries for the shared concerns of\nevery application. **Use them.** Writing a private copy of any capability below\nis a defect.\n\nEach library also exposes its own documentation as an MCP server. An AI agent\ncan read a library's full API by connecting to its MCP and reading\n`doc://index`, `doc://nav`, and `doc://modules/{module}`.\n\n---\n\n## Catalog\n\n| Library | Import | Purpose | Use instead of | MCP |\n|---|---|---|---|---|\n| DAG Pipe | `dagpipe` | Deterministic state-transformation DAG engine | hand-rolled orchestration/topological ordering | `:8006` |\n| Hexa | `hexa` | Declarative DI / composition-root tooling | manual wiring, hand-written factories | `:8008` |\n| Mongo Ops | `mongo_ops` | Async MongoDB repositories, cache, populate, transactions | raw Motor CRUD and connection lifecycle | `:8007` |\n| Omniread | `omniread` | Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) | custom scrapers/parsers | `:8003` |\n| OpenAPI First | `openapi_first` | Spec-first FastAPI bootstrap, client, codegen | decorator routers and hand-written clients | `:8004` |\n| Mail Intake | `mail_intake` | Provider-agnostic read-only email ingestion | Gmail OAuth + MIME parsing | `:8002` |\n| Py JWT | `jwtlib` | JWT auth primitives (register/login/introspect) | password hashing + token code | `:8005` |\n| Doc Forge | `docforge` | Docstring compiler β†’ MkDocs + MCP docs | custom doc generators | `:8001` |\n| Auth Server | *(service)* | Central identity service (register/login/me/introspect) | building auth endpoints yourself | *(deferred)* |\n\n## How to choose\n\n| You need to… | Use |\n|---|---|\n| persist and query documents | Mongo Ops |\n| compose dependencies | Hexa |\n| run a multi-step transformation | DAG Pipe |\n| read/parse an arbitrary input format | Omniread |\n| expose a contract-first HTTP API | OpenAPI First |\n| ingest email | Mail Intake |\n| authenticate users / verify tokens | Py JWT (+ Auth Server) |\n| generate documentation | Doc Forge |\n\n## Discovery\n\nA single **standards MCP** exposes `find_library(capability)`, which returns the\nmatching library, its import name, its \"use instead of\" guidance, and its MCP\nendpoint. Query it before writing any infrastructure.\n\n## Notes\n\n- **Hexa** is a full library with its own MCP server on `:8008`: read\n `doc://index`, `doc://nav`, and `doc://modules/{module}` (e.g.\n `doc://modules/hexa.container`) to discover the DI surface β€” `build(cls, *,\n instances, config)` and the `PortNode` model.\n- **Auth Server** is deferred: it has no `pyproject.toml`/importable package and\n no MCP bundle. Do not reach for it yet; `py-jwt` covers token primitives.\n- Library MCP servers expose **documentation resources** (not executable tools):\n they tell an agent the available API surface so it does not invent code.\n", + "docstring": "# Library Registry\n\n## Summary\n\nThe Aetos ecosystem provides internal libraries for the shared concerns of\nevery application. **Use them.** Writing a private copy of any capability below\nis a defect.\n\nEach library also exposes its own documentation as an MCP server. An AI agent\ncan read a library's full API by connecting to its MCP and reading\n`docs://index`, `docs://nav`, and `docs://modules/{module}`.\n\n---\n\n## Catalog\n\n| Library | Import | Purpose | Use instead of | MCP |\n|---|---|---|---|---|\n| DAG Pipe | `dagpipe` | Deterministic state-transformation DAG engine | hand-rolled orchestration/topological ordering | `:8006` |\n| Hexa | `hexa` | Declarative DI / composition-root tooling | manual wiring, hand-written factories | `:8008` |\n| Mongo Ops | `mongo_ops` | Async MongoDB repositories, cache, populate, transactions | raw Motor CRUD and connection lifecycle | `:8007` |\n| Omniread | `omniread` | Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) | custom scrapers/parsers | `:8003` |\n| OpenAPI First | `openapi_first` | Spec-first FastAPI bootstrap, client, codegen | decorator routers and hand-written clients | `:8004` |\n| Mail Intake | `mail_intake` | Provider-agnostic read-only email ingestion | Gmail OAuth + MIME parsing | `:8002` |\n| Py JWT | `jwtlib` | JWT auth primitives (register/login/introspect) | password hashing + token code | `:8005` |\n| Doc Forge | `docforge` | Docstring compiler β†’ MkDocs + MCP docs | custom doc generators | `:8001` |\n| Auth Server | *(service)* | Central identity service (register/login/me/introspect) | building auth endpoints yourself | *(deferred)* |\n\n## How to choose\n\n| You need to… | Use |\n|---|---|\n| persist and query documents | Mongo Ops |\n| compose dependencies | Hexa |\n| run a multi-step transformation | DAG Pipe |\n| read/parse an arbitrary input format | Omniread |\n| expose a contract-first HTTP API | OpenAPI First |\n| ingest email | Mail Intake |\n| authenticate users / verify tokens | Py JWT (+ Auth Server) |\n| generate documentation | Doc Forge |\n\n## Discovery\n\nA single **standards MCP** exposes `find_library(capability)`, which returns the\nmatching library, its import name, its \"use instead of\" guidance, and its MCP\nendpoint. Query it before writing any infrastructure.\n\n## Notes\n\n- **Hexa** is a full library with its own MCP server on `:8008`: read\n `docs://index`, `docs://nav`, and `docs://modules/{module}` (e.g.\n `docs://modules/hexa.container`) to discover the DI surface β€” `build(cls, *,\n instances, config)` and the `PortNode` model.\n- **Auth Server** is deferred: it has no `pyproject.toml`/importable package and\n no MCP bundle. Do not reach for it yet; `py-jwt` covers token primitives.\n- Library MCP servers expose **documentation resources** (not executable tools):\n they tell an agent the available API surface so it does not invent code.\n", "objects": {} } } \ No newline at end of file diff --git a/standards/mcp/nav.json b/standards/mcp/nav.json index 5b0b62b..124f7bf 100644 --- a/standards/mcp/nav.json +++ b/standards/mcp/nav.json @@ -1,62 +1,62 @@ [ { "module": "build_recipe", - "resource": "doc://modules/build_recipe", + "resource": "docs://modules/build_recipe", "title": "Build Recipe" }, { "module": "layering_rules", - "resource": "doc://modules/layering_rules", + "resource": "docs://modules/layering_rules", "title": "Layering Rules" }, { "module": "composition_root", - "resource": "doc://modules/composition_root", + "resource": "docs://modules/composition_root", "title": "Composition Root" }, { "module": "spec_first_routing", - "resource": "doc://modules/spec_first_routing", + "resource": "docs://modules/spec_first_routing", "title": "Spec-First Routing" }, { "module": "crud_template", - "resource": "doc://modules/crud_template", + "resource": "docs://modules/crud_template", "title": "CRUD Template" }, { "module": "pipeline_scaffold", - "resource": "doc://modules/pipeline_scaffold", + "resource": "docs://modules/pipeline_scaffold", "title": "Pipeline Scaffold" }, { "module": "worker_and_progress", - "resource": "doc://modules/worker_and_progress", + "resource": "docs://modules/worker_and_progress", "title": "Worker & Progress" }, { "module": "human_in_loop", - "resource": "doc://modules/human_in_loop", + "resource": "docs://modules/human_in_loop", "title": "Human-in-the-Loop" }, { "module": "infra_adaptors", - "resource": "doc://modules/infra_adaptors", + "resource": "docs://modules/infra_adaptors", "title": "Infra Adapters" }, { "module": "genericity_matrix", - "resource": "doc://modules/genericity_matrix", + "resource": "docs://modules/genericity_matrix", "title": "Genericity Matrix" }, { "module": "library_registry", - "resource": "doc://modules/library_registry", + "resource": "docs://modules/library_registry", "title": "Library Registry" }, { "module": "index", - "resource": "doc://modules/index", + "resource": "docs://modules/index", "title": "Standards Reference" } ] \ No newline at end of file