@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,177 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AUTH_STRATEGIES = exports.GENERATORS = void 0;
4
+ exports.registerGenerateTools = registerGenerateTools;
5
+ const zod_1 = require("zod");
6
+ const megh_1 = require("../megh");
7
+ const result_1 = require("../result");
8
+ /** The `make:*` generators the `megh_make` tool can run. */
9
+ exports.GENERATORS = [
10
+ "model",
11
+ "controller",
12
+ "service",
13
+ "resource",
14
+ "dto",
15
+ "config",
16
+ "middleware",
17
+ "mail",
18
+ "event",
19
+ "listener",
20
+ "queue",
21
+ "worker",
22
+ "task",
23
+ "migration",
24
+ "seeder",
25
+ "factory",
26
+ ];
27
+ /** Values `megh scaffold:auth --strategy` accepts. */
28
+ exports.AUTH_STRATEGIES = ["jwt", "api-key", "both"];
29
+ const writes = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
30
+ /** `--flag` when true, `--no-flag` when false, nothing when unset. */
31
+ const tri = (flag, value) => (value === undefined ? [] : [value ? `--${flag}` : `--no-${flag}`]);
32
+ /**
33
+ * Tools that write source files through the megh generators. Every call passes
34
+ * `--yes`: the CLI never prompts, and existing files are only replaced with `force`.
35
+ */
36
+ function registerGenerateTools({ server, project, readOnly }) {
37
+ if (readOnly)
38
+ return;
39
+ server.registerTool("megh_make", {
40
+ title: "Generate code",
41
+ description: "Run a megh make:<kind> generator, e.g. kind=controller name=User writes src/controllers/user.controller.ts (admin/User writes src/admin/controllers/user.controller.ts). " +
42
+ "resource writes a model's DTOs, CRUD service and controller. Files that exist are left alone unless force is set. " +
43
+ "Returns the CLI output listing the files written.",
44
+ inputSchema: {
45
+ cwd: result_1.cwdArg,
46
+ kind: zod_1.z.enum(exports.GENERATORS).describe("Which generator to run."),
47
+ name: zod_1.z.string().min(1).describe("Name, optionally nested, e.g. User, admin/User, create_users_table."),
48
+ force: zod_1.z.boolean().optional().describe("Overwrite files that already exist."),
49
+ table: zod_1.z
50
+ .string()
51
+ .optional()
52
+ .describe("model, resource, migration: the table name (for migration, an alter-table migration)."),
53
+ create: zod_1.z.string().optional().describe("migration: generate a create-table migration for this table."),
54
+ template: zod_1.z
55
+ .string()
56
+ .optional()
57
+ .describe("model, resource: create the table from a template, e.g. ecommerce/product (see megh_list_templates)."),
58
+ fields: zod_1.z
59
+ .string()
60
+ .optional()
61
+ .describe('model, resource: columns to add, e.g. "title,price:money,status:in(draft|live),user_id:cascade".'),
62
+ factory: zod_1.z.boolean().optional().describe("model with template or fields: also write a factory."),
63
+ },
64
+ annotations: writes,
65
+ }, (0, result_1.safe)(async ({ cwd, kind, name, force, table, create, template, fields, factory }) => {
66
+ const args = [`make:${kind}`, name, "--yes"];
67
+ if (force)
68
+ args.push("--force");
69
+ if (table)
70
+ args.push("--table", table);
71
+ if (create)
72
+ args.push("--create", create);
73
+ if (template)
74
+ args.push("--template", template);
75
+ if (fields)
76
+ args.push("--fields", fields);
77
+ if (factory)
78
+ args.push("--factory");
79
+ return (0, result_1.fromCli)(await (0, megh_1.runMegh)(project(cwd), args));
80
+ }));
81
+ server.registerTool("megh_sync_model", {
82
+ title: "Sync model with migrations",
83
+ description: "Run megh sync:model after an alter-table migration: adds new columns to the model, removes dropped ones and updates the ones still as make:model wrote them. Customized fields are kept and reported. Use dryRun to see the changes first.",
84
+ inputSchema: {
85
+ cwd: result_1.cwdArg,
86
+ name: zod_1.z.string().min(1).describe("Model name, optionally nested, e.g. User or admin/User."),
87
+ table: zod_1.z.string().optional().describe("Table to read (default: the model's @Table, else the plural snake_case name)."),
88
+ dto: zod_1.z.boolean().optional().describe("Also rewrite src/dtos/<name>.dto.ts from the updated columns."),
89
+ dryRun: zod_1.z.boolean().optional().describe("Show what would change without writing."),
90
+ },
91
+ annotations: writes,
92
+ }, (0, result_1.safe)(async ({ cwd, name, table, dto, dryRun }) => {
93
+ const args = ["sync:model", name, "--yes"];
94
+ if (table)
95
+ args.push("--table", table);
96
+ if (dto)
97
+ args.push("--dto");
98
+ if (dryRun)
99
+ args.push("--dry-run");
100
+ return (0, result_1.fromCli)(await (0, megh_1.runMegh)(project(cwd), args));
101
+ }));
102
+ server.registerTool("megh_scaffold_domain", {
103
+ title: "Scaffold a domain",
104
+ description: "Run megh scaffold:domain: create the migrations (and models or REST resources) of a domain's templates, e.g. ecommerce, pos, medical. See megh_list_templates for the domains.",
105
+ inputSchema: {
106
+ cwd: result_1.cwdArg,
107
+ domain: zod_1.z.string().min(1).describe("Domain name, e.g. ecommerce."),
108
+ only: zod_1.z.array(zod_1.z.string()).optional().describe("Only these templates, e.g. [product, order]. Default: every template."),
109
+ mode: zod_1.z
110
+ .enum(["model", "resource", "migration"])
111
+ .optional()
112
+ .describe("model (default): migrations and models; resource: also DTOs, service and controller; migration: migrations only."),
113
+ factory: zod_1.z.boolean().optional().describe("Also write a factory for each model."),
114
+ deps: zod_1.z.boolean().optional().describe("Create the tables foreign keys point to (default true)."),
115
+ force: zod_1.z.boolean().optional().describe("Overwrite the generated models' files."),
116
+ },
117
+ annotations: writes,
118
+ }, (0, result_1.safe)(async ({ cwd, domain, only, mode, factory, deps, force }) => {
119
+ const args = ["scaffold:domain", domain, "--yes"];
120
+ if (only?.length)
121
+ args.push("--only", only.join(","));
122
+ else
123
+ args.push("--all");
124
+ if (mode === "resource")
125
+ args.push("--resource");
126
+ if (mode === "migration")
127
+ args.push("--migrations-only");
128
+ if (factory)
129
+ args.push("--factory");
130
+ if (deps === false)
131
+ args.push("--no-deps");
132
+ if (force)
133
+ args.push("--force");
134
+ return (0, result_1.fromCli)(await (0, megh_1.runMegh)(project(cwd), args));
135
+ }));
136
+ server.registerTool("megh_scaffold_auth", {
137
+ title: "Scaffold authentication",
138
+ description: "Run megh scaffold:auth: add sign-up and sign-in. Writes the users table (and roles, permissions, api_keys as chosen) as migrations and models, src/auth/, an AuthService, DTOs and an AuthController (POST /auth/register, POST /auth/login, GET /auth/me), and registers them in src/app.ts.",
139
+ inputSchema: {
140
+ cwd: result_1.cwdArg,
141
+ strategy: zod_1.z.enum(exports.AUTH_STRATEGIES).optional().describe("How clients sign in (default jwt)."),
142
+ roles: zod_1.z.enum(["none", "single", "multiple"]).optional().describe("Roles per user (default none)."),
143
+ permissions: zod_1.z.boolean().optional().describe("Whether roles grant permissions."),
144
+ force: zod_1.z.boolean().optional().describe("Overwrite the generated auth files."),
145
+ },
146
+ annotations: writes,
147
+ }, (0, result_1.safe)(async ({ cwd, strategy, roles, permissions, force }) => {
148
+ const args = ["scaffold:auth", "--yes"];
149
+ if (strategy)
150
+ args.push("--strategy", strategy);
151
+ if (roles)
152
+ args.push("--roles", roles);
153
+ args.push(...tri("permissions", permissions));
154
+ if (force)
155
+ args.push("--force");
156
+ return (0, result_1.fromCli)(await (0, megh_1.runMegh)(project(cwd), args));
157
+ }));
158
+ server.registerTool("megh_scaffold_rbac", {
159
+ title: "Scaffold roles and permissions",
160
+ description: "Run megh scaffold:rbac: add roles (one or many per user) and optionally permissions to an app that already has users.",
161
+ inputSchema: {
162
+ cwd: result_1.cwdArg,
163
+ roles: zod_1.z.enum(["single", "multiple"]).optional().describe("Roles per user (default multiple)."),
164
+ permissions: zod_1.z.boolean().optional().describe("Whether roles grant permissions."),
165
+ force: zod_1.z.boolean().optional().describe("Overwrite the generated files."),
166
+ },
167
+ annotations: writes,
168
+ }, (0, result_1.safe)(async ({ cwd, roles, permissions, force }) => {
169
+ const args = ["scaffold:rbac", "--yes"];
170
+ if (roles)
171
+ args.push("--roles", roles);
172
+ args.push(...tri("permissions", permissions));
173
+ if (force)
174
+ args.push("--force");
175
+ return (0, result_1.fromCli)(await (0, megh_1.runMegh)(project(cwd), args));
176
+ }));
177
+ }
@@ -0,0 +1,3 @@
1
+ import type { ToolContext } from "./context";
2
+ /** Tools that read the project or check it compiles. None of them change source files. */
3
+ export declare function registerProjectTools({ server, project, readOnly }: ToolContext): void;
@@ -0,0 +1,84 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.registerProjectTools = registerProjectTools;
7
+ const fs_1 = __importDefault(require("fs"));
8
+ const path_1 = __importDefault(require("path"));
9
+ const cli_1 = require("@meghjs/cli");
10
+ const zod_1 = require("zod");
11
+ const megh_1 = require("../megh");
12
+ const result_1 = require("../result");
13
+ /** Tools that read the project or check it compiles. None of them change source files. */
14
+ function registerProjectTools({ server, project, readOnly }) {
15
+ server.registerTool("megh_project_info", {
16
+ title: "Project info",
17
+ description: "Show the Megh project's root, its @meghjs/* dependencies (declared and installed), npm scripts, `megh` settings from package.json and whether it runs in production.",
18
+ inputSchema: { cwd: result_1.cwdArg },
19
+ annotations: { readOnlyHint: true },
20
+ }, (0, result_1.safe)(({ cwd }) => (0, result_1.text)((0, megh_1.projectInfo)(project(cwd)))));
21
+ server.registerTool("megh_project_structure", {
22
+ title: "Project structure",
23
+ description: "List the project's source files grouped by kind (controllers, services, models, dtos, migrations, seeders, middlewares, events, queues, tests, ...), with counts and the app's entry file.",
24
+ inputSchema: { cwd: result_1.cwdArg },
25
+ annotations: { readOnlyHint: true },
26
+ }, (0, result_1.safe)(({ cwd }) => (0, result_1.text)((0, megh_1.projectStructure)(project(cwd)))));
27
+ server.registerTool("megh_doctor", {
28
+ title: "Doctor",
29
+ description: "Check the project's setup: Node.js version, @meghjs/core, reflect-metadata and the TypeScript decorator settings. Each check is ok, warn or fail.",
30
+ inputSchema: { cwd: result_1.cwdArg },
31
+ annotations: { readOnlyHint: true },
32
+ }, (0, result_1.safe)(({ cwd }) => (0, result_1.text)((0, cli_1.runChecks)(project(cwd)))));
33
+ server.registerTool("megh_list_routes", {
34
+ title: "List routes",
35
+ description: "List the app's HTTP routes (method, path, controller, handler, file). By default the sources are compiled and each *.controller.ts is loaded to read its route metadata, which needs @meghjs/core installed; set static to scan the decorators in the source instead.",
36
+ inputSchema: {
37
+ cwd: result_1.cwdArg,
38
+ static: zod_1.z
39
+ .boolean()
40
+ .optional()
41
+ .describe("Scan @ApiController/@Get/... decorators without running code (only string-literal paths)."),
42
+ },
43
+ annotations: { readOnlyHint: true },
44
+ }, (0, result_1.safe)(async ({ cwd, static: isStatic }) => (0, result_1.jsonFromCli)(await (0, megh_1.runMegh)(project(cwd), ["route:list", "--json", ...(isStatic ? ["--static"] : [])]))));
45
+ server.registerTool("megh_list_templates", {
46
+ title: "List model templates",
47
+ description: "List the model templates by domain (e.g. ecommerce/product). Give a domain to see each template's columns. Use them with megh_make (kind model or resource) or megh_scaffold_domain.",
48
+ inputSchema: {
49
+ cwd: result_1.cwdArg,
50
+ domain: zod_1.z.string().optional().describe("Show only this domain, with each template's columns."),
51
+ },
52
+ annotations: { readOnlyHint: true },
53
+ }, (0, result_1.safe)(async ({ cwd, domain }) => (0, result_1.jsonFromCli)(await (0, megh_1.runMegh)(project(cwd), ["template:list", ...(domain ? [domain] : []), "--json"]))));
54
+ server.registerTool("megh_typecheck", {
55
+ title: "Type-check",
56
+ description: "Run the project's TypeScript compiler without emitting (tsc --noEmit) and return the errors. Use it after changing code to check it still compiles.",
57
+ inputSchema: {
58
+ cwd: result_1.cwdArg,
59
+ project: zod_1.z.string().optional().describe("tsconfig to use, relative to the project. Defaults to tsconfig.json."),
60
+ },
61
+ annotations: { readOnlyHint: true },
62
+ }, (0, result_1.safe)(async ({ cwd, project: tsconfig }) => {
63
+ const root = project(cwd);
64
+ const config = tsconfig ?? "tsconfig.json";
65
+ if (!fs_1.default.existsSync(path_1.default.join(root, config)))
66
+ return (0, result_1.text)(`No ${config} in ${root}.`, true);
67
+ const r = await (0, megh_1.runNode)(root, (0, megh_1.tscBin)(root), ["--noEmit", "--pretty", "false", "-p", config]);
68
+ if (r.exitCode === 0)
69
+ return (0, result_1.text)("No type errors.");
70
+ const errors = r.stdout.split(/\r?\n/).filter((l) => /error TS\d+/.test(l)).length;
71
+ return (0, result_1.text)(`${errors} type error(s):\n\n${r.stdout.trim()}${r.stderr ? `\n\n${r.stderr.trim()}` : ""}`, true);
72
+ }));
73
+ if (readOnly)
74
+ return;
75
+ server.registerTool("megh_build", {
76
+ title: "Build",
77
+ description: "Run megh build: compile with tsc (tsconfig.build.json, else tsconfig.json) into the output folder and copy assets. Writes build output only, not sources.",
78
+ inputSchema: {
79
+ cwd: result_1.cwdArg,
80
+ project: zod_1.z.string().optional().describe("tsconfig to use instead of the default."),
81
+ },
82
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
83
+ }, (0, result_1.safe)(async ({ cwd, project: tsconfig }) => (0, result_1.fromCli)(await (0, megh_1.runMegh)(project(cwd), ["build", ...(tsconfig ? ["--project", tsconfig] : [])]))));
84
+ }
@@ -0,0 +1,2 @@
1
+ /** This package's version, read from its package.json (one level above dist/ and src/). */
2
+ export declare const version: string;
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.version = void 0;
7
+ const fs_1 = __importDefault(require("fs"));
8
+ const path_1 = __importDefault(require("path"));
9
+ /** This package's version, read from its package.json (one level above dist/ and src/). */
10
+ exports.version = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, "..", "package.json"), "utf8")).version;
package/package.json CHANGED
@@ -1,6 +1,60 @@
1
1
  {
2
2
  "name": "@meghjs/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.7.0",
4
+ "description": "Model Context Protocol server that lets AI assistants inspect and scaffold Megh applications",
5
+ "author": "Tareq Hossain",
6
+ "license": "MIT",
7
+ "main": "dist/index.js",
8
+ "types": "dist/index.d.ts",
9
+ "bin": {
10
+ "megh-mcp": "dist/bin.js"
11
+ },
12
+ "files": [
13
+ "dist",
14
+ "README.md",
15
+ "LICENSE"
16
+ ],
17
+ "engines": {
18
+ "node": ">=22"
19
+ },
20
+ "scripts": {
21
+ "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node scripts/copy-docs.js",
22
+ "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
23
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
24
+ "test": "vitest run",
25
+ "watch": "tsc -p tsconfig.json --watch",
26
+ "prepublishOnly": "npm run build"
27
+ },
28
+ "keywords": [
29
+ "megh",
30
+ "mcp",
31
+ "model-context-protocol",
32
+ "ai",
33
+ "claude",
34
+ "typescript",
35
+ "fastify"
36
+ ],
37
+ "dependencies": {
38
+ "@meghjs/cli": "^0.7.0",
39
+ "@modelcontextprotocol/sdk": "^1.32.2",
40
+ "zod": "^4.6.7"
41
+ },
42
+ "devDependencies": {
43
+ "@types/node": "^22.20.5",
44
+ "typescript": "^5.7.2",
45
+ "vitest": "^4.1.12"
46
+ },
47
+ "repository": {
48
+ "type": "git",
49
+ "url": "git+https://github.com/meghjs/megh.git",
50
+ "directory": "packages/mcp"
51
+ },
52
+ "homepage": "https://meghjs.github.io/ai/mcp",
53
+ "bugs": {
54
+ "url": "https://github.com/meghjs/megh/issues"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "gitHead": "8300fd94035696a7af16e470ae95d034d84cdf6e"
60
+ }