@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.
- package/.copilotignore +38 -0
- package/.devcontainer/Dockerfile.dev +28 -0
- package/.devcontainer/devcontainer.json +56 -0
- package/.devcontainer/docker-compose.yml +15 -0
- package/.dockerignore +37 -0
- package/.github/codeql-config.yml +4 -0
- package/.github/copilot-instructions.md +138 -0
- package/.github/prompts/memory.prompt.md +120 -0
- package/.github/workflows/auto-tag-release.yml +84 -0
- package/.github/workflows/codeql-analysis.yml +56 -0
- package/.github/workflows/npm-publish.yml +58 -0
- package/.github/workflows/pr-branch-validation.yml +78 -0
- package/.github/workflows/run-tests.yml +41 -0
- package/.github/workflows/sync-main-to-develop.yml +53 -0
- package/.handbook/GIT_GUIDELINES.md +250 -0
- package/.handbook/PACKAGE_VERSIONING.md +140 -0
- package/.handbook/STACK.md +75 -0
- package/.prettierrc +4 -0
- package/.vscode/extensions.json +44 -0
- package/.vscode/settings.json +40 -0
- package/CONTRIBUTING.md +261 -0
- package/LICENSE +21 -0
- package/README.md +490 -0
- package/dist/examples/async-import/app.module.d.ts +2 -0
- package/dist/examples/async-import/app.module.js +33 -0
- package/dist/examples/async-import/app.module.js.map +1 -0
- package/dist/examples/async-import/main.d.ts +1 -0
- package/dist/examples/async-import/main.js +17 -0
- package/dist/examples/async-import/main.js.map +1 -0
- package/dist/examples/guards/app.module.d.ts +6 -0
- package/dist/examples/guards/app.module.js +48 -0
- package/dist/examples/guards/app.module.js.map +1 -0
- package/dist/examples/guards/guards.resolver.d.ts +13 -0
- package/dist/examples/guards/guards.resolver.js +61 -0
- package/dist/examples/guards/guards.resolver.js.map +1 -0
- package/dist/examples/guards/main.d.ts +1 -0
- package/dist/examples/guards/main.js +11 -0
- package/dist/examples/guards/main.js.map +1 -0
- package/dist/examples/mixed/app.module.d.ts +2 -0
- package/dist/examples/mixed/app.module.js +31 -0
- package/dist/examples/mixed/app.module.js.map +1 -0
- package/dist/examples/mixed/main.d.ts +1 -0
- package/dist/examples/mixed/main.js +11 -0
- package/dist/examples/mixed/main.js.map +1 -0
- package/dist/examples/mixed/mixed.resolver.d.ts +6 -0
- package/dist/examples/mixed/mixed.resolver.js +78 -0
- package/dist/examples/mixed/mixed.resolver.js.map +1 -0
- package/dist/examples/prompts/app.module.d.ts +2 -0
- package/dist/examples/prompts/app.module.js +31 -0
- package/dist/examples/prompts/app.module.js.map +1 -0
- package/dist/examples/prompts/main.d.ts +1 -0
- package/dist/examples/prompts/main.js +11 -0
- package/dist/examples/prompts/main.js.map +1 -0
- package/dist/examples/prompts/prompts.resolver.d.ts +14 -0
- package/dist/examples/prompts/prompts.resolver.js +165 -0
- package/dist/examples/prompts/prompts.resolver.js.map +1 -0
- package/dist/examples/resources/app.module.d.ts +2 -0
- package/dist/examples/resources/app.module.js +31 -0
- package/dist/examples/resources/app.module.js.map +1 -0
- package/dist/examples/resources/main.d.ts +1 -0
- package/dist/examples/resources/main.js +11 -0
- package/dist/examples/resources/main.js.map +1 -0
- package/dist/examples/resources/resources.resolver.d.ts +12 -0
- package/dist/examples/resources/resources.resolver.js +114 -0
- package/dist/examples/resources/resources.resolver.js.map +1 -0
- package/dist/examples/tools/app.module.d.ts +2 -0
- package/dist/examples/tools/app.module.js +31 -0
- package/dist/examples/tools/app.module.js.map +1 -0
- package/dist/examples/tools/main.d.ts +1 -0
- package/dist/examples/tools/main.js +11 -0
- package/dist/examples/tools/main.js.map +1 -0
- package/dist/examples/tools/tools.resolver.d.ts +23 -0
- package/dist/examples/tools/tools.resolver.js +175 -0
- package/dist/examples/tools/tools.resolver.js.map +1 -0
- package/dist/src/controllers/sse/index.d.ts +2 -0
- package/dist/src/controllers/sse/index.js +19 -0
- package/dist/src/controllers/sse/index.js.map +1 -0
- package/dist/src/controllers/sse/sse.controller.d.ts +8 -0
- package/dist/src/controllers/sse/sse.controller.js +51 -0
- package/dist/src/controllers/sse/sse.controller.js.map +1 -0
- package/dist/src/controllers/sse/sse.service.d.ts +16 -0
- package/dist/src/controllers/sse/sse.service.js +78 -0
- package/dist/src/controllers/sse/sse.service.js.map +1 -0
- package/dist/src/controllers/streamable/index.d.ts +2 -0
- package/dist/src/controllers/streamable/index.js +19 -0
- package/dist/src/controllers/streamable/index.js.map +1 -0
- package/dist/src/controllers/streamable/streamable.controller.d.ts +9 -0
- package/dist/src/controllers/streamable/streamable.controller.js +62 -0
- package/dist/src/controllers/streamable/streamable.controller.js.map +1 -0
- package/dist/src/controllers/streamable/streamable.service.d.ts +24 -0
- package/dist/src/controllers/streamable/streamable.service.js +117 -0
- package/dist/src/controllers/streamable/streamable.service.js.map +1 -0
- package/dist/src/decorators/capabilities.constants.d.ts +4 -0
- package/dist/src/decorators/capabilities.constants.js +8 -0
- package/dist/src/decorators/capabilities.constants.js.map +1 -0
- package/dist/src/decorators/capabilities.decorators.d.ts +8 -0
- package/dist/src/decorators/capabilities.decorators.js +49 -0
- package/dist/src/decorators/capabilities.decorators.js.map +1 -0
- package/dist/src/decorators/index.d.ts +2 -0
- package/dist/src/decorators/index.js +19 -0
- package/dist/src/decorators/index.js.map +1 -0
- package/dist/src/index.d.ts +4 -0
- package/dist/src/index.js +21 -0
- package/dist/src/index.js.map +1 -0
- package/dist/src/interfaces/capabilities.interface.d.ts +52 -0
- package/dist/src/interfaces/capabilities.interface.js +3 -0
- package/dist/src/interfaces/capabilities.interface.js.map +1 -0
- package/dist/src/interfaces/guards.interface.d.ts +4 -0
- package/dist/src/interfaces/guards.interface.js +3 -0
- package/dist/src/interfaces/guards.interface.js.map +1 -0
- package/dist/src/interfaces/index.d.ts +2 -0
- package/dist/src/interfaces/index.js +19 -0
- package/dist/src/interfaces/index.js.map +1 -0
- package/dist/src/interfaces/mcp-server-options.interface.d.ts +42 -0
- package/dist/src/interfaces/mcp-server-options.interface.js +3 -0
- package/dist/src/interfaces/mcp-server-options.interface.js.map +1 -0
- package/dist/src/mcp.module.d.ts +13 -0
- package/dist/src/mcp.module.js +176 -0
- package/dist/src/mcp.module.js.map +1 -0
- package/dist/src/registry/discovery.service.d.ts +16 -0
- package/dist/src/registry/discovery.service.js +85 -0
- package/dist/src/registry/discovery.service.js.map +1 -0
- package/dist/src/registry/index.d.ts +2 -0
- package/dist/src/registry/index.js +19 -0
- package/dist/src/registry/index.js.map +1 -0
- package/dist/src/registry/logger.service.d.ts +16 -0
- package/dist/src/registry/logger.service.js +97 -0
- package/dist/src/registry/logger.service.js.map +1 -0
- package/dist/src/registry/registry.service.d.ts +14 -0
- package/dist/src/registry/registry.service.js +165 -0
- package/dist/src/registry/registry.service.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -0
- package/eslint.config.mjs +40 -0
- package/examples/README.md +56 -0
- package/examples/async-import/app.module.ts +22 -0
- package/examples/async-import/main.ts +15 -0
- package/examples/guards/app.module.ts +44 -0
- package/examples/guards/guards.resolver.ts +52 -0
- package/examples/guards/main.ts +11 -0
- package/examples/mixed/app.module.ts +20 -0
- package/examples/mixed/main.ts +11 -0
- package/examples/mixed/mixed.resolver.ts +56 -0
- package/examples/prompts/app.module.ts +20 -0
- package/examples/prompts/main.ts +11 -0
- package/examples/prompts/prompts.resolver.ts +184 -0
- package/examples/resources/app.module.ts +19 -0
- package/examples/resources/main.ts +11 -0
- package/examples/resources/resources.resolver.ts +123 -0
- package/examples/tools/app.module.ts +20 -0
- package/examples/tools/main.ts +11 -0
- package/examples/tools/tools.resolver.ts +205 -0
- package/nest-cli.json +8 -0
- package/package.json +106 -0
- package/scripts/npm-publish.js +301 -0
- package/src/controllers/sse/index.ts +2 -0
- package/src/controllers/sse/sse.controller.ts +19 -0
- package/src/controllers/sse/sse.service.ts +90 -0
- package/src/controllers/streamable/index.ts +2 -0
- package/src/controllers/streamable/streamable.controller.ts +24 -0
- package/src/controllers/streamable/streamable.service.ts +168 -0
- package/src/decorators/capabilities.constants.ts +7 -0
- package/src/decorators/capabilities.decorators.ts +150 -0
- package/src/decorators/index.ts +2 -0
- package/src/index.ts +11 -0
- package/src/interfaces/capabilities.interface.ts +95 -0
- package/src/interfaces/guards.interface.ts +13 -0
- package/src/interfaces/index.ts +2 -0
- package/src/interfaces/mcp-server-options.interface.ts +105 -0
- package/src/mcp.module.ts +233 -0
- package/src/mcp.service.spec.ts +28 -0
- package/src/registry/discovery.service.ts +116 -0
- package/src/registry/index.ts +2 -0
- package/src/registry/logger.service.ts +143 -0
- package/src/registry/registry.service.ts +281 -0
- package/test/base.e2e-spec.ts +74 -0
- package/test/jest-e2e.json +9 -0
- package/tsconfig.build.json +4 -0
- 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