@craft-ts/mcp 0.7.0-beta.13

package/README.md

@@ -0,0 +1,71 @@
+# @craft-ts/mcp
+
+MCP server, Agent Skills, and LLM entry points so a coding agent can use
+`@craft-ts/core` after you import it.
+
+This is the consumer-facing counterpart of the docs site. It does **not**
+replace the runtime registry / log MCP servers used inside the craft-ts
+monorepo.
+
+## Install
+
+```bash
+npm install -D @craft-ts/mcp@beta
+```
+
+Or run it without adding a dependency:
+
+```bash
+npx -y @craft-ts/mcp@beta
+```
+
+## Cursor / Claude Code / VS Code
+
+```json
+{
+  "mcpServers": {
+    "craft-ts": {
+      "command": "npx",
+      "args": ["-y", "@craft-ts/mcp@beta"]
+    }
+  }
+}
+```
+
+Commit that as `.mcp.json` at the app root so the whole team gets the tools.
+
+## Tools
+
+| Tool | Job |
+| --- | --- |
+| `get_best_practices` | Craft coding rules + `AGENTS.md` snippet |
+| `search_documentation` | Search the bundled Learn / Guide / Reference |
+| `get_documentation_page` | One page as markdown |
+| `find_examples` | Learn + demo example hits |
+| `list_skills` / `get_skill` | Agent Skills shipped in this package |
+| `get_llms_txt` | Public `llms.txt` / `llms-full.txt` URLs |
+
+## LLM files on the docs site
+
+- https://craft-ts.github.io/craft/llms.txt
+- https://craft-ts.github.io/craft/llms-full.txt
+- Every docs page also has a `.md` sibling (for example `/guide/state/local-state.md`)
+
+## Agent Skills
+
+Skills follow the [Agent Skills](https://agentskills.io/specification) layout
+and are packaged as an [Agent Plugin](https://agent-plugins.org/) (`plugin.json`
++ `mcp.json` + `skills/`):
+
+- `craft-ts-architecture-tests` — scaffold or run `architecture/`, freeze a graph smell
+- `craft-ts-routes` — type-safe `craftRoutes` files
+- `translate-spec-to-craft-ts` — map a spec onto primitives
+- `craft-ts-service-migration` — `craftService` / `toCraftService`
+- `migrate-to-craft-ts` — `craft-migrate` then manual follow-up
+
+Point your agent at `node_modules/@craft-ts/mcp/skills`, or copy the `AGENTS.md`
+snippet from `get_best_practices`.
+
+## Docs
+
+https://craft-ts.github.io/craft/resources/ai-agents

package/content/agents.md

@@ -0,0 +1,35 @@
+# CraftTS
+
+This application uses `@craft-ts/core` without an Angular dependency. Treat
+Craft APIs as the default. Use Craft primitives, services, components,
+`CraftHttpClient`, `startCraft` (or explicit `bootstrapCraft` / `hydrateCraft`),
+and `provideCraftRouter` in authored code.
+
+For SSR, use `renderCraft` to render one isolated request. On the browser,
+`startCraft` automatically hydrates Craft SSR HTML or mounts a fresh client tree.
+
+## Before writing Craft code
+
+1. Read https://craft-ts.github.io/craft/llms.txt and follow the linked markdown pages.
+2. If the CraftTS MCP server is configured, call `get_best_practices`, then `search_documentation` / `get_skill` instead of guessing APIs.
+3. Skills live in `node_modules/@craft-ts/mcp/skills/` (architecture tests, routes, spec translation, service migration, full-app migration).
+
+## Non-negotiable rules
+
+- `yield*` every Craft reader (`state`, `query.value()`, service helpers). Use `craftUse` only at synchronous boundaries such as tests.
+- One primitive family: `state` / `query` / `mutation` / `queryParams` / `asyncProcess`. Compose insertions with `craftPipe`.
+- `craftService` + generated `X()` helpers for explicit dependency composition.
+- `craftRoutes` + `componentDeps` + a per-file DI check. Split with `loadChildren` on `TS2589`.
+- Enable `@craft-ts/dev-tools` ESLint rules and run `eslint --fix` after DI or route edits.
+- The `architecture/` suite is the graph contract. `craft create` scaffolds it
+  at bootstrap and adds `npm run architecture`. Run it during a feature. Do not
+  add an architecture rule for the feature; encode a smell only when it is a
+  recurring product invariant not covered by a baseline helper.
+
+## Docs
+
+- Tutorial: https://craft-ts.github.io/craft/learn/
+- Guide: https://craft-ts.github.io/craft/guide/
+- API index: https://craft-ts.github.io/craft/reference/
+- Coding agents: https://craft-ts.github.io/craft/resources/ai-agents
+- Local dev: drive the open `ng serve` tab with the function-registry MCP tool `page` (https://craft-ts.github.io/craft/guide/ai/dev-page). That tool is not part of `@craft-ts/mcp`.

package/content/best-practices.md

@@ -0,0 +1,79 @@
+# CraftTS best practices for coding agents
+
+This guide is the contract for generating `@craft-ts/core` code in an
+application that already imported the library. Prefer Craft's functional and
+generator-based model throughout.
+
+Public docs: https://craft-ts.github.io/craft
+LLM index: https://craft-ts.github.io/craft/llms.txt
+Full dump: https://craft-ts.github.io/craft/llms-full.txt
+
+For a new framework-independent app, start with `npx craft create <directory>`.
+The prompt asks for EffectTS v4 first, then the agent integrations to install
+(`codex`, `cursor`, `cloud-code`; `claude-code` is also supported). The starter
+already contains a routed page, a `CraftHttpClient` API query, ESLint, unit and
+Playwright tests, and the `architecture/` contract. Use `--effect=v4` or
+`--effect=none` for non-interactive setup.
+
+When MCP tools are available, call `get_best_practices` once, then `search_documentation` / `get_skill` instead of inventing APIs.
+
+## Mental model
+
+- Declare with a name, `yield*` what you do not own, derive the rest.
+- One API shape for every kind of state: `state`, `query`, `mutation`, `queryParams`, `asyncProcess`.
+- Insertions compose behaviour (`insertForm`, `insertReactOnMutation`, `insertEntities`, persistence). A primitive takes **one** insertion. Compose with `craftPipe(context, a, b)`.
+- Services are factories (`craftService`), not classes.
+- Components are selectorless functions (`craftComponent`) with typed hyperscript, not `@Component` + HTML templates.
+
+## Which primitive
+
+| Need | Primitive |
+| --- | --- |
+| Local UI state you own | `state` |
+| Server read, refetch from reactive params | `query` |
+| Server write, triggered explicitly | `mutation` |
+| Shareable URL query-string state | `queryParams` |
+| One-off async job with lifecycle | `asyncProcess` |
+
+Decision page: `/guide/concepts/choose-primitive`.
+
+## Rules you must not break
+
+1. **`yield*` every Craft reader.** Primitive roots, insertions, `query.value()`, `query.status()`, service helpers. Do not call a reader as a function to unwrap it. In tests and other synchronous boundaries use `craftUse(reader())`.
+2. **Keep reactive state inside Craft primitives.** Use `state`, `craftComputed`,
+   `craftEffect`, and the other documented helpers rather than ad hoc runtime
+   state.
+3. **Do not use `async` / `await` / `for await`.** Generators, `craftSleep`, and `CraftHttpClient` replace them.
+4. **HTTP:** `query` for reads, `mutation` for writes, both backed by `CraftHttpClient`. No raw `fetch` / `HttpClient`.
+5. **Forms** derive from `state` + `insertForm`. Validators are `cRequired`, `cEmail`, `cMinLength`, … Submit through `insertFormSubmit` + a `mutation`. Failures are `craftException` values.
+6. **Services:** `craftService({ name, scope }, function* () { ... })`. Consume
+   the generated `X()` helper, typically `yield* X(...)`.
+7. **Routes:** `craftRoutes(name, [...])`, every component route has `componentDeps: {} as import('./x').GenDeps_X`, and **every file** has its own `ValidateCascadeRoutesFile` / `CanRun` check. Parent checks do not cover `loadChildren`. On `TS2589`, split with `loadChildren` — never delete the check.
+8. **Templates:** `ifBlock` / `matchBlock` / `each` / `defer`, not `@if` / `@for`. Interactive helpers take a unique literal local name: `button('save', { type: 'button', ... }, 'Save')`. The name is `data-craft-name` and must be unique in the app (`assertInteractiveElementNamed`).
+9. **Let ESLint keep generated aliases.** After DI or route edits, run `eslint --fix`. Do not hand-edit `GenDeps_*` or `_Check*` / `_CanRun*` blocks.
+
+Install `@craft-ts/dev-tools` and enable the `craft-ts/*` ESLint rules. They are the compiler's partner: a missing route check or a raw `inject()` should fail CI, not production. The generated README documents `npm run lint`, `typecheck`, `test`, `architecture`, `e2e`, and, for EffectTS v4, `effect-check`.
+
+The `architecture/` suite is the graph contract: unique HTTP, unique identities, armed route DI proofs, folder lanes. Scaffold it at app start (`craft-ts-architecture-tests`, `craft-migrate-architecture`). During a feature, run it. Do not add an architecture rule for the feature. Add a new `it()` only to freeze a spotted smell so it cannot recur.
+
+## Default compositions
+
+- Mutation that changes a visible list: `insertReactOnMutation` on the `query`. Prefer `optimisticPatch` for shallow fields, `optimisticUpdate` for arrays. Enable `reload: { onMutationError: true }` unless the spec forbids refetch.
+- Pagination / no-flicker page changes: `queryParams` + `query` + `insertPaginationPlaceholderData`.
+- Collections (add/remove/update/upsert): `insertEntities` and `removeOne` / `removeMany` / `updateOne` / `upsertMany`.
+- Remembered filters or results: `insertStoragePersister` / `insertLocalStoragePersister`.
+- Nested sub-state: `insertSelect`. Nested forms: `insertSelectFormTree` + `insertSubFormField`.
+
+## Agent workflow
+
+1. If this is app setup or `craft-migrate`, and `architecture/` is missing, load `craft-ts-architecture-tests` and scaffold the baseline. Mid-feature, offer the scaffold; do not impose it.
+2. Map the request to primitives (`translate-spec-to-craft-ts` skill). Name the baseline helper that already covers the mapping; do not invent a rule per feature.
+3. Search docs for the exact export (`search_documentation`, then `get_documentation_page`).
+4. For routes, follow `craft-ts-routes`. For an existing application, use
+   `migrate-to-craft-ts` then `craft-migrate`. Load
+   `craft-ts-architecture-tests` when a graph smell must not recur.
+5. Run the app's lint, typecheck, existing architecture tests, and tests. Do not claim success from filtered output.
+
+Confirm symbol names against the installed `@craft-ts/core` (and `@craft-ts/component`) in `node_modules`. If they disagree with this guide, the installed package wins.
+
+In local development, drive the already-open `ng serve` tab with the function-registry MCP tool `page` (see `/guide/ai/dev-page`). `@craft-ts/mcp` does not expose `page`; it is docs and skills for writing Craft.