@meghjs/mcp 0.0.0-stage → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +141 -2
  3. package/dist/bin.d.ts +2 -0
  4. package/dist/bin.js +37 -0
  5. package/dist/docs/advanced/caching.md +72 -0
  6. package/dist/docs/advanced/database.md +328 -0
  7. package/dist/docs/advanced/events.md +169 -0
  8. package/dist/docs/advanced/file-uploads.md +141 -0
  9. package/dist/docs/advanced/health.md +81 -0
  10. package/dist/docs/advanced/logging.md +96 -0
  11. package/dist/docs/advanced/mail.md +439 -0
  12. package/dist/docs/advanced/orm/migrations.md +210 -0
  13. package/dist/docs/advanced/orm/models.md +291 -0
  14. package/dist/docs/advanced/orm/queries.md +169 -0
  15. package/dist/docs/advanced/orm/query-builder.md +120 -0
  16. package/dist/docs/advanced/orm/relations.md +179 -0
  17. package/dist/docs/advanced/orm/seeding.md +129 -0
  18. package/dist/docs/advanced/orm.md +145 -0
  19. package/dist/docs/advanced/plugins.md +90 -0
  20. package/dist/docs/advanced/queue.md +217 -0
  21. package/dist/docs/advanced/scheduler.md +253 -0
  22. package/dist/docs/advanced/testing.md +257 -0
  23. package/dist/docs/advanced/views.md +335 -0
  24. package/dist/docs/ai/mcp.md +162 -0
  25. package/dist/docs/cli/basic.md +133 -0
  26. package/dist/docs/cli/database.md +112 -0
  27. package/dist/docs/cli/generators.md +605 -0
  28. package/dist/docs/cli/scaffold/auth.md +172 -0
  29. package/dist/docs/cli/scaffold/domains.md +224 -0
  30. package/dist/docs/cli/scaffold/index.md +77 -0
  31. package/dist/docs/cli/scaffold/rbac.md +118 -0
  32. package/dist/docs/cli/scaffold/templates.md +235 -0
  33. package/dist/docs/core-concept/authentication.md +162 -0
  34. package/dist/docs/core-concept/configuration.md +268 -0
  35. package/dist/docs/core-concept/controller.md +350 -0
  36. package/dist/docs/core-concept/dependency-injection.md +213 -0
  37. package/dist/docs/core-concept/error-handling.md +185 -0
  38. package/dist/docs/core-concept/middleware.md +143 -0
  39. package/dist/docs/core-concept/request-context.md +110 -0
  40. package/dist/docs/core-concept/validation.md +355 -0
  41. package/dist/docs/getting-started/application.md +233 -0
  42. package/dist/docs/getting-started/installation.md +166 -0
  43. package/dist/docs/getting-started/introduction.md +136 -0
  44. package/dist/docs/getting-started/upgrading-0.4.md +125 -0
  45. package/dist/docs/getting-started/upgrading-0.5.md +293 -0
  46. package/dist/docs/getting-started/upgrading-0.6.md +251 -0
  47. package/dist/docs/getting-started/upgrading-0.7.md +225 -0
  48. package/dist/docs/getting-started/upgrading-megh.md +91 -0
  49. package/dist/docs/getting-started/upgrading-next.md +12 -0
  50. package/dist/docs/getting-started/upgrading.md +137 -0
  51. package/dist/docs/getting-started/usage.md +194 -0
  52. package/dist/docs/index.md +58 -0
  53. package/dist/docs/microservices/openapi.md +387 -0
  54. package/dist/docs/microservices/websocket.md +165 -0
  55. package/dist/docs/production/deployment.md +256 -0
  56. package/dist/docs/production/security.md +307 -0
  57. package/dist/docs/reference/api.md +999 -0
  58. package/dist/docs/reference/faq.md +227 -0
  59. package/dist/docs/reference/versioning.md +105 -0
  60. package/dist/docs.d.ts +30 -0
  61. package/dist/docs.js +126 -0
  62. package/dist/index.d.ts +10 -0
  63. package/dist/index.js +22 -0
  64. package/dist/megh.d.ts +59 -0
  65. package/dist/megh.js +207 -0
  66. package/dist/prompts.d.ts +3 -0
  67. package/dist/prompts.js +47 -0
  68. package/dist/result.d.ts +18 -0
  69. package/dist/result.js +48 -0
  70. package/dist/server.d.ts +17 -0
  71. package/dist/server.js +40 -0
  72. package/dist/tools/context.d.ts +11 -0
  73. package/dist/tools/context.js +2 -0
  74. package/dist/tools/database.d.ts +8 -0
  75. package/dist/tools/database.js +58 -0
  76. package/dist/tools/docs.d.ts +3 -0
  77. package/dist/tools/docs.js +63 -0
  78. package/dist/tools/generate.d.ts +10 -0
  79. package/dist/tools/generate.js +177 -0
  80. package/dist/tools/project.d.ts +3 -0
  81. package/dist/tools/project.js +84 -0
  82. package/dist/version.d.ts +2 -0
  83. package/dist/version.js +10 -0
  84. package/package.json +58 -4
@@ -0,0 +1,162 @@
1
+ ---
2
+ title: MCP Server
3
+ description: Connect AI assistants to your Megh app with @meghjs/mcp, the Megh Model Context Protocol server.
4
+ ---
5
+
6
+ # MCP Server
7
+
8
+ `@meghjs/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
9
+ (MCP) server for Megh. MCP is an open standard for connecting AI assistants to
10
+ tools and data. With this server, assistants such as Claude Code, Claude
11
+ Desktop, Cursor and VS Code work from your real project and the real Megh docs
12
+ instead of guessing.
13
+
14
+ It gives an assistant:
15
+
16
+ - **The Megh docs.** They ship with the server and match its version, so the
17
+ assistant searches and reads the right API instead of relying on memory.
18
+ - **A view of your project:** dependencies, source files by kind, routes,
19
+ migration status, the `megh doctor` checks and type errors.
20
+ - **The `megh` generators and scaffolds,** run the same way the CLI runs them.
21
+ - **Migrations and seeders,** which it refuses to run against a production
22
+ project.
23
+
24
+ It wraps the `megh` CLI. It uses the `@meghjs/cli` installed in your project
25
+ when there is one, so generated code matches your `@meghjs/core`, and falls
26
+ back to its own copy otherwise.
27
+
28
+ ## Setup
29
+
30
+ The server runs with `npx`, so there is nothing to install in your project.
31
+
32
+ ### Claude Code
33
+
34
+ From your project folder:
35
+
36
+ ```sh
37
+ claude mcp add megh -- npx -y @meghjs/mcp
38
+ ```
39
+
40
+ ### VS Code
41
+
42
+ Add `.vscode/mcp.json` to your project:
43
+
44
+ ```json [.vscode/mcp.json]
45
+ {
46
+ "servers": {
47
+ "megh": {
48
+ "type": "stdio",
49
+ "command": "npx",
50
+ "args": ["-y", "@meghjs/mcp", "${workspaceFolder}"]
51
+ }
52
+ }
53
+ }
54
+ ```
55
+
56
+ ### Claude Desktop, Cursor and others
57
+
58
+ Any client that reads an `mcpServers` config:
59
+
60
+ ```json
61
+ {
62
+ "mcpServers": {
63
+ "megh": {
64
+ "command": "npx",
65
+ "args": ["-y", "@meghjs/mcp", "/path/to/your/project"]
66
+ }
67
+ }
68
+ }
69
+ ```
70
+
71
+ Then ask the assistant something like "review this Megh project" or "add a
72
+ products resource with a name and a price".
73
+
74
+ ## Options
75
+
76
+ ```sh
77
+ megh-mcp [project-dir] [--read-only]
78
+ ```
79
+
80
+ | Option | Environment | Description |
81
+ | --- | --- | --- |
82
+ | `project-dir` | `MEGH_PROJECT_ROOT` | The project the tools work on. Defaults to the folder the server starts in. Every tool also takes an optional `cwd`. |
83
+ | `--read-only` | `MEGH_MCP_READ_ONLY=1` | Leave out every tool that writes files or changes the database, and the `megh-add-resource` prompt. |
84
+ | | `MEGH_DOCS_DIR` | Serve docs from this folder instead of the bundled ones. |
85
+
86
+ ::: tip Read-only for reviews
87
+ Use `--read-only` when you only want the assistant to explain or review your
88
+ code. It can still read the docs and inspect the project, but it can't change
89
+ files or the database.
90
+ :::
91
+
92
+ ## Tools
93
+
94
+ ### Project
95
+
96
+ | Tool | What it does |
97
+ | --- | --- |
98
+ | `megh_project_info` | Project root, `@meghjs/*` dependencies (declared and installed), scripts, `megh` settings, and whether it runs in production |
99
+ | `megh_project_structure` | Source files grouped by kind (controllers, services, models, DTOs, migrations, seeders...), with counts and the entry file |
100
+ | `megh_doctor` | The `megh doctor` checks: Node.js, `@meghjs/core`, `reflect-metadata`, decorator settings |
101
+ | `megh_list_routes` | `megh route:list --json`. `static: true` reads the decorators without running your code |
102
+ | `megh_list_templates` | `megh template:list [domain] --json` |
103
+ | `megh_typecheck` | Runs the project's `tsc --noEmit` and returns the errors |
104
+ | `megh_migrate_status` | `megh migrate:status --json` |
105
+
106
+ ### Docs
107
+
108
+ | Tool | What it does |
109
+ | --- | --- |
110
+ | `megh_search_docs` | Searches the Megh docs and returns the best-matching pages with snippets |
111
+ | `megh_read_doc` | Reads a page as markdown, e.g. `core-concept/controller`. With no page, lists them all |
112
+
113
+ ### Code generation
114
+
115
+ | Tool | What it does |
116
+ | --- | --- |
117
+ | `megh_make` | `megh make:<kind> <name>` for model, controller, service, resource, dto, config, middleware, mail, event, listener, queue, worker, task, migration, seeder and factory |
118
+ | `megh_sync_model` | `megh sync:model`: updates a model after an alter-table migration. `dryRun` shows the changes first |
119
+ | `megh_scaffold_domain` | `megh scaffold:domain`: the tables (and models or resources) of a domain's templates |
120
+ | `megh_scaffold_auth` | `megh scaffold:auth`: sign-up and sign-in with JWTs, API keys or both, optionally with roles |
121
+ | `megh_scaffold_rbac` | `megh scaffold:rbac`: roles and permissions for an app that already has users |
122
+ | `megh_build` | `megh build`: compiles to the output folder and copies assets |
123
+
124
+ The generators never prompt, and they leave existing files alone unless `force`
125
+ is set.
126
+
127
+ ### Database
128
+
129
+ | Tool | What it does |
130
+ | --- | --- |
131
+ | `megh_migrate` | Runs the pending migrations, optionally followed by the seeders |
132
+ | `megh_migrate_rollback` | Undoes the last migration, or the last `step` |
133
+ | `megh_db_seed` | Runs the seeders, or one `seeder` |
134
+
135
+ These refuse to run when `NODE_ENV` is `production`, whether it is set in the
136
+ server's environment or in the project's `.env`. `migrate:reset` and
137
+ `migrate:refresh` aren't exposed, because they drop every table. Run those
138
+ yourself.
139
+
140
+ ## Resources and prompts
141
+
142
+ | Resource | Contents |
143
+ | --- | --- |
144
+ | `megh://docs/{page}` | A docs page as markdown, e.g. `megh://docs/advanced/orm` |
145
+ | `megh://project/info` | The project, as `megh_project_info` returns it |
146
+ | `megh://project/structure` | The project's files, as `megh_project_structure` returns them |
147
+
148
+ | Prompt | What it does |
149
+ | --- | --- |
150
+ | `megh-review-project` | Checks the setup, routes, structure and type errors, and points out problems |
151
+ | `megh-explain` | Explains a Megh feature (`topic`) from the docs, with an example that fits the project |
152
+ | `megh-add-resource` | Adds a table, model and CRUD API for `name` (with optional `fields`), migrates, and checks it compiles. Not offered in read-only mode |
153
+
154
+ ## Use it as a library
155
+
156
+ ```ts
157
+ import { createServer } from '@meghjs/mcp';
158
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
159
+
160
+ const server = createServer({ projectRoot: '/path/to/app', readOnly: true });
161
+ await server.connect(new StdioServerTransport());
162
+ ```
@@ -0,0 +1,133 @@
1
+ ---
2
+ title: CLI
3
+ description: "The megh command: create, run and build apps, generate code and manage the database."
4
+ ---
5
+
6
+ # CLI
7
+
8
+ Install the CLI globally, or run it with `npx`:
9
+
10
+ ```sh
11
+ npm i -g @meghjs/cli
12
+ ```
13
+
14
+ ## Command Overview
15
+
16
+ | Command | Alias | Description |
17
+ |---------|-------|-------------|
18
+ | `new` | | Create a new application |
19
+ | `serve` | | Start the dev server with watch + rebuild |
20
+ | `build` | | Compile using `tsconfig.build.json` |
21
+ | `make:model` | `m:m` | Create a model: a plain class, a MeghORM model with `--orm` (columns from its migrations), or a TypeORM entity with `--typeorm` |
22
+ | `sync:model` | `s:m` | Sync an existing model's columns with its migrations (was `update:model`) |
23
+ | `make:resource` | `m:r` | Create a REST resource for a model: DTOs, CRUD service and controller |
24
+ | `make:controller` | `m:c` | Create a controller |
25
+ | `make:service` | `m:s` | Create a service |
26
+ | `make:config` | `m:cnf` | Create a config class |
27
+ | `make:middleware` | `m:mlwr` | Create a middleware |
28
+ | `make:mail` | `m:mail` | Create a Mailable in `src/mail/` |
29
+ | `make:event` | `m:ev` | Create an event in `src/events/` |
30
+ | `make:listener` | `m:lsn` | Create an event listener in `src/listeners/` (`--event` to type it) |
31
+ | `make:queue` | `m:q` | Create a queue with a job handler in `src/queues/` |
32
+ | `make:worker` | `m:w` | Create a worker for a queue in `src/workers/` |
33
+ | `make:task` | `m:task`, `make:scheduler` | Create a scheduled task in `src/tasks/` (`--cron`, `--interval`) |
34
+ | `make:dto` | `m:dto` | Create a class-validator DTO in `src/dtos/` |
35
+ | `make:class` | `m:cls` | Create a plain class in `src/classes/` |
36
+ | `make:view` | `m:v` | Create a `.megh.html` view (or `-c` component) in `views/` |
37
+ | `make:test` | `m:t` | Create a unit test (`<name>.spec.ts`) for an existing file |
38
+ | `make:migration` | `m:mig` | Create a database migration |
39
+ | `make:seeder` | `m:sd` | Create a database seeder |
40
+ | `make:factory` | `m:f` | Create a model factory with Faker values |
41
+ | `migrate` | | Run pending migrations (`--seed` to seed afterwards) |
42
+ | `migrate:status` | | Show which migrations have run |
43
+ | `migrate:rollback` | | Undo the last migration (`--step <n>` for more) |
44
+ | `migrate:reset` | | Undo every migration |
45
+ | `migrate:refresh` | | Undo every migration, then run them all again (`--seed` too) |
46
+ | `db:seed` | | Run the seeders (`--seeder <name>` for one) |
47
+ | `scaffold:domain` | `sc:domain` | Create the tables and models (or resources) of a business domain |
48
+ | `scaffold:auth` | `sc:auth` | Add sign-up and sign-in with JWTs and/or API keys, optionally with roles |
49
+ | `scaffold:rbac` | `sc:rbac` | Add roles and permissions to an app's users |
50
+ | `template:list` | `templates` | List the model templates |
51
+
52
+ Every `make:*` command takes `-f` / `--force` to overwrite an existing file.
53
+ The generators except `make:model` and the database ones (`make:migration`,
54
+ `make:seeder`, `make:factory`) also write a unit test next to the file; pass
55
+ `--notest` (or `-nt`) to skip it. See [Tests](/cli/generators#tests).
56
+ `make:model` and `make:resource` also build the table from a
57
+ [template](/cli/scaffold/templates) with `--template` or `--fields`.
58
+
59
+ ## Pages
60
+
61
+ | Page | Commands |
62
+ |---|---|
63
+ | [Generators](/cli/generators) | `make:resource`, `make:controller`, `make:service`, `make:model`, `sync:model`, `make:middleware`, `make:config`, `make:mail`, `make:event`, `make:listener`, `make:queue`, `make:worker`, `make:task`, `make:dto`, `make:class`, `make:test` |
64
+ | [Database Commands](/cli/database) | `make:migration`, `migrate*`, `make:seeder`, `db:seed`, `make:factory` |
65
+ | [Scaffold](/cli/scaffold/) | `--template`, `--fields`, `scaffold:domain`, `scaffold:auth`, `scaffold:rbac`, `template:list` |
66
+
67
+ ## Version and info
68
+
69
+ ```sh
70
+ npx megh -v # the CLI version, e.g. 0.7.0 (also --version)
71
+ npx megh --info # the logo, CLI, Node.js and OS versions, and the project's Megh packages (also -i)
72
+ ```
73
+
74
+ The logo appears only with `--info`; `-v`, `--help` and the other commands
75
+ print without it. `--info` also shows the installed `@meghjs/core`, `@meghjs/data`
76
+ and TypeScript versions when run inside an app: paste it into a bug report.
77
+
78
+ ## Application
79
+
80
+ ```sh
81
+ npx @meghjs/cli new myapi
82
+ ```
83
+
84
+ You are prompted for a package manager and optional features: OpenAPI docs,
85
+ CORS and MeghORM. With MeghORM you also pick the database. Add
86
+ [Mail](/advanced/mail#setting-it-up), Scalar UI or the
87
+ [`@meghjs/data`](/advanced/database) plugin afterwards. Non-interactively:
88
+
89
+ ```sh
90
+ npx @meghjs/cli new myapi --yes --database postgres # also: mysql, sqlite, mssql
91
+ ```
92
+
93
+ `--database` (or the `orm` feature, which defaults to SQLite) installs the
94
+ driver, adds `app.useMeghORM()` to `src/app.ts`, writes `DATABASE_URL` to
95
+ `.env` and creates `src/database/migrations/`.
96
+
97
+ For a server-rendered app, pass `--mvc`:
98
+
99
+ ```sh
100
+ npx @meghjs/cli new myapp --mvc
101
+ ```
102
+
103
+ It adds `app.useViews()` and `app.useMethodOverride()` to `src/app.ts`, a
104
+ layout in `views/layouts/app.megh.html`, a page in `views/pages/home.megh.html`,
105
+ and a `HomeController` that renders it with `Results.View('pages.home', ...)`.
106
+ Add more pages with [`make:view`](/cli/generators#view). See
107
+ [Views](/advanced/views). `--mvc` can't be combined with `--minimal`.
108
+
109
+ The new project is put under git with `git init`, unless git isn't installed
110
+ or the folder is already inside a repository. Pass `--skip-git` (or set
111
+ `MEGH_SKIP_GIT=1`) to skip it. Then:
112
+
113
+ ```sh
114
+ cd myapi
115
+ npm run start:dev
116
+ ```
117
+
118
+ ## Development Server
119
+
120
+ ```sh
121
+ npx megh serve
122
+ ```
123
+
124
+ Compiles `src/` with SWC into `dist/`, starts the app and restarts it on change.
125
+ The entry point comes from `megh.entry` in `package.json`, falling back to `main`.
126
+
127
+ ## Build
128
+
129
+ ```sh
130
+ npx megh build
131
+ ```
132
+
133
+ Removes the output folder (`outDir`, usually `dist/`) and compiles the project with `tsconfig.build.json`.
@@ -0,0 +1,112 @@
1
+ ---
2
+ title: Database Commands
3
+ description: Running migrations, seeders and factories with the Megh CLI.
4
+ ---
5
+
6
+ # Database Commands
7
+
8
+ These commands create and run migrations, seeders and factories.
9
+
10
+ ## Migrations
11
+
12
+ ```sh
13
+ npx megh make:migration create_users_table
14
+ npx megh migrate
15
+ ```
16
+
17
+ `make:migration` writes `src/database/migrations/<timestamp>_<name>.ts`.
18
+ A `create_<table>_table` name gives a create-table migration, and
19
+ `add_<x>_to_<table>_table` an alter-table one; `--create <table>` and
20
+ `--table <table>` choose explicitly.
21
+
22
+ The `migrate` commands connect the way `app.useMeghORM()` does, from
23
+ `DATABASE_URL` (or the `DB_*` variables) in the environment or `.env`. Set
24
+ `megh.migrations` in `package.json` to use another folder. See
25
+ [MeghORM: Migrations](/advanced/orm/migrations).
26
+
27
+ By default they compile `src/` with SWC into `node_modules/.cache/megh`
28
+ first. With `--compiled` they run the `.js` files `megh build` wrote to the
29
+ tsconfig `outDir` instead (`dist/database/migrations`, or
30
+ `dist/src/database/migrations` when `rootDir` isn't set), so the sources and
31
+ a writable `node_modules` aren't needed. This happens automatically when
32
+ there is no `src/` folder, as in a production image. Every `migrate*`
33
+ command and `db:seed` accepts `--compiled`.
34
+
35
+ ```sh
36
+ npx megh build
37
+ npx megh migrate --compiled
38
+ ```
39
+
40
+ ## Seeders
41
+
42
+ ```sh
43
+ npx megh make:seeder roles
44
+ npx megh make:seeder users
45
+ npx megh make:seeder database # the entry seeder: calls roles, then users
46
+ npx megh db:seed
47
+ ```
48
+
49
+ `make:seeder` writes `src/database/seeders/<name>.seeder.ts`
50
+ (`UserSeeder` and `user_seeder` both become `user.seeder.ts`):
51
+
52
+ ```ts [src/database/seeders/roles.seeder.ts]
53
+ import { defineSeeder } from '@meghjs/core';
54
+ import { Role } from '../../models/role.model';
55
+
56
+ export default defineSeeder({
57
+ async run() {
58
+ await Role.create({ name: 'Admin' });
59
+ await Role.create({ name: 'Editor' });
60
+ },
61
+ });
62
+ ```
63
+
64
+ `db:seed` runs the `database` seeder, which calls the others in the order you
65
+ choose; `make:seeder database` fills that in from the seeders that already
66
+ exist. Without a `database` seeder, every seeder runs in file-name order.
67
+
68
+ ```sh
69
+ npx megh db:seed --seeder users # just one (also -s)
70
+ npx megh migrate --seed # migrate, then seed
71
+ npx megh migrate:refresh --seed # rebuild the schema and seed it
72
+ ```
73
+
74
+ A whole run is one transaction: if a seeder throws, nothing is saved and the
75
+ error names the seeder. Seeding refuses to run when `NODE_ENV` is
76
+ `production` unless you pass `--force`. Set `megh.seeders` in `package.json`
77
+ to use another folder. See [MeghORM: Seeding](/advanced/orm/seeding#seeding).
78
+
79
+ ## Factories
80
+
81
+ ```sh
82
+ npx megh make:factory role
83
+ npx megh make:factory user
84
+ ```
85
+
86
+ `make:factory` reads the model's columns and writes
87
+ `src/database/factories/<name>.factory.ts` with a [Faker](https://fakerjs.dev)
88
+ value for each, picked from the column's name and type:
89
+
90
+ ```ts [src/database/factories/user.factory.ts]
91
+ import { defineFactory } from "@meghjs/core";
92
+ import { User } from "../../models/user.model";
93
+ import { RoleFactory } from "./role.factory";
94
+
95
+ export const UserFactory = defineFactory(User, ({ faker }) => ({
96
+ name: faker.person.fullName(),
97
+ email: faker.internet.email(),
98
+ phone: faker.phone.number({ style: "international" }).slice(0, 20),
99
+ is_active: faker.datatype.boolean(),
100
+ role_id: RoleFactory,
101
+ }));
102
+ ```
103
+
104
+ A foreign key such as `role_id` uses `RoleFactory` when that factory exists,
105
+ so create the related model's factory first; otherwise it is left as a
106
+ comment (or `null` for a nullable key). Values are kept within short
107
+ `varchar(n)` columns. The generated key and timestamps are left out. Edit the
108
+ result freely: it's your code.
109
+
110
+ Factories need `@faker-js/faker` (`npm install -D @faker-js/faker`); `megh new`
111
+ adds it to projects with MeghORM. Set `megh.factories` in `package.json` to use
112
+ another folder. See [MeghORM: Factories](/advanced/orm/seeding#factories).