@nestjs-mcp/server 0.1.0-alpha.4

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 (178) hide show
  1. package/.copilotignore +38 -0
  2. package/.devcontainer/Dockerfile.dev +28 -0
  3. package/.devcontainer/devcontainer.json +56 -0
  4. package/.devcontainer/docker-compose.yml +15 -0
  5. package/.dockerignore +37 -0
  6. package/.github/codeql-config.yml +4 -0
  7. package/.github/copilot-instructions.md +138 -0
  8. package/.github/prompts/memory.prompt.md +120 -0
  9. package/.github/workflows/auto-tag-release.yml +84 -0
  10. package/.github/workflows/codeql-analysis.yml +56 -0
  11. package/.github/workflows/npm-publish.yml +58 -0
  12. package/.github/workflows/pr-branch-validation.yml +78 -0
  13. package/.github/workflows/run-tests.yml +41 -0
  14. package/.github/workflows/sync-main-to-develop.yml +53 -0
  15. package/.handbook/GIT_GUIDELINES.md +250 -0
  16. package/.handbook/PACKAGE_VERSIONING.md +140 -0
  17. package/.handbook/STACK.md +75 -0
  18. package/.prettierrc +4 -0
  19. package/.vscode/extensions.json +44 -0
  20. package/.vscode/settings.json +40 -0
  21. package/CONTRIBUTING.md +261 -0
  22. package/LICENSE +21 -0
  23. package/README.md +490 -0
  24. package/dist/examples/async-import/app.module.d.ts +2 -0
  25. package/dist/examples/async-import/app.module.js +33 -0
  26. package/dist/examples/async-import/app.module.js.map +1 -0
  27. package/dist/examples/async-import/main.d.ts +1 -0
  28. package/dist/examples/async-import/main.js +17 -0
  29. package/dist/examples/async-import/main.js.map +1 -0
  30. package/dist/examples/guards/app.module.d.ts +6 -0
  31. package/dist/examples/guards/app.module.js +48 -0
  32. package/dist/examples/guards/app.module.js.map +1 -0
  33. package/dist/examples/guards/guards.resolver.d.ts +13 -0
  34. package/dist/examples/guards/guards.resolver.js +61 -0
  35. package/dist/examples/guards/guards.resolver.js.map +1 -0
  36. package/dist/examples/guards/main.d.ts +1 -0
  37. package/dist/examples/guards/main.js +11 -0
  38. package/dist/examples/guards/main.js.map +1 -0
  39. package/dist/examples/mixed/app.module.d.ts +2 -0
  40. package/dist/examples/mixed/app.module.js +31 -0
  41. package/dist/examples/mixed/app.module.js.map +1 -0
  42. package/dist/examples/mixed/main.d.ts +1 -0
  43. package/dist/examples/mixed/main.js +11 -0
  44. package/dist/examples/mixed/main.js.map +1 -0
  45. package/dist/examples/mixed/mixed.resolver.d.ts +6 -0
  46. package/dist/examples/mixed/mixed.resolver.js +78 -0
  47. package/dist/examples/mixed/mixed.resolver.js.map +1 -0
  48. package/dist/examples/prompts/app.module.d.ts +2 -0
  49. package/dist/examples/prompts/app.module.js +31 -0
  50. package/dist/examples/prompts/app.module.js.map +1 -0
  51. package/dist/examples/prompts/main.d.ts +1 -0
  52. package/dist/examples/prompts/main.js +11 -0
  53. package/dist/examples/prompts/main.js.map +1 -0
  54. package/dist/examples/prompts/prompts.resolver.d.ts +14 -0
  55. package/dist/examples/prompts/prompts.resolver.js +165 -0
  56. package/dist/examples/prompts/prompts.resolver.js.map +1 -0
  57. package/dist/examples/resources/app.module.d.ts +2 -0
  58. package/dist/examples/resources/app.module.js +31 -0
  59. package/dist/examples/resources/app.module.js.map +1 -0
  60. package/dist/examples/resources/main.d.ts +1 -0
  61. package/dist/examples/resources/main.js +11 -0
  62. package/dist/examples/resources/main.js.map +1 -0
  63. package/dist/examples/resources/resources.resolver.d.ts +12 -0
  64. package/dist/examples/resources/resources.resolver.js +114 -0
  65. package/dist/examples/resources/resources.resolver.js.map +1 -0
  66. package/dist/examples/tools/app.module.d.ts +2 -0
  67. package/dist/examples/tools/app.module.js +31 -0
  68. package/dist/examples/tools/app.module.js.map +1 -0
  69. package/dist/examples/tools/main.d.ts +1 -0
  70. package/dist/examples/tools/main.js +11 -0
  71. package/dist/examples/tools/main.js.map +1 -0
  72. package/dist/examples/tools/tools.resolver.d.ts +23 -0
  73. package/dist/examples/tools/tools.resolver.js +175 -0
  74. package/dist/examples/tools/tools.resolver.js.map +1 -0
  75. package/dist/src/controllers/sse/index.d.ts +2 -0
  76. package/dist/src/controllers/sse/index.js +19 -0
  77. package/dist/src/controllers/sse/index.js.map +1 -0
  78. package/dist/src/controllers/sse/sse.controller.d.ts +8 -0
  79. package/dist/src/controllers/sse/sse.controller.js +51 -0
  80. package/dist/src/controllers/sse/sse.controller.js.map +1 -0
  81. package/dist/src/controllers/sse/sse.service.d.ts +16 -0
  82. package/dist/src/controllers/sse/sse.service.js +78 -0
  83. package/dist/src/controllers/sse/sse.service.js.map +1 -0
  84. package/dist/src/controllers/streamable/index.d.ts +2 -0
  85. package/dist/src/controllers/streamable/index.js +19 -0
  86. package/dist/src/controllers/streamable/index.js.map +1 -0
  87. package/dist/src/controllers/streamable/streamable.controller.d.ts +9 -0
  88. package/dist/src/controllers/streamable/streamable.controller.js +62 -0
  89. package/dist/src/controllers/streamable/streamable.controller.js.map +1 -0
  90. package/dist/src/controllers/streamable/streamable.service.d.ts +24 -0
  91. package/dist/src/controllers/streamable/streamable.service.js +117 -0
  92. package/dist/src/controllers/streamable/streamable.service.js.map +1 -0
  93. package/dist/src/decorators/capabilities.constants.d.ts +4 -0
  94. package/dist/src/decorators/capabilities.constants.js +8 -0
  95. package/dist/src/decorators/capabilities.constants.js.map +1 -0
  96. package/dist/src/decorators/capabilities.decorators.d.ts +8 -0
  97. package/dist/src/decorators/capabilities.decorators.js +49 -0
  98. package/dist/src/decorators/capabilities.decorators.js.map +1 -0
  99. package/dist/src/decorators/index.d.ts +2 -0
  100. package/dist/src/decorators/index.js +19 -0
  101. package/dist/src/decorators/index.js.map +1 -0
  102. package/dist/src/index.d.ts +4 -0
  103. package/dist/src/index.js +21 -0
  104. package/dist/src/index.js.map +1 -0
  105. package/dist/src/interfaces/capabilities.interface.d.ts +52 -0
  106. package/dist/src/interfaces/capabilities.interface.js +3 -0
  107. package/dist/src/interfaces/capabilities.interface.js.map +1 -0
  108. package/dist/src/interfaces/guards.interface.d.ts +4 -0
  109. package/dist/src/interfaces/guards.interface.js +3 -0
  110. package/dist/src/interfaces/guards.interface.js.map +1 -0
  111. package/dist/src/interfaces/index.d.ts +2 -0
  112. package/dist/src/interfaces/index.js +19 -0
  113. package/dist/src/interfaces/index.js.map +1 -0
  114. package/dist/src/interfaces/mcp-server-options.interface.d.ts +42 -0
  115. package/dist/src/interfaces/mcp-server-options.interface.js +3 -0
  116. package/dist/src/interfaces/mcp-server-options.interface.js.map +1 -0
  117. package/dist/src/mcp.module.d.ts +13 -0
  118. package/dist/src/mcp.module.js +176 -0
  119. package/dist/src/mcp.module.js.map +1 -0
  120. package/dist/src/registry/discovery.service.d.ts +16 -0
  121. package/dist/src/registry/discovery.service.js +85 -0
  122. package/dist/src/registry/discovery.service.js.map +1 -0
  123. package/dist/src/registry/index.d.ts +2 -0
  124. package/dist/src/registry/index.js +19 -0
  125. package/dist/src/registry/index.js.map +1 -0
  126. package/dist/src/registry/logger.service.d.ts +16 -0
  127. package/dist/src/registry/logger.service.js +97 -0
  128. package/dist/src/registry/logger.service.js.map +1 -0
  129. package/dist/src/registry/registry.service.d.ts +14 -0
  130. package/dist/src/registry/registry.service.js +165 -0
  131. package/dist/src/registry/registry.service.js.map +1 -0
  132. package/dist/tsconfig.build.tsbuildinfo +1 -0
  133. package/eslint.config.mjs +40 -0
  134. package/examples/README.md +56 -0
  135. package/examples/async-import/app.module.ts +22 -0
  136. package/examples/async-import/main.ts +15 -0
  137. package/examples/guards/app.module.ts +44 -0
  138. package/examples/guards/guards.resolver.ts +52 -0
  139. package/examples/guards/main.ts +11 -0
  140. package/examples/mixed/app.module.ts +20 -0
  141. package/examples/mixed/main.ts +11 -0
  142. package/examples/mixed/mixed.resolver.ts +56 -0
  143. package/examples/prompts/app.module.ts +20 -0
  144. package/examples/prompts/main.ts +11 -0
  145. package/examples/prompts/prompts.resolver.ts +184 -0
  146. package/examples/resources/app.module.ts +19 -0
  147. package/examples/resources/main.ts +11 -0
  148. package/examples/resources/resources.resolver.ts +123 -0
  149. package/examples/tools/app.module.ts +20 -0
  150. package/examples/tools/main.ts +11 -0
  151. package/examples/tools/tools.resolver.ts +205 -0
  152. package/nest-cli.json +8 -0
  153. package/package.json +106 -0
  154. package/scripts/npm-publish.js +301 -0
  155. package/src/controllers/sse/index.ts +2 -0
  156. package/src/controllers/sse/sse.controller.ts +19 -0
  157. package/src/controllers/sse/sse.service.ts +90 -0
  158. package/src/controllers/streamable/index.ts +2 -0
  159. package/src/controllers/streamable/streamable.controller.ts +24 -0
  160. package/src/controllers/streamable/streamable.service.ts +168 -0
  161. package/src/decorators/capabilities.constants.ts +7 -0
  162. package/src/decorators/capabilities.decorators.ts +150 -0
  163. package/src/decorators/index.ts +2 -0
  164. package/src/index.ts +11 -0
  165. package/src/interfaces/capabilities.interface.ts +95 -0
  166. package/src/interfaces/guards.interface.ts +13 -0
  167. package/src/interfaces/index.ts +2 -0
  168. package/src/interfaces/mcp-server-options.interface.ts +105 -0
  169. package/src/mcp.module.ts +233 -0
  170. package/src/mcp.service.spec.ts +28 -0
  171. package/src/registry/discovery.service.ts +116 -0
  172. package/src/registry/index.ts +2 -0
  173. package/src/registry/logger.service.ts +143 -0
  174. package/src/registry/registry.service.ts +281 -0
  175. package/test/base.e2e-spec.ts +74 -0
  176. package/test/jest-e2e.json +9 -0
  177. package/tsconfig.build.json +4 -0
  178. package/tsconfig.json +23 -0
@@ -0,0 +1,78 @@
1
+ name: PR Branch Validation
2
+
3
+ on:
4
+ pull_request:
5
+ types: [opened, synchronize, reopened, edited]
6
+ branches: [develop, main, 'release/*']
7
+
8
+ jobs:
9
+ validate-pr-branches:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v3
13
+
14
+ - name: Install jq
15
+ run: sudo apt-get update && sudo apt-get install -y jq
16
+
17
+ - name: Validate PR source and target branches
18
+ run: |
19
+ # Get source and target branches
20
+ SOURCE_BRANCH="${{ github.head_ref }}"
21
+ TARGET_BRANCH="${{ github.base_ref }}"
22
+
23
+ echo "Validating PR from $SOURCE_BRANCH to $TARGET_BRANCH"
24
+
25
+ # Extract branch type
26
+ SOURCE_TYPE=$(echo $SOURCE_BRANCH | cut -d'/' -f1)
27
+
28
+ # Validate branch relationships based on workflow rules
29
+ if [[ "$SOURCE_TYPE" == "feature" ]] || [[ "$SOURCE_TYPE" == "bugfix" ]] || [[ "$SOURCE_TYPE" == "devfix" ]]; then
30
+ if [[ "$TARGET_BRANCH" != "develop" ]]; then
31
+ echo "ERROR: feature, bugfix, and devfix branches must target the develop branch."
32
+ exit 1
33
+ fi
34
+
35
+ elif [[ "$SOURCE_TYPE" == "hotfix" ]] || [[ "$SOURCE_TYPE" == "release" ]]; then
36
+ if [[ "$TARGET_BRANCH" != "main" ]]; then
37
+ echo "ERROR: hotfix and release branches must target the main branch."
38
+ echo "Note: Sync to develop will be handled automatically after merge to main."
39
+ exit 1
40
+ fi
41
+
42
+ elif [[ "$SOURCE_TYPE" == "relfix" ]]; then
43
+ if [[ ! "$TARGET_BRANCH" =~ ^release/ ]]; then
44
+ echo "ERROR: relfix branches must target a release branch."
45
+ exit 1
46
+ fi
47
+
48
+ else
49
+ echo "Unknown branch type: $SOURCE_TYPE"
50
+ exit 1
51
+ fi
52
+
53
+ echo "PR branch validation passed"
54
+
55
+ - name: Validate version is strictly progressive (release/hotfix to main only)
56
+ if: ((contains(github.head_ref, 'release/') || contains(github.head_ref, 'hotfix/')) && github.base_ref == 'main')
57
+ run: |
58
+ # Get the base and head commit SHAs
59
+ BASE_SHA="${{ github.event.pull_request.base.sha }}"
60
+ HEAD_SHA="${{ github.event.pull_request.head.sha }}"
61
+
62
+ # Fetch the base branch package.json
63
+ git fetch origin ${{ github.base_ref }}
64
+ git checkout $BASE_SHA -- package.json
65
+ BASE_VERSION=$(jq -r .version package.json)
66
+
67
+ # Fetch the head branch package.json
68
+ git checkout $HEAD_SHA -- package.json
69
+ HEAD_VERSION=$(jq -r .version package.json)
70
+
71
+ # Compare versions using semver
72
+ npx semver $HEAD_VERSION -r ">"$BASE_VERSION
73
+ if [ $? -ne 0 ]; then
74
+ echo "ERROR: Version in PR ($HEAD_VERSION) must be strictly greater than base branch ($BASE_VERSION)."
75
+ exit 1
76
+ fi
77
+
78
+ echo "Version progression validation passed."
@@ -0,0 +1,41 @@
1
+ name: Run Tests
2
+
3
+ on:
4
+ pull_request:
5
+ branches:
6
+ - 'release/*'
7
+ - 'hotfix/*'
8
+ - 'develop'
9
+
10
+ jobs:
11
+ test:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - name: Checkout code
15
+ uses: actions/checkout@v3
16
+
17
+ - name: Setup Node
18
+ uses: actions/setup-node@v3
19
+ with:
20
+ node-version: '22.x'
21
+ registry-url: 'https://registry.npmjs.org'
22
+
23
+ - name: Install PNPM
24
+ uses: pnpm/action-setup@v2
25
+ with:
26
+ version: 10
27
+
28
+ - name: Install dependencies
29
+ run: pnpm install --frozen-lockfile
30
+
31
+ - name: Run linter
32
+ run: pnpm lint
33
+
34
+ - name: Type check
35
+ run: pnpm typecheck
36
+
37
+ - name: Run unit tests
38
+ run: pnpm test
39
+
40
+ - name: Run build verification
41
+ run: pnpm run build
@@ -0,0 +1,53 @@
1
+ name: Sync Main to Develop
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+
8
+ jobs:
9
+ sync-branches:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v3
13
+ with:
14
+ fetch-depth: 0 # Required to access full commit history
15
+
16
+ - name: Install GitHub CLI
17
+ run: sudo apt-get update && sudo apt-get install -y gh
18
+
19
+ - name: Check merge source and create sync PR
20
+ env:
21
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
22
+ run: |
23
+ # Get the last commit message on main (the merge commit)
24
+ LAST_COMMIT_MSG=$(git log -1 --pretty=%B)
25
+
26
+ # Check if the merge was from a hotfix or release branch
27
+ if [[ "$LAST_COMMIT_MSG" =~ Merge\ pull\ request\ .*from\ .*hotfix/ ]] ||
28
+ [[ "$LAST_COMMIT_MSG" =~ Merge\ pull\ request\ .*from\ .*release/ ]]; then
29
+ echo "Detected merge from hotfix or release branch, syncing to develop."
30
+
31
+ # Create a temporary branch for the PR
32
+ SYNC_BRANCH="sync-main-to-develop-$(date +%s)"
33
+ git checkout -b $SYNC_BRANCH
34
+
35
+ # Attempt to merge main into develop
36
+ git fetch origin develop:develop
37
+ if git merge origin/develop --no-commit --no-ff; then
38
+ echo "No conflicts detected. Creating PR for automatic sync."
39
+ else
40
+ echo "Conflicts detected. PR will require manual resolution."
41
+ fi
42
+
43
+ git commit -am "Sync main to develop after hotfix/release merge"
44
+ git push origin $SYNC_BRANCH
45
+
46
+ gh pr create \
47
+ --base develop \
48
+ --head $SYNC_BRANCH \
49
+ --title "Auto-sync: main to develop" \
50
+ --body "Automated PR to sync changes from main to develop after hotfix or release merge. If this PR has conflicts, manual resolution is required."
51
+ else
52
+ echo "Push to main was not from a hotfix or release branch, no sync needed."
53
+ fi
@@ -0,0 +1,250 @@
1
+ # Git Guidelines <!-- omit in toc -->
2
+
3
+ This document defines the Git workflow, branch naming conventions, commit message standards, and pull request process for the MCP Server NestJS module library. Its objective is to ensure a consistent, maintainable, and collaborative development process, while enforcing best practices and compatibility with the @modelcontextprotocol/sdk. Use this guide to understand how to contribute, manage branches, and maintain code quality in this project.
4
+
5
+ ## Table of Contents <!-- omit in toc -->
6
+
7
+ - [Branch Structure](#branch-structure)
8
+ - [Workflow Diagram](#workflow-diagram)
9
+ - [Branch Naming Conventions](#branch-naming-conventions)
10
+ - [Commit Guidelines](#commit-guidelines)
11
+ - [Format](#format)
12
+ - [Types](#types)
13
+ - [Examples](#examples)
14
+ - [Pull Request Process](#pull-request-process)
15
+ - [Handling Conflicts](#handling-conflicts)
16
+ - [Branch Protection and Pull Request Rules](#branch-protection-and-pull-request-rules)
17
+ - [Revert and Rebase Policy](#revert-and-rebase-policy)
18
+ - [Automation](#automation)
19
+ - [Automatic Sync from Main to Develop](#automatic-sync-from-main-to-develop)
20
+ - [Special Workflow Cases](#special-workflow-cases)
21
+ - [Bugfixes vs Hotfixes vs Relfixes vs Devfixes](#bugfixes-vs-hotfixes-vs-relfixes-vs-devfixes)
22
+ - [Bugfix](#bugfix)
23
+ - [Hotfix](#hotfix)
24
+ - [Relfix](#relfix)
25
+ - [Devfix](#devfix)
26
+ - [Releases](#releases)
27
+ - [SemVer Versioning](#semver-versioning)
28
+ - [Version Progression Validation](#version-progression-validation)
29
+
30
+ This document outlines our Git workflow, branch naming conventions, and commit message guidelines.
31
+
32
+ ## Branch Structure
33
+
34
+ We follow a modified GitFlow workflow with the following branches:
35
+
36
+ | Branch Type | Created From | PR Target | Purpose |
37
+ | ----------------------- | ------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
38
+ | `main` | - | - (PR to develop if conflicts after hotfix/release merge) | Stable production code. If there are conflicts during the automatic sync to develop (after a hotfix or release merge), a PR from main to develop is required for conflict resolution. |
39
+ | `develop` | `main` | - | Latest changes, potentially unstable. Does not make PRs to main directly. |
40
+ | `feature/*` | `main` | `develop` | New features and enhancements |
41
+ | `bugfix/*` | `main` | `develop` | Non-urgent bug fixes that can wait for the next release |
42
+ | `hotfix/*` | `main` | `main` | Urgent production fixes that need immediate deployment |
43
+ | `relfix/*` | `release/*` | `release/*` | Bug fixes specifically for a release in preparation |
44
+ | `devfix/*` | `develop` | `develop` | Bug fixes for issues only present in develop |
45
+ | `release/*` | `develop` | `main` | Preparing a new release |
46
+ | `main → develop (auto)` | `main` | `develop` | Automatic sync after hotfix/release merge to main (if no conflicts; otherwise, manual resolution required via PR from main to develop) |
47
+
48
+ > Note: The PR from main to develop for conflict resolution may originate from either a hotfix or a release merge. The develop branch never makes PRs to main directly. All production releases flow through release or hotfix branches.
49
+
50
+ ## Workflow Diagram
51
+
52
+ ```
53
+ main ●─────────────●───────────●───────────●
54
+ \ ↑ ↑ / \
55
+ \ | | / \
56
+ develop ●───●───●───●──────────●────────● ↓
57
+ ↑ ↑ ↑ ↑ ↑ ↑ ●─── hotfix/critical
58
+ | | | | | |
59
+ feature/x ●───● | | | |
60
+ | | | |
61
+ feature/y ●───● | |
62
+ | | |
63
+ bugfix/z ●────● | |
64
+ | | |
65
+ devfix/d ●───────● | |
66
+ | |
67
+ release/1.0 ●────────●
68
+
69
+ relfix/r ●
70
+ ```
71
+
72
+ ## Branch Naming Conventions
73
+
74
+ - `feature/issue-{id}-{short-description}`: For new features
75
+ - `bugfix/issue-{id}-{short-description}`: For non-critical bug fixes that can wait for next release
76
+ - `hotfix/{version-number}`: For urgent production bug fixes requiring immediate deployment
77
+ - `relfix/issue-{id}-{short-description}`: For bug fixes specifically targeting a release in preparation
78
+ - `devfix/issue-{id}-{short-description}`: For bug fixes only present in the develop branch
79
+ - `release/{version-number}`: For release preparation (follows SemVer)
80
+
81
+ Examples:
82
+
83
+ - `feature/issue-42-user-authentication`
84
+ - `bugfix/issue-75-broken-login`
85
+ - `hotfix/1.2.1`
86
+ - `relfix/issue-83-validation-error`
87
+ - `devfix/issue-91-integration-failure`
88
+ - `release/1.2.0`
89
+
90
+ ## Commit Guidelines
91
+
92
+ We use conventional commits for clear and structured history.
93
+
94
+ ### Format
95
+
96
+ ```
97
+ <type>(<scope>): <subject>
98
+
99
+ <body>
100
+
101
+ <footer>
102
+ ```
103
+
104
+ ### Types
105
+
106
+ - `feat`: A new feature
107
+ - `fix`: A bug fix
108
+ - `docs`: Documentation changes
109
+ - `style`: Formatting changes
110
+ - `refactor`: Code restructuring without feature changes
111
+ - `perf`: Performance improvements
112
+ - `test`: Test additions or corrections
113
+ - `chore`: Build process or tool changes
114
+
115
+ ### Examples
116
+
117
+ ```
118
+ feat(auth): add user login functionality
119
+
120
+ Implement JWT-based authentication with refresh tokens.
121
+
122
+ Closes #24
123
+ ```
124
+
125
+ ```
126
+ fix(api): correct response status codes
127
+
128
+ Change HTTP status from 200 to 201 for resource creation endpoints.
129
+
130
+ Resolves #56
131
+ ```
132
+
133
+ ## Pull Request Process
134
+
135
+ 1. Create a branch from `main` using the appropriate naming convention
136
+ 2. Make your changes and commit them following the commit guidelines
137
+ 3. Pull the latest changes from the target branch
138
+ 4. Push your branch and create a PR to the appropriate target branch
139
+ 5. Request at least one reviewer
140
+ 6. Address any feedback from code reviews
141
+ 7. Once approved, the PR will be merged by a maintainer
142
+
143
+ ## Handling Conflicts
144
+
145
+ If conflicts arise when merging:
146
+
147
+ 1. Pull the latest changes from the target branch
148
+ 2. Resolve conflicts locally
149
+ 3. Commit the resolved conflicts
150
+ 4. Push the changes to your branch
151
+
152
+ ## Branch Protection and Pull Request Rules
153
+
154
+ - Only `main`, `develop`, and `release/*` branches accept pull requests. PRs to any other branch are not permitted.
155
+ - The branches `main`, `develop`, and all `release/*` branches **must be protected** against direct push and force push. Only merges via pull request are allowed.
156
+ - All other branches (e.g., `feature/*`, `bugfix/*`, `devfix/*`, `hotfix/*`, `relfix/*`) can receive updates via direct push.
157
+ - This ensures the stability and integrity of the main development and release branches, while allowing flexibility in feature and fix branches.
158
+
159
+ ## Revert and Rebase Policy
160
+
161
+ <!-- TODO: Define and document the policy for revert, squash, and rebase operations on protected branches. For now, follow standard Git best practices and avoid force pushes on protected branches. -->
162
+
163
+ ## Automation
164
+
165
+ All possible validations and checks (linting, tests, version progression, branch naming, etc.) are automated via CI/CD workflows. Manual steps should be minimized and clearly documented if required.
166
+
167
+ ## Automatic Sync from Main to Develop
168
+
169
+ After a `hotfix/*` or `release/*` branch is merged into `main`, an automated process will create a PR to sync `main` into `develop`. If there are no conflicts, this PR can be merged automatically. If conflicts are detected, manual resolution is required before merging.
170
+
171
+ ## Special Workflow Cases
172
+
173
+ ### Bugfixes vs Hotfixes vs Relfixes vs Devfixes
174
+
175
+ We use different branch types for different kinds of fixes:
176
+
177
+ #### Bugfix
178
+
179
+ For non-urgent issues that can wait for the next regular release:
180
+
181
+ 1. Create a `bugfix/` branch from `main`
182
+ 2. Fix the issue and commit changes
183
+ 3. Create a PR to `develop`
184
+ 4. Changes will go to production with the next release cycle
185
+
186
+ #### Hotfix
187
+
188
+ For urgent production issues requiring immediate deployment:
189
+
190
+ 1. Create a `hotfix/` branch from `main`
191
+ 2. Fix the issue and commit changes
192
+ 3. Create a PR to `main`
193
+ 4. After approval, merge to `main`
194
+ 5. An automated PR will sync `main` to `develop` (manual conflict resolution may be required)
195
+ 6. Deploy to production immediately after merging to `main`
196
+
197
+ #### Relfix
198
+
199
+ For issues found during release preparation:
200
+
201
+ 1. Create a `relfix/` branch from the specific `release/*` branch
202
+ 2. Fix the issue and commit changes
203
+ 3. Create a PR targeted to the same `release/*` branch
204
+ 4. These changes will be included when the release is merged to `main`
205
+
206
+ #### Devfix
207
+
208
+ For issues only present in the develop branch:
209
+
210
+ 1. Create a `devfix/` branch from `develop`
211
+ 2. Fix the issue and commit changes
212
+ 3. Create a PR to `develop`
213
+ 4. These fixes prevent unstable code from propagating further
214
+
215
+ ### Releases
216
+
217
+ To prepare a new release (using SemVer):
218
+
219
+ 1. Create a `release/` branch from `develop` (e.g., `release/1.2.0`)
220
+ 2. Only `relfix/` branches can be merged into this branch
221
+ 3. When ready, create a PR from `release/*` to `main`
222
+ 4. After approval, merge to `main`
223
+ 5. An automated PR will sync `main` to `develop` (manual conflict resolution may be required)
224
+ 6. Tag the release in `main` with the version number
225
+
226
+ ### SemVer Versioning
227
+
228
+ We follow Semantic Versioning (SemVer) for our releases:
229
+
230
+ - `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
231
+ - `MAJOR`: Breaking changes
232
+ - `MINOR`: New features, non-breaking
233
+ - `PATCH`: Hotfixes and critical bug fixes
234
+
235
+ Examples:
236
+
237
+ - `1.0.0`: Initial release
238
+ - `1.1.0`: New feature added
239
+ - `1.1.1`: Hotfix for a critical issue
240
+ - `2.0.0`: Breaking changes
241
+
242
+ ## Version Progression Validation
243
+
244
+ For pull requests from `release/*` or `hotfix/*` branches targeting `main`, the version in the PR **must be strictly greater than** the version currently in `main`. This is enforced automatically by CI:
245
+
246
+ - The PR will be rejected if the version is equal to or less than the current version in `main`.
247
+ - This ensures that all production releases are progressive and prevents accidental downgrades or duplicate versions.
248
+ - This rule does not apply to other branch types or targets.
249
+
250
+ > **Tip:** Always bump the version as the first step in your release or hotfix branch.
@@ -0,0 +1,140 @@
1
+ # Package Versioning Guidelines <!-- omit in toc -->
2
+
3
+ This document describes the versioning policy and release process for all packages in the MCP Server NestJS module library. Its objective is to ensure clear, progressive, and predictable versioning for all releases, maintain compatibility with the @modelcontextprotocol/sdk, and provide guidance for stable and pre-release workflows. Use this guide to understand how to version, tag, and publish packages in this project.
4
+
5
+ ## Table of Contents <!-- omit in toc -->
6
+
7
+ - [Overview](#overview)
8
+ - [Version Format](#version-format)
9
+ - [Pre-release Identifiers](#pre-release-identifiers)
10
+ - [Tagging and Publishing](#tagging-and-publishing)
11
+ - [Progressive Versioning](#progressive-versioning)
12
+ - [Version Progression Validation](#version-progression-validation)
13
+ - [Branching and Release Flow](#branching-and-release-flow)
14
+ - [Release Flow](#release-flow)
15
+ - [Automation](#automation)
16
+ - [Best Practices](#best-practices)
17
+ - [Publication Policy](#publication-policy)
18
+
19
+ ## Overview
20
+
21
+ This document defines the versioning strategy for all packages in this repository. The goal is to ensure clear, progressive, and predictable versioning for all releases, including pre-releases and stable versions.
22
+
23
+ ## Version Format
24
+
25
+ We follow [Semantic Versioning 2.0.0](https://semver.org/) as the baseline:
26
+
27
+ ```
28
+ MAJOR.MINOR.PATCH[-PRERELEASE]
29
+ ```
30
+
31
+ - **MAJOR**: Incompatible API changes
32
+ - **MINOR**: Backwards-compatible functionality
33
+ - **PATCH**: Backwards-compatible bug fixes
34
+ - **PRERELEASE**: Optional, for alpha/beta/rc versions
35
+
36
+ ## Pre-release Identifiers
37
+
38
+ Pre-release versions are denoted by a hyphen and a label after the patch number:
39
+
40
+ - `-alpha`: Early preview, unstable, not feature-complete
41
+ - `-beta`: Feature-complete, but may contain known issues
42
+ - `-rc`: Release candidate, stable unless critical bugs are found
43
+
44
+ **Examples:**
45
+
46
+ - `1.2.0-alpha.1`
47
+ - `1.2.0-beta.2`
48
+ - `1.2.0-rc.1`
49
+ - `1.2.0` (final release)
50
+
51
+ ## Tagging and Publishing
52
+
53
+ The version field in `package.json` (package version) must strictly follow the format: `X.Y.Z` or `X.Y.Z-prerelease` (e.g., `1.2.3`, `1.2.3-beta.1`). The version must never include a `v` prefix.
54
+
55
+ - **Stable releases**: package version as `X.Y.Z`.
56
+ - **Pre-releases**: package version as `X.Y.Z-prerelease.N` (e.g., `1.2.3-beta.1`).
57
+
58
+ ## Progressive Versioning
59
+
60
+ - **All new versions MUST be strictly greater than previous versions.**
61
+ - **Never publish a version that is equal to or less than an existing version.**
62
+ - This ensures consumers always receive the latest, most appropriate version and avoids confusion or accidental downgrades.
63
+
64
+ ## Version Progression Validation
65
+
66
+ All new versions MUST be strictly greater than previous versions. This is enforced automatically by CI/CD:
67
+
68
+ - For pull requests from `release/*` or `hotfix/*` branches targeting `main`, the workflow checks that the version in the PR is strictly greater than the version in `main`.
69
+ - If the version is not progressive, the PR will be rejected and must be corrected before merging.
70
+ - This prevents accidental downgrades or duplicate versions in production.
71
+
72
+ ## Branching and Release Flow
73
+
74
+ - **Feature, bugfix, and devfix branches**: Merge into `develop` only.
75
+ - **Release and hotfix branches**: Merge into `main` only.
76
+ - **Relfix branches**: Merge into a `release/*` branch only.
77
+ - **Version numbers must always increase** with each release, regardless of branch.
78
+
79
+ ## Release Flow
80
+
81
+ The complete release process is as follows:
82
+
83
+ 1. Prepare a `release/*` or `hotfix/*` branch with the new version in `package.json`.
84
+ 2. Create a PR to `main`. The CI will validate version progression and run tests.
85
+ 3. Once merged, the CI workflow will create a tag on `main`.
86
+ 4. The publish workflow will build and publish the package to NPM, assigning the correct NPM tag.
87
+ 5. An automated PR will sync `main` to `develop` to keep branches aligned.
88
+
89
+ > Always ensure the version is bumped before creating the PR to `main`.
90
+
91
+ ## Automation
92
+
93
+ - CI/CD workflows will:
94
+ - Validate that new versions are strictly progressive.
95
+ - Tag releases according to the pre-release identifier.
96
+ - Prevent publishing if the version is not greater than the previous.
97
+
98
+ ## Best Practices
99
+
100
+ - Bump the version as soon as a change is made that warrants it.
101
+ - Use pre-release identifiers for unstable or preview releases.
102
+ - Only remove the pre-release identifier (`-alpha`, `-beta`, `-rc`) when the release is considered stable.
103
+ - Document breaking changes and version bumps in the changelog.
104
+
105
+ ## Publication Policy
106
+
107
+ This project follows [Semantic Versioning 2.0.0](https://semver.org/). All releases must:
108
+
109
+ - Use strictly increasing version numbers (no downgrades or duplicates)
110
+ - Use pre-release identifiers (`-alpha`, `-beta`, `-rc`) for unstable or preview releases
111
+ - Only remove the pre-release identifier when the release is considered stable
112
+ - Document breaking changes and version bumps in the changelog
113
+
114
+ ### Branching and Release Flow
115
+
116
+ - Only `release/*` and `fix/*` branches are allowed for publishing
117
+ - Final releases are only allowed from `release/*` branches
118
+ - Pre-releases (alpha, beta, rc) are allowed from `release/*` and `fix/*` branches
119
+ - All other branches must merge into `develop` or follow the project's branching model
120
+
121
+ ### Pre-release Identifiers
122
+
123
+ - `-alpha`: Early preview, unstable, not feature-complete
124
+ - `-beta`: Feature-complete, but may contain known issues
125
+ - `-rc`: Release candidate, stable unless critical bugs are found
126
+
127
+ ### Tagging and Publishing
128
+
129
+ - The version in `package.json` must match the intended release type and follow semver
130
+ - The correct NPM tag and access must be used for each release type (see project scripts)
131
+ - Always increment the version before publishing
132
+
133
+ ### Automation
134
+
135
+ - CI/CD workflows must enforce version progression and correct tagging
136
+ - Publishing must be blocked if the version is not strictly greater than the previous
137
+
138
+ ---
139
+
140
+ **For implementation details and scripts, see the project README or scripts directory.**
@@ -0,0 +1,75 @@
1
+ # Tech Stack <!-- omit in toc -->
2
+
3
+ This document provides an overview of the core technologies, tools, and configurations used in the MCP Server NestJS module library. Its objective is to clarify the project's technical foundation, ensure consistency across development environments, and help contributors understand the stack requirements for building, testing, and maintaining modules compatible with the @modelcontextprotocol/sdk.
4
+
5
+ # Table of Contents <!-- omit in toc -->
6
+
7
+ - [Framework](#framework)
8
+ - [Language \& Transpilation](#language--transpilation)
9
+ - [Package Management](#package-management)
10
+ - [Linting](#linting)
11
+ - [Code Formatter](#code-formatter)
12
+ - [Testing](#testing)
13
+ - [Build](#build)
14
+ - [Logger](#logger)
15
+ - [Documentation](#documentation)
16
+ - [Environment Management](#environment-management)
17
+ - [CI/CD](#cicd)
18
+ - [Other](#other)
19
+
20
+ This project is built primarily with **NestJS** as the main framework. All modules, services, and controllers are designed following NestJS best practices and conventions.
21
+
22
+ The stack and tooling are organized by category, with the primary technology for each area explicitly listed:
23
+
24
+ ## Framework
25
+
26
+ - **NestJS**: Main application framework for building scalable server-side applications
27
+
28
+ ## Language & Transpilation
29
+
30
+ - **TypeScript**: Main language for all source code
31
+
32
+ ## Package Management
33
+
34
+ - **pnpm**: For dependency management and scripts
35
+ - **npm**: Only for package publishing
36
+
37
+ ## Linting
38
+
39
+ - **ESLint**: Code linting (see `eslint.config.mjs`)
40
+
41
+ ## Code Formatter
42
+
43
+ - **Prettier**: Code formatting (if `.prettierrc` is present)
44
+
45
+ ## Testing
46
+
47
+ - **Jest**: Unit and end-to-end testing
48
+
49
+ ## Build
50
+
51
+ - **TypeScript Compiler (tsc)**: Build process (see `tsconfig.json` and `tsconfig.build.json`)
52
+
53
+ ## Logger
54
+
55
+ - **NestJS Logger**: Default logger for application and modules
56
+ - **Custom Logger**: `mcp-logger.service.ts` for registry-specific logging
57
+
58
+ ## Documentation
59
+
60
+ - **Swagger**: (If present) For API documentation via decorators
61
+ - **Typedoc**: (If present) For code documentation
62
+
63
+ ## Environment Management
64
+
65
+ - **dotenv**: (If present) For environment variable management
66
+
67
+ ## CI/CD
68
+
69
+ - **GitHub Actions**: For continuous integration and deployment workflows
70
+
71
+ ## Other
72
+
73
+ - **@modelcontextprotocol/sdk**: Core dependency for MCP Server compatibility
74
+
75
+ > All tools must be used in the versions specified in the workflows and configuration files to ensure compatibility and reproducibility.
package/.prettierrc ADDED
@@ -0,0 +1,4 @@
1
+ {
2
+ "singleQuote": true,
3
+ "trailingComma": "all"
4
+ }