@happyvertical/smrt-dev-mcp 0.30.0

package/AGENTS.md

@@ -0,0 +1,75 @@
+# @happyvertical/smrt-dev-mcp
+
+Tier 2 MCP server for development — code generation, project introspection,
+deterministic SMRT ecosystem knowledge, and portable agent workflows.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `generate-smrt-class` | Generates `@smrt()` class with fields, decorator config, imports |
+| `introspect-project` | Scans project directory for SMRT objects, returns class/field/relationship report |
+| `review-smrt-project` | Advisory downstream ecosystem alignment review for dependencies, storage, app shell, auth/tenancy, and manifest generation |
+| `reflect-knowledge` | Reports deterministic SMRT + HappyVertical SDK knowledge coverage and freshness |
+| `reflect-domain-knowledge` | Reports downstream/domain artifact coverage and freshness |
+| `check-knowledge-freshness` | Runs deterministic agent-doc and stale-reference checks |
+| `check-domain-knowledge` | Alias for deterministic domain artifact freshness checks |
+| `build-review-context` | Builds model-ready SMRT review context and package expert routing |
+| `build-domain-review-context` | Domain-scoped review context builder with `scope`/`package` filters |
+| `smrt-review` | Returns deterministic review findings and a reusable review prompt bundle |
+| `build-architecture-context` | Builds architecture planning context from an idea or docs |
+| `build-domain-architecture-context` | Domain-scoped architecture context builder with `scope`/`package` filters |
+| `smrt-architecture` | Recommends SMRT/SDK packages, object-model sketch, risks, and questions |
+| `list-agent-skills` | Lists bundled harness-agnostic agent skills |
+| `get-agent-skill` | Returns a bundled agent skill as Markdown plus optional references |
+
+## Agent Skills
+
+Bundled skills live under `agent-skills/`. They are plain Markdown procedures
+with YAML frontmatter (`name` and `description`) and harness-neutral body text.
+Skill-aware harnesses can parse the frontmatter; other harnesses can ignore it.
+
+- `agent-skills/smrt-code-review/SKILL.md` — downstream SMRT code review workflow.
+  Agents should fetch it with `get-agent-skill`, then call `smrt-review` for
+  deterministic context, inspect the actual diff, and produce a findings-first
+  review.
+
+## Usage
+
+```jsonc
+// .mcp.json or Claude Desktop config
+{ "mcpServers": { "smrt-dev-mcp": { "command": "npx", "args": ["-y", "@happyvertical/smrt-dev-mcp"] } } }
+```
+
+For global MCP client config, do not use `pnpm exec smrt-dev-mcp` unless the MCP
+server is always launched from a repo that installs the package. Prefer an
+absolute `node /path/to/node_modules/@happyvertical/smrt-dev-mcp/dist/index.js`
+launcher or a small wrapper script with an absolute Node path.
+
+## MCP Tier Context
+
+- **Tier 1** (Runtime): auto-generated from `@smrt()` objects — live data operations
+- **Tier 2** (Development): this package — code generation and project analysis
+- **Tier 3** (Docs): `smrt-docs-mcp` — framework documentation access
+
+## Key Files
+
+- `src/index.ts` — MCP server setup, tool registration
+- `src/knowledge/index.ts` — deterministic SMRT, SDK, and downstream domain knowledge discovery
+- `src/agent-skills.ts` — bundled skill registry and file loader
+- `agent-skills/smrt-code-review/SKILL.md` — downstream SMRT review procedure
+- `src/tools/generate-smrt-class.ts` — class generation logic and package-ready templates
+- `src/tools/introspect-project.ts` — manifest-first project scanning, falling back to `@happyvertical/smrt-scanner`
+- `src/tools/review-smrt-project.ts` — advisory ecosystem-alignment checks for downstream projects
+
+## Gotchas
+
+- **Read-only**: never writes files or executes generated code
+- **Model-agnostic**: review and architecture tools return deterministic
+  findings/context and prompt bundles; they do not call model providers
+- **Domain artifacts first**: discovery must prefer `.smrt/smrt-knowledge.json`,
+  then `dist/smrt-knowledge.json`, then source artifacts before raw manifest
+  fallback
+- **Skill loading**: bundled skills must be included in `package.json` `files`
+  because runtime reads them from the installed package directory
+- **Field type mapping**: `text`, `integer`, `decimal`, `boolean`, `datetime`, `json` — maps to SMRT field helpers (but prefer TypeScript defaults per framework convention)

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# @happyvertical/smrt-dev-mcp
+
+Development MCP server for the SMRT framework providing code generation,
+project introspection, deterministic ecosystem knowledge, and portable review
+or architecture prompt bundles.
+
+## Installation
+
+```bash
+pnpm install @happyvertical/smrt-dev-mcp
+```
+
+## Usage
+
+Add to your project-local `.mcp.json`, Codex MCP config, or Claude Desktop
+config:
+
+```json
+{
+  "mcpServers": {
+    "smrt-dev-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@happyvertical/smrt-dev-mcp"]
+    }
+  }
+}
+```
+
+For global MCP client config, prefer a launcher that does not depend on the
+current working directory. Avoid `command = "pnpm"` with
+`args = ["exec", "smrt-dev-mcp"]` in user-level config: MCP clients can start
+servers from repositories that do not install this package, and pnpm can run
+dependency-status or build-approval checks before the MCP server starts.
+
+Install the package in a stable location and point Codex at the built server:
+
+```toml
+[mcp_servers.smrt-dev-mcp]
+command = "node"
+args = ["/absolute/path/to/node_modules/@happyvertical/smrt-dev-mcp/dist/index.js"]
+```
+
+If your Node runtime is managed by a toolchain, use a tiny absolute wrapper
+instead:
+
+```sh
+#!/usr/bin/env sh
+exec /absolute/path/to/node /absolute/path/to/node_modules/@happyvertical/smrt-dev-mcp/dist/index.js "$@"
+```
+
+```toml
+[mcp_servers.smrt-dev-mcp]
+command = "/absolute/path/to/smrt-dev-mcp-wrapper"
+args = []
+```
+
+Set `DEBUG=true` in the environment to enable diagnostic logging.
+
+## Knowledge Boundary
+
+`smrt-dev-mcp` is model-agnostic. Its review and architecture tools do not call
+Codex, Claude, or any other model provider directly. They return deterministic
+findings plus a reusable prompt bundle that can be sent to the local model plan
+or provider of your choice.
+
+Downstream SMRT packages/apps can publish their own scoped
+`smrt-knowledge.json` artifact. Discovery prefers local
+`.smrt/smrt-knowledge.json`, then `dist/smrt-knowledge.json`, then source
+manifest artifacts before falling back to raw manifest/doc scanning. The runtime
+`manifest.json` stays focused on object registration; `smrt-knowledge.json` is
+the agent/developer contract.
+
+After using a model to update package docs or expertise, always run the
+deterministic checker again:
+
+```bash
+pnpm knowledge:check --strict --format markdown
+```
+
+Use `--format json` when another script needs machine-readable output.
+
+## Downstream Review Flow
+
+1. Run the downstream app build or dev server so `.smrt/smrt-knowledge.json`
+   exists.
+2. Call `reflect-domain-knowledge` to confirm package and SDK coverage.
+3. Call `build-domain-review-context` or `smrt-review` with changed files,
+   `scope`, and optional `package`.
+4. Send the returned prompt bundle to Codex, Claude, or another model.
+5. Re-run `check-domain-knowledge` after edits.
+
+Equivalent CLI commands are:
+
+```bash
+smrt knowledge:review-context --scope package --package content --format markdown
+smrt knowledge:architecture-context "tenant-aware publishing workflow" --format json
+```
+
+## Agent Skills
+
+The package ships harness-agnostic agent skills under `agent-skills/`.
+
+Downstream agents should fetch the review procedure before starting a formal
+SMRT review:
+
+```json
+{
+  "name": "get-agent-skill",
+  "arguments": {
+    "name": "smrt-code-review"
+  }
+}
+```
+
+The returned `skillMarkdown` is plain Markdown with YAML frontmatter (`name`
+and `description`) and a harness-neutral body. Skill-aware harnesses can parse
+the frontmatter; other MCP-capable harnesses can ignore it, call `smrt-review`
+for deterministic context, inspect the actual diff, and produce a findings-first
+review. Native MCP prompt/resource clients can also load the `smrt-code-review`
+prompt or `smrt-dev-mcp://agent-skills/smrt-code-review` resource.
+
+## Available Tools
+
+The server exposes these MCP tools:
+
+### `generate-smrt-class`
+
+Generate a complete SMRT class with `@smrt()` decorator, fields, and imports.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `className` | `string` | Yes | Class name (PascalCase) |
+| `properties` | `array` | Yes | Property definitions (`name`, `type`, `required?`, `nullable?`, `description?`, `defaultValue?`) |
+| `baseClass` | `string` | No | `'SmrtObject'` (default) or `'SmrtCollection'` |
+| `template` | `string` | No | `basic`, `global-catalog`, `optional-catalog`, `tenant-project-object`, `tenant-event-log-object`, or `cross-package-reference` |
+| `tableName` | `string` | No | Explicit `@smrt({ tableName })` value |
+| `conflictColumns` | `string[]` | No | Explicit upsert natural key columns |
+| `tenantScoped` | `boolean/object` | No | Add `@TenantScoped(...)`; object supports `mode`, `field`, and bypass/filter options |
+| `includeTenantIdField` | `boolean` | No | Emit a matching `@tenantId()` field |
+| `relationships` | `array` | No | Relationship definitions for `foreignKey`, `crossPackageRef`, `oneToMany`, or `manyToMany` |
+| `includeCompanionSnippets` | `boolean` | No | Append package wiring notes |
+| `includeApiConfig` | `boolean` | No | Include REST API config (default: true) |
+| `includeMcpConfig` | `boolean` | No | Include MCP config (default: true) |
+| `includeCliConfig` | `boolean` | No | Include CLI config (default: true) |
+
+Supported property types: `text`, `integer`, `decimal`, `boolean`, `datetime`, `json`.
+
+### `introspect-project`
+
+Scan a project directory for SMRT objects and return a manifest-equivalent
+class/field/relationship report. Discovery prefers `.smrt/manifest.json`, then
+`dist/manifest.json`, then `src/manifest/manifest.json`; when no artifact is
+available it falls back to `@happyvertical/smrt-scanner`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `directory` | `string` | No | Project directory (default: cwd) |
+| `manifestPath` | `string` | No | Explicit manifest artifact path |
+| `includeFields` | `boolean` | No | Include field details |
+| `includeRelationships` | `boolean` | No | Analyze relationships |
+| `includeMethods` | `boolean` | No | Include public method details |
+
+### `review-smrt-project`
+
+Run an advisory downstream ecosystem review. The tool scans package manifests
+and source imports for missing HappyVertical dependencies, direct storage
+bypasses, custom HTTP shells, custom object manifest generation, local
+auth/tenancy/audit seams, and UI shell drift. It returns deterministic findings
+and suggested follow-up issue titles; it does not modify files.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `directory` | `string` | No | Project directory (default: cwd) |
+| `rootDir` | `string` | No | Compatibility alias for `directory` |
+| `includeSourceEvidence` | `boolean` | No | Include file/line evidence (default: true) |
+| `maxFindings` | `number` | No | Limit findings returned |
+
+### `reflect-knowledge`
+
+Return package coverage, SDK package coverage, relationship-v2 counts, and
+freshness status from the deterministic SMRT + HappyVertical SDK knowledge
+index.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+
+### `reflect-domain-knowledge`
+
+Return domain artifact coverage, missing exported artifacts, SDK package
+coverage, relationship-v2 counts, and freshness status.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `scope` | `string` | No | `project`, `local`, `package`, or `sdk` |
+| `package` | `string` | No | Package name or short name to focus |
+
+### `check-knowledge-freshness`
+
+Run the same deterministic freshness checks exposed by `pnpm knowledge:check`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `changed` | `boolean` | No | Limit stale-pattern checks to changed files |
+| `strict` | `boolean` | No | Treat stale-pattern findings as errors |
+
+### `check-domain-knowledge`
+
+Alias over the deterministic checker that emphasizes downstream
+`smrt-knowledge.json` artifact freshness.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `changed` | `boolean` | No | Limit stale-pattern checks to changed files |
+| `strict` | `boolean` | No | Treat stale-pattern findings as errors |
+| `scope` | `string` | No | `project`, `local`, `package`, or `sdk` |
+| `package` | `string` | No | Package name or short name to focus |
+
+### `build-review-context`
+
+Select relevant SMRT and HappyVertical SDK package expertise for changed files,
+then return a model-ready prompt bundle.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `changedFiles` | `string[]` | No | Files to route to package experts |
+| `focus` | `string` | No | Review focus or concern |
+| `documentation` | `string` | No | Additional docs or notes to include |
+
+### `build-domain-review-context`
+
+Domain-scoped alias for `build-review-context`. Accepts the same fields plus
+`scope` and `package`.
+
+### `smrt-review`
+
+Return deterministic review findings, a prompt bundle, or both.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `changedFiles` | `string[]` | No | Files to route to package experts |
+| `focus` | `string` | No | Review focus or concern |
+| `documentation` | `string` | No | Additional docs or notes to include |
+| `mode` | `string` | No | `findings`, `prompt-bundle`, or `both` |
+
+### `build-architecture-context`
+
+Select relevant SMRT and SDK package expertise for an idea or documentation,
+then return a model-ready architecture prompt bundle.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `idea` | `string` | No | Product or implementation idea |
+| `documentation` | `string` | No | Existing docs or requirements |
+| `focus` | `string` | No | Architecture concern to prioritize |
+
+### `build-domain-architecture-context`
+
+Domain-scoped alias for `build-architecture-context`. Accepts the same fields
+plus `scope` and `package`.
+
+### `smrt-architecture`
+
+Return package recommendations, SDK recommendations, an object-model sketch,
+risks, questions, and the reusable architecture prompt bundle.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rootDir` | `string` | No | Project root directory (default: cwd) |
+| `idea` | `string` | No | Product or implementation idea |
+| `documentation` | `string` | No | Existing docs or requirements |
+| `focus` | `string` | No | Architecture concern to prioritize |
+
+### `list-agent-skills`
+
+List bundled harness-agnostic agent skills.
+No parameters.
+
+### `get-agent-skill`
+
+Return a bundled agent skill as Markdown, with optional referenced files.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `string` | Yes | Skill name. Currently `smrt-code-review` |
+| `includeReferences` | `boolean` | No | Include referenced files (default: true) |
+
+## MCP Resources And Prompts
+
+Resources:
+
+- `smrt://knowledge/project` — composed project knowledge index as JSON.
+- `smrt://knowledge/package/{name}` — package-scoped knowledge as JSON.
+- `smrt-dev-mcp://agent-skills/smrt-code-review` — portable review skill.
+
+Prompts:
+
+- `domain-code-review` — returns the review prompt bundle.
+- `domain-architecture` — returns the architecture prompt bundle.
+- `smrt-code-review` — returns the harness-agnostic review procedure.
+
+## MCP Tier Context
+
+- **Tier 1** (Runtime): auto-generated from `@smrt()` objects -- live data operations
+- **Tier 2** (Development): this package -- code generation and project analysis
+- **Tier 3** (Docs): `smrt-docs-mcp` -- framework documentation access
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` -- MCP server protocol
+- `@happyvertical/smrt-core` -- manifest and object registry
+- `@happyvertical/smrt-types` -- shared domain knowledge contract
+
+## License
+
+MIT

package/agent-skills/smrt-code-review/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: smrt-code-review
+description: Use when reviewing a downstream SMRT project. Fetch deterministic SMRT and HappyVertical SDK context from smrt-dev-mcp, inspect the actual code diff, and produce a findings-first code review.
+---
+
+# SMRT Review
+
+Use this skill for code reviews in projects that use SMRT packages or generated
+SMRT surfaces.
+
+## Workflow
+
+1. Determine the repository root and changed files.
+   - Prefer the user's explicit changed-file list.
+   - Otherwise use the active harness's git support or `git diff --name-only`.
+   - Include staged files when the user is preparing a commit.
+2. Call MCP tool `smrt-review` from `smrt-dev-mcp` with:
+
+```json
+{
+  "rootDir": "/absolute/path/to/project",
+  "changedFiles": ["relative/path/from/root.ts"],
+  "focus": "Review SMRT usage, relationships-v2 patterns, tenancy, generated API/CLI/MCP compatibility, SDK usage, prompt/data safety, and stale docs.",
+  "mode": "both"
+}
+```
+
+3. Treat `deterministicFindings` as required review routing, not as the whole
+   review. A routing warning means the code needs focused scrutiny; do not
+   report it as a defect unless the actual diff confirms a concrete issue.
+4. Read the actual changed diff and any referenced files needed to understand
+   behavior. Do not review from the MCP context alone.
+5. Use `promptBundle.contextMarkdown` as current SMRT ecosystem context for
+   selected packages and SDKs. When generated facts conflict with authored
+   guidance, trust generated facts and flag the doc drift.
+6. Produce a findings-first review. Prioritize correctness, regressions,
+   missing tests, generated-surface compatibility, relationship/tenant
+   invariants, data exposure, and stale docs.
+7. If code, docs, or package expertise changed, call MCP tool
+   `check-knowledge-freshness` with `{ "strict": true }` when available, or
+   tell the user to run:
+
+```bash
+pnpm knowledge:check --strict --format markdown
+```
+
+## Required Review Focus
+
+- Relationships-v2: `@foreignKey`, `@crossPackageRef`, `SmrtJunction`,
+  `SmrtHierarchical`, polymorphic `(metaType, metaId, role)` links, qualified
+  `_meta_type`, UUID id/FK columns, and tenant-guarded relationship loads.
+- Generated surfaces: public exports, CLI commands, REST handlers, generated MCP
+  tool names/schemas, and AI-operation compatibility.
+- Tenancy: nullable tenant semantics, tenant context propagation, and explicit
+  cross-tenant exceptions.
+- SDK usage: prefer HappyVertical SDK packages for AI, SQL, files, logging,
+  secrets, jobs, and external capability adapters.
+- Agent docs: `AGENTS.md` is canonical; `CLAUDE.md` must remain exactly the
+  `@AGENTS.md` shim.
+
+## Output
+
+Lead with findings ordered by severity. Use file and line references when the
+harness can provide them. If no issues are found, say that clearly and mention
+the validation or residual risk. Keep summaries secondary to findings.
+
+See `references/review-output.md` for a stricter output template when the user
+asks for a formal review.

package/agent-skills/smrt-code-review/references/review-output.md

@@ -0,0 +1,31 @@
+# SMRT Review Output
+
+Use this stricter template when the user asks for a formal review.
+
+## Findings
+
+List findings first, ordered by severity. Each finding should include:
+
+- severity: blocker, high, medium, or low
+- file and line reference when available
+- the concrete bug, regression, or risk
+- why it matters in SMRT terms
+- the smallest practical fix or validation path
+
+## Open Questions
+
+Include only questions that block a correct review or implementation decision.
+
+## Validation
+
+State which checks were run or which checks are still needed. For SMRT doc,
+package, or expertise changes, include deterministic knowledge freshness:
+
+```bash
+pnpm knowledge:check --strict --format markdown
+```
+
+## Summary
+
+Keep the summary brief and secondary. Do not let a summary hide unresolved
+findings.

package/dist/agent-skills.d.ts

@@ -0,0 +1,19 @@
+export interface AgentSkillSummary {
+    name: string;
+    description: string;
+    path: string;
+    references: string[];
+}
+export interface AgentSkillBundle extends AgentSkillSummary {
+    skillMarkdown: string;
+    referenceFiles: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+export declare function listAgentSkills(): AgentSkillSummary[];
+export declare function getAgentSkill(options: {
+    name: string;
+    includeReferences?: boolean;
+}): AgentSkillBundle;
+//# sourceMappingURL=agent-skills.d.ts.map

package/dist/agent-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skills.d.ts","sourceRoot":"","sources":["../src/agent-skills.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,KAAK,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAiBD,wBAAgB,eAAe,IAAI,iBAAiB,EAAE,CAErD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,gBAAgB,CAoBnB"}