```
├── .gitattributes (omitted)
├── .github/
├── pull_request_template.md (400 tokens)
├── workflows/
├── claude.yml (400 tokens)
├── python.yml (700 tokens)
├── readme-pr-check.yml (1000 tokens)
├── release.yml (1400 tokens)
├── typescript.yml (500 tokens)
├── .gitignore (1100 tokens)
├── .mcp.json
├── .npmrc
├── CLAUDE.md (800 tokens)
├── CODE_OF_CONDUCT.md (1000 tokens)
├── CONTRIBUTING.md (500 tokens)
├── LICENSE (omitted)
├── README.md (4.9k tokens)
├── SECURITY.md (200 tokens)
├── package-lock.json (omitted)
├── package.json (200 tokens)
├── scripts/
├── release.py (1200 tokens)
├── src/
├── everything/
├── .prettierignore
├── AGENTS.md (600 tokens)
├── Dockerfile (100 tokens)
├── README.md (1000 tokens)
├── __tests__/
├── prompts.test.ts (1300 tokens)
├── registrations.test.ts (1100 tokens)
├── resources.test.ts (2.2k tokens)
├── server.test.ts (200 tokens)
├── tools.test.ts (5.8k tokens)
├── docs/
├── architecture.md (300 tokens)
├── extension.md (200 tokens)
├── features.md (1800 tokens)
├── how-it-works.md (600 tokens)
├── instructions.md (300 tokens)
├── startup.md (600 tokens)
├── structure.md (1900 tokens)
├── index.ts (300 tokens)
├── package.json (300 tokens)
├── prompts/
├── args.ts (200 tokens)
├── completions.ts (400 tokens)
├── index.ts (100 tokens)
├── resource.ts (500 tokens)
├── simple.ts (100 tokens)
├── resources/
├── files.ts (500 tokens)
├── index.ts (200 tokens)
├── session.ts (500 tokens)
├── subscriptions.ts (1200 tokens)
├── templates.ts (1500 tokens)
├── server/
├── index.ts (700 tokens)
├── logging.ts (600 tokens)
├── roots.ts (600 tokens)
├── tools/
├── echo.ts (200 tokens)
├── get-annotated-message.ts (600 tokens)
├── get-env.ts (200 tokens)
├── get-resource-links.ts (500 tokens)
├── get-resource-reference.ts (600 tokens)
├── get-roots-list.ts (700 tokens)
├── get-structured-content.ts (500 tokens)
├── get-sum.ts (300 tokens)
├── get-tiny-image.ts (1300 tokens)
├── gzip-file-as-resource.ts (1700 tokens)
├── index.ts (500 tokens)
├── simulate-research-query.ts (2.3k tokens)
├── toggle-simulated-logging.ts (400 tokens)
├── toggle-subscriber-updates.ts (400 tokens)
├── trigger-elicitation-request-async.ts (1800 tokens)
├── trigger-elicitation-request.ts (1800 tokens)
├── trigger-long-running-operation.ts (500 tokens)
├── trigger-sampling-request-async.ts (1500 tokens)
├── trigger-sampling-request.ts (600 tokens)
├── transports/
├── sse.ts (500 tokens)
├── stdio.ts (200 tokens)
├── streamableHttp.ts (1500 tokens)
├── tsconfig.json
├── vitest.config.ts (100 tokens)
├── fetch/
├── .python-version
├── Dockerfile (200 tokens)
├── LICENSE (200 tokens)
├── README.md (1500 tokens)
├── pyproject.toml (200 tokens)
├── src/
├── mcp_server_fetch/
├── __init__.py (100 tokens)
├── __main__.py
├── server.py (2.1k tokens)
├── tests/
├── __init__.py
├── test_server.py (2.5k tokens)
├── uv.lock (omitted)
├── filesystem/
├── Dockerfile (100 tokens)
├── README.md (2.9k tokens)
├── __tests__/
├── directory-tree.test.ts (1200 tokens)
├── lib.test.ts (5.2k tokens)
├── path-utils.test.ts (2.8k tokens)
├── path-validation.test.ts (8.7k tokens)
├── roots-utils.test.ts (600 tokens)
├── startup-validation.test.ts (700 tokens)
├── structured-content.test.ts (1100 tokens)
├── index.ts (5.5k tokens)
├── lib.ts (2.8k tokens)
├── package.json (200 tokens)
├── path-utils.ts (900 tokens)
├── path-validation.ts (500 tokens)
├── roots-utils.ts (600 tokens)
├── tsconfig.json (100 tokens)
├── vitest.config.ts (100 tokens)
├── git/
├── .gitignore
├── .python-version
├── Dockerfile (300 tokens)
├── LICENSE (200 tokens)
├── README.md (2.2k tokens)
├── pyproject.toml (200 tokens)
├── src/
├── mcp_server_git/
├── __init__.py (100 tokens)
├── __main__.py
├── py.typed
├── server.py (4.2k tokens)
├── tests/
├── test_server.py (3.4k tokens)
├── uv.lock (omitted)
├── memory/
├── Dockerfile (100 tokens)
├── README.md (2k tokens)
├── __tests__/
├── file-path.test.ts (1000 tokens)
├── knowledge-graph.test.ts (3.9k tokens)
├── index.ts (3.2k tokens)
├── package.json (200 tokens)
├── tsconfig.json
├── vitest.config.ts (100 tokens)
├── sequentialthinking/
├── Dockerfile (100 tokens)
├── README.md (1500 tokens)
├── __tests__/
├── lib.test.ts (1700 tokens)
├── index.ts (1100 tokens)
├── lib.ts (600 tokens)
├── package.json (200 tokens)
├── tsconfig.json
├── vitest.config.ts (100 tokens)
├── time/
├── .python-version
├── Dockerfile (300 tokens)
├── README.md (1500 tokens)
├── pyproject.toml (200 tokens)
├── src/
├── mcp_server_time/
├── __init__.py (100 tokens)
├── __main__.py
├── server.py (1600 tokens)
├── test/
├── time_server_test.py (3.6k tokens)
├── uv.lock (omitted)
├── tsconfig.json (100 tokens)
```
## /.github/pull_request_template.md
<!-- Provide a brief description of your changes -->
## Description
## Publishing Your Server
**Note: We are no longer accepting PRs to add servers to the README.** Instead, please publish your server to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) to make it discoverable to the MCP ecosystem.
To publish your server, follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx). You can browse published servers at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/).
## Server Details
<!-- If modifying an existing server, provide details -->
- Server: <!-- e.g., filesystem, github -->
- Changes to: <!-- e.g., tools, resources, prompts -->
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
## How Has This Been Tested?
<!-- Have you tested this with an LLM client? Which scenarios were tested? -->
## Breaking Changes
<!-- Will users need to update their MCP client configurations? -->
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes that apply. -->
- [ ] I have read the [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [ ] My changes follows MCP security best practices
- [ ] I have updated the server's README accordingly
- [ ] I have tested this with an LLM client
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have documented all environment variables and configuration options
## Additional context
<!-- Add any other context, implementation notes, or design decisions -->
## /.github/workflows/claude.yml
```yml path="/.github/workflows/claude.yml"
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]
pull_request_review:
types: [submitted]
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
actions: read
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 1
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# Allow Claude to read CI results on PRs
additional_permissions: |
actions: read
# Trigger when assigned to an issue
assignee_trigger: "claude"
claude_args: |
--mcp-config .mcp.json
--allowedTools "Bash,mcp__mcp-docs,WebFetch"
--append-system-prompt "If posting a comment to GitHub, give a concise summary of the comment at the top and put all the details in a <details> block. When working on MCP-related code or reviewing MCP-related changes, use the mcp-docs MCP server to look up the latest protocol documentation. For schema details, reference https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema which contains versioned schemas in JSON (schema.json) and TypeScript (schema.ts) formats."
```
## /.github/workflows/python.yml
```yml path="/.github/workflows/python.yml"
name: Python
on:
push:
branches:
- main
pull_request:
release:
types: [published]
jobs:
detect-packages:
runs-on: ubuntu-latest
outputs:
packages: ${{ steps.find-packages.outputs.packages }}
steps:
- uses: actions/checkout@v6
- name: Find Python packages
id: find-packages
working-directory: src
run: |
PACKAGES=$(find . -name pyproject.toml -exec dirname {} \; | sed 's/^\.\///' | jq -R -s -c 'split("\n")[:-1]')
echo "packages=$PACKAGES" >> $GITHUB_OUTPUT
test:
needs: [detect-packages]
strategy:
matrix:
package: ${{ fromJson(needs.detect-packages.outputs.packages) }}
name: Test ${{ matrix.package }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Install uv
uses: astral-sh/setup-uv@v3
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version-file: "src/${{ matrix.package }}/.python-version"
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: uv sync --frozen --all-extras --dev
- name: Check if tests exist
id: check-tests
working-directory: src/${{ matrix.package }}
run: |
if [ -d "tests" ] || [ -d "test" ] || grep -q "pytest" pyproject.toml; then
echo "has-tests=true" >> $GITHUB_OUTPUT
else
echo "has-tests=false" >> $GITHUB_OUTPUT
fi
- name: Run tests
if: steps.check-tests.outputs.has-tests == 'true'
working-directory: src/${{ matrix.package }}
run: uv run pytest
build:
needs: [detect-packages, test]
strategy:
matrix:
package: ${{ fromJson(needs.detect-packages.outputs.packages) }}
name: Build ${{ matrix.package }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Install uv
uses: astral-sh/setup-uv@v3
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version-file: "src/${{ matrix.package }}/.python-version"
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: uv sync --locked --all-extras --dev
- name: Run pyright
working-directory: src/${{ matrix.package }}
run: uv run --frozen pyright
- name: Build package
working-directory: src/${{ matrix.package }}
run: uv build
- name: Upload artifacts
uses: actions/upload-artifact@v6
with:
name: dist-${{ matrix.package }}
path: src/${{ matrix.package }}/dist/
publish:
runs-on: ubuntu-latest
needs: [build, detect-packages]
if: github.event_name == 'release'
strategy:
matrix:
package: ${{ fromJson(needs.detect-packages.outputs.packages) }}
name: Publish ${{ matrix.package }}
environment: release
permissions:
id-token: write # Required for trusted publishing
steps:
- name: Download artifacts
uses: actions/download-artifact@v7
with:
name: dist-${{ matrix.package }}
path: dist/
- name: Publish package to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
```
## /.github/workflows/readme-pr-check.yml
```yml path="/.github/workflows/readme-pr-check.yml"
name: README PR Check
on:
pull_request:
types: [opened]
paths:
- 'README.md'
issue_comment:
types: [created]
jobs:
check-readme-only:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- name: Check files and comment if README-only
uses: actions/github-script@v8
with:
script: |
const { owner, repo } = context.repo;
const prNumber = context.payload.pull_request.number;
const { data: files } = await github.rest.pulls.listFiles({ owner, repo, pull_number: prNumber });
if (files.length !== 1 || files[0].filename !== 'README.md') {
console.log('PR modifies files other than README, skipping');
return;
}
// Check if we've already commented
const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number: prNumber });
if (comments.some(c => c.user.login === 'github-actions[bot]' && c.body.includes('no longer accepting PRs to add new servers'))) {
console.log('Already commented on this PR, skipping');
return;
}
await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['readme: pending'] });
await github.rest.issues.createComment({
owner,
repo,
issue_number: prNumber,
body: [
'Thanks for your contribution!',
'',
'**We are no longer accepting PRs to add new servers to the README.** The third-party server list has been removed from this README in favor of the [MCP Server Registry](https://registry.modelcontextprotocol.io/).',
'',
'👉 **To add a new MCP server:** Please publish it to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead. You can browse published servers at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/).',
'',
'👉 **If this PR updates or removes an existing entry:** We do still accept these changes. Please reply with `/i-promise-this-is-not-a-new-server` to continue.',
'',
'If this PR is adding a new server, please close it and submit to the registry instead.',
].join('\n'),
});
handle-confirmation:
if: github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '/i-promise-this-is-not-a-new-server')
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- name: Swap labels and minimize comments
uses: actions/github-script@v8
with:
script: |
const { owner, repo } = context.repo;
const prNumber = context.payload.issue.number;
// Check if pending label exists
const { data: labels } = await github.rest.issues.listLabelsOnIssue({ owner, repo, issue_number: prNumber });
if (!labels.some(l => l.name === 'readme: pending')) {
console.log('No pending label found, skipping');
return;
}
// Swap labels
try {
await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'readme: pending' });
} catch (e) {}
await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['readme: ready for review'] });
// Find the bot's original comment
const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number: prNumber });
const botComment = comments.find(c =>
c.user.login === 'github-actions[bot]' &&
c.body.includes('no longer accepting PRs to add new servers')
);
// Minimize both comments via GraphQL
const minimizeComment = async (nodeId) => {
await github.graphql(`
mutation($id: ID!) {
minimizeComment(input: {subjectId: $id, classifier: RESOLVED}) {
minimizedComment { isMinimized }
}
}
`, { id: nodeId });
};
if (botComment) {
await minimizeComment(botComment.node_id);
}
// Only minimize user's comment if it's just the command
const userComment = context.payload.comment.body.trim();
if (userComment === '/i-promise-this-is-not-a-new-server') {
await minimizeComment(context.payload.comment.node_id);
}
```
## /.github/workflows/release.yml
```yml path="/.github/workflows/release.yml"
name: Automatic Release Creation
on:
workflow_dispatch:
schedule:
- cron: '0 10 * * *'
jobs:
create-metadata:
runs-on: ubuntu-latest
if: github.repository_owner == 'modelcontextprotocol'
outputs:
hash: ${{ steps.last-release.outputs.hash }}
version: ${{ steps.create-version.outputs.version}}
npm_packages: ${{ steps.create-npm-packages.outputs.npm_packages}}
pypi_packages: ${{ steps.create-pypi-packages.outputs.pypi_packages}}
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Get last release hash
id: last-release
run: |
HASH=$(git rev-list --tags --max-count=1 || echo "HEAD~1")
echo "hash=${HASH}" >> $GITHUB_OUTPUT
echo "Using last release hash: ${HASH}"
- name: Install uv
uses: astral-sh/setup-uv@v5
- name: Create version name
id: create-version
run: |
VERSION=$(uv run --script scripts/release.py generate-version)
echo "version $VERSION"
echo "version=$VERSION" >> $GITHUB_OUTPUT
- name: Create notes
run: |
HASH="${{ steps.last-release.outputs.hash }}"
uv run --script scripts/release.py generate-notes --directory src/ $HASH > RELEASE_NOTES.md
cat RELEASE_NOTES.md
- name: Release notes
uses: actions/upload-artifact@v6
with:
name: release-notes
path: RELEASE_NOTES.md
- name: Create python matrix
id: create-pypi-packages
run: |
HASH="${{ steps.last-release.outputs.hash }}"
PYPI=$(uv run --script scripts/release.py generate-matrix --pypi --directory src $HASH)
echo "pypi_packages $PYPI"
echo "pypi_packages=$PYPI" >> $GITHUB_OUTPUT
- name: Create npm matrix
id: create-npm-packages
run: |
HASH="${{ steps.last-release.outputs.hash }}"
NPM=$(uv run --script scripts/release.py generate-matrix --npm --directory src $HASH)
echo "npm_packages $NPM"
echo "npm_packages=$NPM" >> $GITHUB_OUTPUT
update-packages:
needs: [create-metadata]
if: ${{ needs.create-metadata.outputs.npm_packages != '[]' || needs.create-metadata.outputs.pypi_packages != '[]' }}
runs-on: ubuntu-latest
environment: release
permissions:
contents: write
outputs:
changes_made: ${{ steps.commit.outputs.changes_made }}
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Install uv
uses: astral-sh/setup-uv@v5
- name: Update packages
run: |
HASH="${{ needs.create-metadata.outputs.hash }}"
uv run --script scripts/release.py update-packages --directory src/ $HASH
- name: Configure git
run: |
git config --global user.name "GitHub Actions"
git config --global user.email "actions@github.com"
- name: Commit changes
id: commit
run: |
VERSION="${{ needs.create-metadata.outputs.version }}"
git add -u
if git diff-index --quiet HEAD; then
echo "changes_made=false" >> $GITHUB_OUTPUT
else
git commit -m 'Automatic update of packages'
git tag -a "$VERSION" -m "Release $VERSION"
git push origin "$VERSION"
echo "changes_made=true" >> $GITHUB_OUTPUT
fi
publish-pypi:
needs: [update-packages, create-metadata]
if: ${{ needs.create-metadata.outputs.pypi_packages != '[]' && needs.create-metadata.outputs.pypi_packages != '' }}
strategy:
fail-fast: false
matrix:
package: ${{ fromJson(needs.create-metadata.outputs.pypi_packages) }}
name: Build ${{ matrix.package }}
environment: release
permissions:
id-token: write # Required for trusted publishing
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
ref: ${{ needs.create-metadata.outputs.version }}
- name: Install uv
uses: astral-sh/setup-uv@v5
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version-file: "src/${{ matrix.package }}/.python-version"
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: uv sync --frozen --all-extras --dev
- name: Run pyright
working-directory: src/${{ matrix.package }}
run: uv run --frozen pyright
- name: Build package
working-directory: src/${{ matrix.package }}
run: uv build
- name: Publish package to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
packages-dir: src/${{ matrix.package }}/dist
publish-npm:
needs: [update-packages, create-metadata]
if: ${{ needs.create-metadata.outputs.npm_packages != '[]' && needs.create-metadata.outputs.npm_packages != '' }}
strategy:
fail-fast: false
matrix:
package: ${{ fromJson(needs.create-metadata.outputs.npm_packages) }}
name: Build ${{ matrix.package }}
environment: release
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
ref: ${{ needs.create-metadata.outputs.version }}
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
registry-url: 'https://registry.npmjs.org'
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: npm ci
- name: Check if version exists on npm
working-directory: src/${{ matrix.package }}
run: |
VERSION=$(jq -r .version package.json)
if npm view --json | jq -e --arg version "$VERSION" '[.[]][0].versions | contains([$version])'; then
echo "Version $VERSION already exists on npm"
exit 1
fi
echo "Version $VERSION is new, proceeding with publish"
- name: Build package
working-directory: src/${{ matrix.package }}
run: npm run build
- name: Publish package
working-directory: src/${{ matrix.package }}
run: |
npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
create-release:
needs: [update-packages, create-metadata, publish-pypi, publish-npm]
if: |
always() &&
needs.update-packages.outputs.changes_made == 'true' &&
(needs.publish-pypi.result == 'success' || needs.publish-npm.result == 'success')
runs-on: ubuntu-latest
environment: release
permissions:
contents: write
steps:
- uses: actions/checkout@v6
- name: Download release notes
uses: actions/download-artifact@v7
with:
name: release-notes
- name: Create release
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN}}
run: |
VERSION="${{ needs.create-metadata.outputs.version }}"
gh release create "$VERSION" \
--title "Release $VERSION" \
--notes-file RELEASE_NOTES.md
```
## /.github/workflows/typescript.yml
```yml path="/.github/workflows/typescript.yml"
name: TypeScript
on:
push:
branches:
- main
pull_request:
release:
types: [published]
jobs:
detect-packages:
runs-on: ubuntu-latest
outputs:
packages: ${{ steps.find-packages.outputs.packages }}
steps:
- uses: actions/checkout@v6
- name: Find JS packages
id: find-packages
working-directory: src
run: |
PACKAGES=$(find . -name package.json -not -path "*/node_modules/*" -exec dirname {} \; | sed 's/^\.\///' | jq -R -s -c 'split("\n")[:-1]')
echo "packages=$PACKAGES" >> $GITHUB_OUTPUT
test:
needs: [detect-packages]
strategy:
matrix:
package: ${{ fromJson(needs.detect-packages.outputs.packages) }}
name: Test ${{ matrix.package }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: npm ci
- name: Run tests
working-directory: src/${{ matrix.package }}
run: npm test --if-present
build:
needs: [detect-packages, test]
strategy:
matrix:
package: ${{ fromJson(needs.detect-packages.outputs.packages) }}
name: Build ${{ matrix.package }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: npm ci
- name: Build package
working-directory: src/${{ matrix.package }}
run: npm run build
publish:
runs-on: ubuntu-latest
needs: [build, detect-packages]
if: github.event_name == 'release'
environment: release
strategy:
matrix:
package: ${{ fromJson(needs.detect-packages.outputs.packages) }}
name: Publish ${{ matrix.package }}
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
registry-url: "https://registry.npmjs.org"
- name: Install dependencies
working-directory: src/${{ matrix.package }}
run: npm ci
- name: Publish package
working-directory: src/${{ matrix.package }}
run: npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```
## /.gitignore
```gitignore path="/.gitignore"
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
.pnpm-debug.log*
# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
*.lcov
# nyc test coverage
.nyc_output
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Bower dependency directory (https://bower.io/)
bower_components
# node-waf configuration
.lock-wscript
# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules/
jspm_packages/
# Snowpack dependency directory (https://snowpack.dev/)
web_modules/
# TypeScript cache
*.tsbuildinfo
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional stylelint cache
.stylelintcache
# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local
# parcel-bundler cache (https://parceljs.org/)
.cache
.parcel-cache
# Next.js build output
.next
out
# Nuxt.js build / generate output
.nuxt
dist
# Gatsby files
.cache/
# Comment in the public line in if your project uses Gatsby and not Next.js
# https://nextjs.org/blog/next-9-1#public-directory-support
# public
# vuepress build output
.vuepress/dist
# vuepress v2.x temp and cache directory
.temp
.cache
# Docusaurus cache and generated files
.docusaurus
# Serverless directories
.serverless/
# FuseBox cache
.fusebox/
# DynamoDB Local files
.dynamodb/
# TernJS port file
.tern-port
# Stores VSCode versions used for testing VSCode extensions
.vscode-test
# IDEs
.idea/
.vscode/
# yarn v2
.yarn/cache
.yarn/unplugged
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*
build/
gcp-oauth.keys.json
.*-server-credentials.json
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
.DS_Store
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
.claude/settings.local.json
```
## /.mcp.json
```json path="/.mcp.json"
{
"mcpServers": {
"mcp-docs": {
"type": "http",
"url": "https://modelcontextprotocol.io/mcp"
}
}
}
```
## /.npmrc
```npmrc path="/.npmrc"
registry="https://registry.npmjs.org/"
@modelcontextprotocol:registry="https://registry.npmjs.org/"
```
## /CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code when working with code in this repository.
## Project Overview
Official MCP reference server implementations. This is an npm workspaces monorepo containing 7 servers (4 TypeScript, 3 Python) under `src/`. Each server is a standalone package published to npm or PyPI.
## Monorepo Structure
```
src/
everything/ TS @modelcontextprotocol/server-everything (reference server, all MCP features)
filesystem/ TS @modelcontextprotocol/server-filesystem (file operations with Roots access control)
memory/ TS @modelcontextprotocol/server-memory (knowledge graph persistence)
sequentialthinking/ TS @modelcontextprotocol/server-sequential-thinking (step-by-step reasoning)
fetch/ Py mcp-server-fetch (web content fetching)
git/ Py mcp-server-git (git repository operations)
time/ Py mcp-server-time (timezone queries and conversion)
```
## Build & Test Commands
### TypeScript servers
```bash
# Single server
cd src/<server> && npm ci && npm run build && npm test
# All TS servers from root
npm install && npm run build
```
- Build: `tsc` (target ES2022, module Node16, strict mode)
- Tests: **vitest** with `@vitest/coverage-v8` (required for new tests)
- Node version: **22**
### Python servers
```bash
cd src/<server> && uv sync --frozen --all-extras --dev
# Run tests (if tests/ or test/ directory exists)
uv run pytest
# Type checking
uv run pyright
# Linting
uv run ruff check .
```
- Build system: **hatchling** (`uv build`)
- Package manager: **uv** (not pip)
- Python version: **>= 3.10** (per-server `.python-version` file)
- Type checking: **pyright** (enforced in CI)
- Linting: **ruff**
## Code Style
### TypeScript
- ES modules with `.js` extension in import paths
- Strict TypeScript typing for all functions and variables
- Zod schemas for tool input validation
- 2-space indentation, trailing commas in multi-line objects
- camelCase for variables/functions, PascalCase for types/classes, UPPER_CASE for constants
- kebab-case for file names and registered tools/prompts/resources
- Verb-first tool names (e.g., `get-file-info`, not `file-info`)
- Imports grouped: external first, then internal
### Python
- Type hints enforced via pyright
- Async/await patterns (especially in fetch server with pytest-asyncio)
- Follow existing module layout per server
## Contributing Guidelines
**Accepted:** Bug fixes, usability improvements, enhancements demonstrating MCP protocol features (Resources, Prompts, Roots -- not just Tools).
**Selective:** New features outside a server's core purpose or highly opinionated additions.
**Not accepted:** New server implementations (use the [MCP Server Registry](https://github.com/modelcontextprotocol/registry)), README server listing changes.
## CI/CD Pipeline
Both TypeScript and Python workflows use **dynamic package detection** (find + jq matrix strategy):
1. `detect-packages` -- finds all `package.json` / `pyproject.toml` under `src/`
2. `test` -- runs tests per package
3. `build` -- compiles and type-checks per package
4. `publish` -- on release events only (npm for TS, PyPI trusted publishing for Python)
## MCP Protocol Reference
The repo is configured with an MCP docs server (`.mcp.json`) pointing to `https://modelcontextprotocol.io/mcp`. For schema details, reference `https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema` which contains versioned schemas in JSON and TypeScript formats.
## Key Patterns
- Each server registers capabilities via `registerTools(server)`, `registerResources(server)`, `registerPrompts(server)` functions
- Tool annotations: set `readOnlyHint`, `idempotentHint`, `destructiveHint` per MCP spec
- Transport support: stdio (default), SSE (deprecated), Streamable HTTP
- All PRs are reviewed against the [PR template](.github/pull_request_template.md) checklist -- ensure MCP docs are read, security best practices followed, and changes tested with an LLM client
## /CODE_OF_CONDUCT.md
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
mcp-coc@anthropic.com.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
## /CONTRIBUTING.md
# Contributing to MCP Servers
Thanks for your interest in contributing! Here's how you can help make this repo better.
We accept changes through [the standard GitHub flow model](https://docs.github.com/en/get-started/using-github/github-flow).
## Server Listings
The README no longer contains a list of third-party MCP servers — that list has been retired in favor of the [MCP Server Registry](https://github.com/modelcontextprotocol/registry). To make your server discoverable, follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx) to publish it there.
You can browse published servers at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/).
## Server Implementations
We welcome:
- **Bug fixes** — Help us squash those pesky bugs.
- **Usability improvements** — Making servers easier to use for humans and agents.
- **Enhancements that demonstrate MCP protocol features** — We encourage contributions that help reference servers better illustrate underutilized aspects of the MCP protocol beyond just Tools, such as Resources, Prompts, or Roots. For example, adding Roots support to filesystem-server helps showcase this important but lesser-known feature.
We're more selective about:
- **Other new features** — Especially if they're not crucial to the server's core purpose or are highly opinionated. The existing servers are reference servers meant to inspire the community. If you need specific features, we encourage you to build enhanced versions and publish them to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry)! We think a diverse ecosystem of servers is beneficial for everyone.
We don't accept:
- **New server implementations** — We encourage you to publish them to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead.
## Testing
When adding or configuring tests for servers implemented in TypeScript, use **vitest** as the test framework. Vitest provides better ESM support, faster test execution, and a more modern testing experience.
## Documentation
Improvements to existing documentation is welcome - although generally we'd prefer ergonomic improvements than documenting pain points if possible!
We're more selective about adding wholly new documentation, especially in ways that aren't vendor neutral (e.g. how to run a particular server with a particular client).
## Community
[Learn how the MCP community communicates](https://modelcontextprotocol.io/community/communication).
Thank you for helping make MCP servers better for everyone!
## /README.md
# Model Context Protocol servers
This repository is a collection of *reference implementations* for the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), as well as references to community-built servers and additional resources.
> [!IMPORTANT]
> If you are looking for a list of MCP servers, you can browse published servers on [the MCP Registry](https://registry.modelcontextprotocol.io/). The repository served by this README is dedicated to housing just the small number of reference servers maintained by the MCP steering group.
> [!WARNING]
> The servers in this repository are intended as **reference implementations** to demonstrate MCP features and SDK usage. They are meant to serve as educational examples for developers building their own MCP servers, not as production-ready solutions. Developers should evaluate their own security requirements and implement appropriate safeguards based on their specific threat model and use case.
The servers in this repository showcase the versatility and extensibility of MCP, demonstrating how it can be used to give Large Language Models (LLMs) secure, controlled access to tools and data sources.
Typically, each MCP server is implemented with an MCP SDK:
- [C# MCP SDK](https://github.com/modelcontextprotocol/csharp-sdk)
- [Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk)
- [Java MCP SDK](https://github.com/modelcontextprotocol/java-sdk)
- [Kotlin MCP SDK](https://github.com/modelcontextprotocol/kotlin-sdk)
- [PHP MCP SDK](https://github.com/modelcontextprotocol/php-sdk)
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Ruby MCP SDK](https://github.com/modelcontextprotocol/ruby-sdk)
- [Rust MCP SDK](https://github.com/modelcontextprotocol/rust-sdk)
- [Swift MCP SDK](https://github.com/modelcontextprotocol/swift-sdk)
- [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
## 🌟 Reference Servers
These servers aim to demonstrate MCP features and the official SDKs.
- **[Everything](src/everything)** - Reference / test server with prompts, resources, and tools.
- **[Fetch](src/fetch)** - Web content fetching and conversion for efficient LLM usage.
- **[Filesystem](src/filesystem)** - Secure file operations with configurable access controls.
- **[Git](src/git)** - Tools to read, search, and manipulate Git repositories.
- **[Memory](src/memory)** - Knowledge graph-based persistent memory system.
- **[Sequential Thinking](src/sequentialthinking)** - Dynamic and reflective problem-solving through thought sequences.
- **[Time](src/time)** - Time and timezone conversion capabilities.
### Archived
The following reference servers are now archived and can be found at [servers-archived](https://github.com/modelcontextprotocol/servers-archived).
- **[AWS KB Retrieval](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/aws-kb-retrieval-server)** - Retrieval from AWS Knowledge Base using Bedrock Agent Runtime.
- **[Brave Search](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/brave-search)** - Web and local search using Brave's Search API. Has been replaced by the [official server](https://github.com/brave/brave-search-mcp-server).
- **[EverArt](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/everart)** - AI image generation using various models.
- **[GitHub](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/github)** - Repository management, file operations, and GitHub API integration.
- **[GitLab](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/gitlab)** - GitLab API, enabling project management.
- **[Google Drive](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/gdrive)** - File access and search capabilities for Google Drive.
- **[Google Maps](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/google-maps)** - Location services, directions, and place details.
- **[PostgreSQL](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/postgres)** - Read-only database access with schema inspection.
- **[Puppeteer](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/puppeteer)** - Browser automation and web scraping.
- **[Redis](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/redis)** - Interact with Redis key-value stores.
- **[Sentry](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/sentry)** - Retrieving and analyzing issues from Sentry.io.
- **[Slack](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/slack)** - Channel management and messaging capabilities. Now maintained by [Zencoder](https://github.com/zencoderai/slack-mcp-server)
- **[SQLite](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/sqlite)** - Database interaction and business intelligence capabilities.
## 📚 Frameworks
These are high-level frameworks that make it easier to build MCP servers or clients.
### For servers
* **[Anubis MCP](https://github.com/zoedsoupe/anubis-mcp)** (Elixir) - A high-performance and high-level Model Context Protocol (MCP) implementation in Elixir. Think like "Live View" for MCP.
* **[ModelFetch](https://github.com/phuctm97/modelfetch/)** (TypeScript) - Runtime-agnostic SDK to create and deploy MCP servers anywhere TypeScript/JavaScript runs
* **[EasyMCP](https://github.com/zcaceres/easy-mcp/)** (TypeScript)
* **[FastAPI to MCP auto generator](https://github.com/tadata-org/fastapi_mcp)** – A zero-configuration tool for automatically exposing FastAPI endpoints as MCP tools by **[Tadata](https://tadata.com/)**
* **[FastMCP](https://github.com/punkpeye/fastmcp)** (TypeScript)
* **[Foobara MCP Connector](https://github.com/foobara/mcp-connector)** - Easily expose Foobara commands written in Ruby as tools via MCP
* **[Foxy Contexts](https://github.com/strowk/foxy-contexts)** – A library to build MCP servers in Golang by **[strowk](https://github.com/strowk)**
* **[Higress MCP Server Hosting](https://github.com/alibaba/higress/tree/main/plugins/wasm-go/mcp-servers)** - A solution for hosting MCP Servers by extending the API Gateway (based on Envoy) with wasm plugins.
* **[MCP Declarative Java SDK](https://github.com/codeboyzhou/mcp-declarative-java-sdk)** Annotation-driven MCP servers development with Java, no Spring Framework Required, minimize dependencies as much as possible.
* **[MCP-Framework](https://mcp-framework.com)** Build MCP servers with elegance and speed in TypeScript. Comes with a CLI to create your project with `mcp create app`. Get started with your first server in under 5 minutes by **[Alex Andru](https://github.com/QuantGeekDev)**
* **[MCP Plexus](https://github.com/Super-I-Tech/mcp_plexus)**: A secure, **multi-tenant** and Multi-user MCP python server framework built to integrate easily with external services via OAuth 2.1, offering scalable and robust solutions for managing complex AI applications.
* **[mcp_sse (Elixir)](https://github.com/kEND/mcp_sse)** An SSE implementation in Elixir for rapidly creating MCP servers.
* **[mxcp](https://github.com/raw-labs/mxcp)** (Python) - Open-source framework for building enterprise-grade MCP servers using just YAML, SQL, and Python, with built-in auth, monitoring, ETL and policy enforcement.
* **[Next.js MCP Server Template](https://github.com/vercel-labs/mcp-for-next.js)** (Typescript) - A starter Next.js project that uses the MCP Adapter to allow MCP clients to connect and access resources.
* **[PayMCP](https://github.com/blustAI/paymcp)** (Python & TypeScript) - Lightweight payments layer for MCP servers: turn tools into paid endpoints with a two-line decorator. [PyPI](https://pypi.org/project/paymcp/) · [npm](https://www.npmjs.com/package/paymcp) · [TS repo](https://github.com/blustAI/paymcp-ts)
* **[Perl SDK](https://github.com/mojolicious/mojo-mcp)** - An SDK for building MCP servers and clients with the Perl programming language.
* **[Quarkus MCP Server SDK](https://github.com/quarkiverse/quarkus-mcp-server)** (Java)
- **[R mcptools](https://github.com/posit-dev/mcptools)** - An R SDK for creating R-based MCP servers and retrieving functionality from third-party MCP servers as R functions.
* **[SAP ABAP MCP Server SDK](https://github.com/abap-ai/mcp)** - Build SAP ABAP based MCP servers. ABAP 7.52 based with 7.02 downport; runs on R/3 & S/4HANA on-premises, currently not cloud-ready.
* **[Spring AI MCP Server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html)** - Provides auto-configuration for setting up an MCP server in Spring Boot applications.
* **[Template MCP Server](https://github.com/mcpdotdirect/template-mcp-server)** - A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure
* **[AgentR Universal MCP SDK](https://github.com/universal-mcp/universal-mcp)** - A python SDK to build MCP Servers with inbuilt credential management by **[Agentr](https://agentr.dev/home)**
* **[Vercel MCP Adapter](https://github.com/vercel/mcp-adapter)** (TypeScript) - A simple package to start serving an MCP server on most major JS meta-frameworks including Next, Nuxt, Svelte, and more.
* **[PHP MCP Server](https://github.com/php-mcp/server)** (PHP) - Core PHP implementation for the Model Context Protocol (MCP) server
### For clients
* **[codemirror-mcp](https://github.com/marimo-team/codemirror-mcp)** - CodeMirror extension that implements the Model Context Protocol (MCP) for resource mentions and prompt commands
* **[llm-analysis-assistant](https://github.com/xuzexin-hz/llm-analysis-assistant)** <img height="12" width="12" src="https://raw.githubusercontent.com/xuzexin-hz/llm-analysis-assistant/refs/heads/main/src/llm_analysis_assistant/pages/html/imgs/favicon.ico" alt="Langfuse Logo" /> - A very streamlined mcp client that supports calling and monitoring stdio/sse/streamableHttp, and can also view request responses through the /logs page. It also supports monitoring and simulation of ollama/openai interface.
* **[MCP-Agent](https://github.com/lastmile-ai/mcp-agent)** - A simple, composable framework to build agents using Model Context Protocol by **[LastMile AI](https://www.lastmileai.dev)**
* **[Spring AI MCP Client](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html)** - Provides auto-configuration for MCP client functionality in Spring Boot applications.
* **[MCP CLI Client](https://github.com/vincent-pli/mcp-cli-host)** - A CLI host application that enables Large Language Models (LLMs) to interact with external tools through the Model Context Protocol (MCP).
* **[OpenMCP Client](https://github.com/LSTM-Kirigaya/openmcp-client/)** - An all-in-one vscode/trae/cursor plugin for MCP server debugging. [Document](https://kirigaya.cn/openmcp/) & [OpenMCP SDK](https://kirigaya.cn/openmcp/sdk-tutorial/).
* **[PHP MCP Client](https://github.com/php-mcp/client)** - Core PHP implementation for the Model Context Protocol (MCP) Client
* **[Runbear](https://runbear.io/solutions/integrations/slack/mcp)** - No-code MCP client for team chat platforms, such as Slack, Microsoft Teams, and Discord.
## 📚 Resources
Additional resources on MCP.
- **[A2A-MCP Java Bridge](https://github.com/vishalmysore/a2ajava)** - A2AJava brings powerful A2A-MCP integration directly into your Java applications. It enables developers to annotate standard Java methods and instantly expose them as MCP Server, A2A-discoverable actions — with no boilerplate or service registration overhead.
- **[AiMCP](https://www.aimcp.info)** - A collection of MCP clients&servers to find the right mcp tools by **[Hekmon](https://github.com/hekmon8)**
- **[Awesome Crypto MCP Servers by badkk](https://github.com/badkk/awesome-crypto-mcp-servers)** - A curated list of MCP servers by **[Luke Fan](https://github.com/badkk)**
- **[Awesome MCP Servers by appcypher](https://github.com/appcypher/awesome-mcp-servers)** - A curated list of MCP servers by **[Stephen Akinyemi](https://github.com/appcypher)**
- **[Awesome MCP Servers by punkpeye](https://github.com/punkpeye/awesome-mcp-servers)** (**[website](https://glama.ai/mcp/servers)**) - A curated list of MCP servers by **[Frank Fiegel](https://github.com/punkpeye)**
- **[Awesome MCP Servers by wong2](https://github.com/wong2/awesome-mcp-servers)** (**[website](https://mcpservers.org)**) - A curated list of MCP servers by **[wong2](https://github.com/wong2)**
- **[Awesome Remote MCP Servers by JAW9C](https://github.com/jaw9c/awesome-remote-mcp-servers)** - A curated list of **remote** MCP servers, including their authentication support by **[JAW9C](https://github.com/jaw9c)**
- **[Discord Server](https://glama.ai/mcp/discord)** – A community discord server dedicated to MCP by **[Frank Fiegel](https://github.com/punkpeye)**
- **[Install This MCP](https://installthismcp.com)** - Reduce Installation Friction with beautiful installation guides
- <img height="12" width="12" src="https://raw.githubusercontent.com/klavis-ai/klavis/main/static/klavis-ai.png" alt="Klavis Logo" /> **[Klavis AI](https://www.klavis.ai)** - Open Source MCP Infra. Hosted MCP servers and MCP clients on Slack and Discord.
- **[MCP Badges](https://github.com/mcpx-dev/mcp-badges)** – Quickly highlight your MCP project with clear, eye-catching badges, by **[Ironben](https://github.com/nanbingxyz)**
- <img height="12" width="12" src="https://mcpproxy.app/favicon.svg" alt="MCPProxy Logo" /> **[MCPProxy](https://github.com/smart-mcp-proxy/mcpproxy-go)** - Open-source local app that enables access to multiple MCP servers and thousands of tools with intelligent discovery via MCP protocol, runs servers in isolated environments, and features automatic quarantine protection against malicious tools.
- **[MCPRepository.com](https://mcprepository.com/)** - A repository that indexes and organizes all MCP servers for easy discovery.
- **[mcp-cli](https://github.com/wong2/mcp-cli)** - A CLI inspector for the Model Context Protocol by **[wong2](https://github.com/wong2)**
- **[mcp-dockmaster](https://mcp-dockmaster.com)** - An Open-Sourced UI to install and manage MCP servers for Windows, Linux and macOS.
- **[mcp-get](https://mcp-get.com)** - Command line tool for installing and managing MCP servers by **[Michael Latman](https://github.com/michaellatman)**
- **[mcp-guardian](https://github.com/eqtylab/mcp-guardian)** - GUI application + tools for proxying / managing control of MCP servers by **[EQTY Lab](https://eqtylab.io)**
- **[MCP Linker](https://github.com/milisp/mcp-linker)** - A cross-platform Tauri GUI tool for one-click setup and management of MCP servers, supporting Claude Desktop, Cursor, Windsurf, VS Code, Cline, and Neovim.
- **[mcp-manager](https://github.com/zueai/mcp-manager)** - Simple Web UI to install and manage MCP servers for Claude Desktop by **[Zue](https://github.com/zueai)**
- **[MCP Marketplace Web Plugin](https://github.com/AI-Agent-Hub/mcp-marketplace)** MCP Marketplace is a small Web UX plugin to integrate with AI applications, Support various MCP Server API Endpoint (e.g pulsemcp.com/deepnlp.org and more). Allowing user to browse, paginate and select various MCP servers by different categories. [Pypi](https://pypi.org/project/mcp-marketplace) | [Maintainer](https://github.com/AI-Agent-Hub) | [Website](http://www.deepnlp.org/store/ai-agent/mcp-server)
- **[mcp.natoma.ai](https://mcp.natoma.ai)** – A Hosted MCP Platform to discover, install, manage and deploy MCP servers by **[Natoma Labs](https://www.natoma.ai)**
- **[mcp.run](https://mcp.run)** - A hosted registry and control plane to install & run secure + portable MCP Servers.
- **[MCPHub](https://www.mcphub.com)** - Website to list high quality MCP servers and reviews by real users. Also provide online chatbot for popular LLM models with MCP server support.
- **[MCP Router](https://mcp-router.net)** – Free Windows and macOS app that simplifies MCP management while providing seamless app authentication and powerful log visualization by **[MCP Router](https://github.com/mcp-router/mcp-router)**
- **[MCP Servers Hub](https://github.com/apappascs/mcp-servers-hub)** (**[website](https://mcp-servers-hub-website.pages.dev/)**) - A curated list of MCP servers by **[apappascs](https://github.com/apappascs)**
- **[MCPServers.com](https://mcpservers.com)** - A growing directory of high-quality MCP servers with clear setup guides for a variety of MCP clients. Built by the team behind the **[Highlight MCP client](https://highlightai.com/)**
- **[MCP Servers Rating and User Reviews](http://www.deepnlp.org/store/ai-agent/mcp-server)** - Website to rate MCP servers, write authentic user reviews, and [search engine for agent & mcp](http://www.deepnlp.org/search/agent)
- **[MCP Sky](https://bsky.app/profile/brianell.in/feed/mcp)** - Bluesky feed for MCP related news and discussion by **[@brianell.in](https://bsky.app/profile/brianell.in)**
- **[MCP X Community](https://x.com/i/communities/1861891349609603310)** – A X community for MCP by **[Xiaoyi](https://x.com/chxy)**
- **[MCPHub](https://github.com/Jeamee/MCPHub-Desktop)** – An Open Source macOS & Windows GUI Desktop app for discovering, installing and managing MCP servers by **[Jeamee](https://github.com/jeamee)**
- **[mcpm](https://github.com/pathintegral-institute/mcpm.sh)** ([website](https://mcpm.sh)) - MCP Manager (MCPM) is a Homebrew-like service for managing Model Context Protocol (MCP) servers across clients by **[Pathintegral](https://github.com/pathintegral-institute)**
- **[MCPVerse](https://mcpverse.dev)** - A portal for creating & hosting authenticated MCP servers and connecting to them securely.
- **[MCP Servers Search](https://github.com/atonomus/mcp-servers-search)** - An MCP server that provides tools for querying and discovering available MCP servers from this list.
- **[Search MCP Server](https://github.com/krzysztofkucmierz/search-mcp-server)** - Recommends the most relevant MCP servers based on the client's query by searching this README file.
- **[MCPWatch](https://github.com/kapilduraphe/mcp-watch)** - A comprehensive security scanner for Model Context Protocol (MCP) servers that detects vulnerabilities and security issues in your MCP server implementations.
- <img height="12" width="12" src="https://mkinf.io/favicon-lilac.png" alt="mkinf Logo" /> **[mkinf](https://mkinf.io)** - An Open Source registry of hosted MCP Servers to accelerate AI agent workflows.
- **[Open-Sourced MCP Servers Directory](https://github.com/chatmcp/mcp-directory)** - A curated list of MCP servers by **[mcpso](https://mcp.so)**
- <img height="12" width="12" src="https://opentools.com/favicon.ico" alt="OpenTools Logo" /> **[OpenTools](https://opentools.com)** - An open registry for finding, installing, and building with MCP servers by **[opentoolsteam](https://github.com/opentoolsteam)**
- **[Programmatic MCP Prototype](https://github.com/domdomegg/programmatic-mcp-prototype)** - Experimental agent prototype demonstrating programmatic MCP tool composition, progressive tool discovery, state persistence, and skill building through TypeScript code execution by **[Adam Jones](https://github.com/domdomegg)**
- **[PulseMCP](https://www.pulsemcp.com)** ([API](https://www.pulsemcp.com/api)) - Community hub & weekly newsletter for discovering MCP servers, clients, articles, and news by **[Tadas Antanavicius](https://github.com/tadasant)**, **[Mike Coughlin](https://github.com/macoughl)**, and **[Ravina Patel](https://github.com/ravinahp)**
- **[r/mcp](https://www.reddit.com/r/mcp)** – A Reddit community dedicated to MCP by **[Frank Fiegel](https://github.com/punkpeye)**
- **[MCP.ing](https://mcp.ing/)** - A list of MCP services for discovering MCP servers in the community and providing a convenient search function for MCP services by **[iiiusky](https://github.com/iiiusky)**
- **[MCP Hunt](https://mcp-hunt.com)** - Realtime platform for discovering trending MCP servers with momentum tracking, upvoting, and community discussions - like Product Hunt meets Reddit for MCP
- **[Smithery](https://smithery.ai/)** - A registry of MCP servers to find the right tools for your LLM agents by **[Henry Mao](https://github.com/calclavia)**
- **[Toolbase](https://gettoolbase.ai)** - Desktop application that manages tools and MCP servers with just a few clicks - no coding required by **[gching](https://github.com/gching)**
- **[ToolHive](https://github.com/StacklokLabs/toolhive)** - A lightweight utility designed to simplify the deployment and management of MCP servers, ensuring ease of use, consistency, and security through containerization by **[StacklokLabs](https://github.com/StacklokLabs)**
- **[NetMind](https://www.netmind.ai/AIServices)** - Access powerful AI services via simple APIs or MCP servers to supercharge your productivity.
- **[Webrix MCP Gateway](https://github.com/webrix-ai/secure-mcp-gateway)** - Enterprise MCP gateway with SSO, RBAC, audit trails, and token vaults for secure, centralized AI agent access control. Deploy via Helm charts on-premise or in your cloud. [webrix.ai](https://webrix.ai)
## 🚀 Getting Started
### Using MCP Servers in this Repository
TypeScript-based servers in this repository can be used directly with `npx`.
For example, this will start the [Memory](src/memory) server:
```sh
npx -y @modelcontextprotocol/server-memory
```
Python-based servers in this repository can be used directly with [`uvx`](https://docs.astral.sh/uv/concepts/tools/) or [`pip`](https://pypi.org/project/pip/). `uvx` is recommended for ease of use and setup.
For example, this will start the [Git](src/git) server:
```sh
# With uvx
uvx mcp-server-git
# With pip
pip install mcp-server-git
python -m mcp_server_git
```
Follow [these](https://docs.astral.sh/uv/getting-started/installation/) instructions to install `uv` / `uvx` and [these](https://pip.pypa.io/en/stable/installation/) to install `pip`.
### Using an MCP Client
However, running a server on its own isn't very useful, and should instead be configured into an MCP client. For example, here's the Claude Desktop configuration to use the above server:
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}
```
On Windows, wrap `npx` with `cmd /c`:
```json
{
"mcpServers": {
"memory": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]
}
}
}
```
Additional examples of using the Claude Desktop as an MCP client might look like:
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
},
"git": {
"command": "uvx",
"args": ["mcp-server-git", "--repository", "path/to/git/repo"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
}
}
}
```
On Windows, apply the same wrapper to each `npx`-based entry above by changing `"command"` to `"cmd"` and prepending `"/c", "npx"` to the existing `args`. Leave `uvx` entries unchanged.
## 🛠️ Creating Your Own Server
Interested in creating your own MCP server? Visit the official documentation at [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) for comprehensive guides, best practices, and technical details on implementing MCP servers.
## 🤝 Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for information about contributing to this repository.
## 🔒 Security
See [SECURITY.md](SECURITY.md) for reporting security vulnerabilities.
## 📜 License
This project is licensed under the Apache License, Version 2.0 for new contributions, with existing code under MIT - see the [LICENSE](LICENSE) file for details.
## 💬 Community
- [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions)
## ⭐ Support
If you find MCP servers useful, please consider starring the repository and contributing new servers or improvements!
---
Managed by Anthropic, but built together with the community. The Model Context Protocol is open source and we encourage everyone to contribute their own servers and improvements!
## /SECURITY.md
# Security Policy
Thank you for helping keep the Model Context Protocol and its ecosystem secure.
## Important Notice
The servers in this repository are **reference implementations** intended to demonstrate
MCP features and SDK usage. They serve as educational examples for developers building
their own MCP servers, not as production-ready solutions.
This repository is **not** eligible for security vulnerability reporting. If you discover
a vulnerability in an MCP SDK, please report it in the appropriate SDK repository.
## Reporting Security Issues in MCP SDKs
If you discover a security vulnerability in an MCP SDK, please report it through the
[GitHub Security Advisory process](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
in the relevant SDK repository.
Please **do not** report security vulnerabilities through public GitHub issues, discussions,
or pull requests.
## /package.json
```json path="/package.json"
{
"name": "@modelcontextprotocol/servers",
"private": true,
"version": "0.6.2",
"description": "Model Context Protocol servers",
"license": "SEE LICENSE IN LICENSE",
"author": "Model Context Protocol a Series of LF Projects, LLC.",
"homepage": "https://modelcontextprotocol.io",
"bugs": "https://github.com/modelcontextprotocol/servers/issues",
"type": "module",
"workspaces": [
"src/*"
],
"files": [],
"scripts": {
"build": "npm run build --workspaces",
"watch": "npm run watch --workspaces",
"publish-all": "npm publish --workspaces --access public",
"link-all": "npm link --workspaces"
},
"dependencies": {
"@modelcontextprotocol/server-everything": "*",
"@modelcontextprotocol/server-memory": "*",
"@modelcontextprotocol/server-filesystem": "*",
"@modelcontextprotocol/server-sequential-thinking": "*"
}
}
```
## /scripts/release.py
```py path="/scripts/release.py"
#!/usr/bin/env uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "click>=8.1.8",
# "tomlkit>=0.13.2"
# ]
# ///
import sys
import re
import click
from pathlib import Path
import json
import tomlkit
import datetime
import subprocess
from dataclasses import dataclass
from typing import Any, Iterator, NewType, Protocol
Version = NewType("Version", str)
GitHash = NewType("GitHash", str)
class GitHashParamType(click.ParamType):
name = "git_hash"
def convert(
self, value: Any, param: click.Parameter | None, ctx: click.Context | None
) -> GitHash | None:
if value is None:
return None
if not (8 <= len(value) <= 40):
self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
if not re.match(r"^[0-9a-fA-F]+{{contextString}}quot;, value):
self.fail("Git hash must contain only hex digits (0-9, a-f)")
try:
# Verify hash exists in repo
subprocess.run(
["git", "rev-parse", "--verify", value], check=True, capture_output=True
)
except subprocess.CalledProcessError:
self.fail(f"Git hash {value} not found in repository")
return GitHash(value.lower())
GIT_HASH = GitHashParamType()
class Package(Protocol):
path: Path
def package_name(self) -> str: ...
def update_version(self, version: Version) -> None: ...
@dataclass
class NpmPackage:
path: Path
def package_name(self) -> str:
with open(self.path / "package.json", "r") as f:
return json.load(f)["name"]
def update_version(self, version: Version):
with open(self.path / "package.json", "r+") as f:
data = json.load(f)
data["version"] = version
f.seek(0)
json.dump(data, f, indent=2)
f.truncate()
@dataclass
class PyPiPackage:
path: Path
def package_name(self) -> str:
with open(self.path / "pyproject.toml") as f:
toml_data = tomlkit.parse(f.read())
name = toml_data.get("project", {}).get("name")
if not name:
raise Exception("No name in pyproject.toml project section")
return str(name)
def update_version(self, version: Version):
# Update version in pyproject.toml
with open(self.path / "pyproject.toml") as f:
data = tomlkit.parse(f.read())
data["project"]["version"] = version
with open(self.path / "pyproject.toml", "w") as f:
f.write(tomlkit.dumps(data))
# Regenerate uv.lock to match the updated pyproject.toml
subprocess.run(["uv", "lock"], cwd=self.path, check=True)
def has_changes(path: Path, git_hash: GitHash) -> bool:
"""Check if any files changed between current state and git hash"""
try:
output = subprocess.run(
["git", "diff", "--name-only", git_hash, "--", "."],
cwd=path,
check=True,
capture_output=True,
text=True,
)
changed_files = [Path(f) for f in output.stdout.splitlines()]
relevant_files = [f for f in changed_files if f.suffix in [".py", ".ts"]]
return len(relevant_files) >= 1
except subprocess.CalledProcessError:
return False
def gen_version() -> Version:
"""Generate version based on current date"""
now = datetime.datetime.now()
return Version(f"{now.year}.{now.month}.{now.day}")
def find_changed_packages(directory: Path, git_hash: GitHash) -> Iterator[Package]:
for path in directory.glob("*/package.json"):
if has_changes(path.parent, git_hash):
yield NpmPackage(path.parent)
for path in directory.glob("*/pyproject.toml"):
if has_changes(path.parent, git_hash):
yield PyPiPackage(path.parent)
@click.group()
def cli():
pass
@cli.command("update-packages")
@click.option(
"--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
)
@click.argument("git_hash", type=GIT_HASH)
def update_packages(directory: Path, git_hash: GitHash) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
for package in find_changed_packages(path, git_hash):
name = package.package_name()
package.update_version(version)
click.echo(f"{name}@{version}")
return 0
@cli.command("generate-notes")
@click.option(
"--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
)
@click.argument("git_hash", type=GIT_HASH)
def generate_notes(directory: Path, git_hash: GitHash) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
click.echo(f"# Release : v{version}")
click.echo("")
click.echo("## Updated packages")
for package in find_changed_packages(path, git_hash):
name = package.package_name()
click.echo(f"- {name}@{version}")
return 0
@cli.command("generate-version")
def generate_version() -> int:
# Detect package type
click.echo(gen_version())
return 0
@cli.command("generate-matrix")
@click.option(
"--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
)
@click.option("--npm", is_flag=True, default=False)
@click.option("--pypi", is_flag=True, default=False)
@click.argument("git_hash", type=GIT_HASH)
def generate_matrix(directory: Path, git_hash: GitHash, pypi: bool, npm: bool) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
changes = []
for package in find_changed_packages(path, git_hash):
pkg = package.path.relative_to(path)
if npm and isinstance(package, NpmPackage):
changes.append(str(pkg))
if pypi and isinstance(package, PyPiPackage):
changes.append(str(pkg))
click.echo(json.dumps(changes))
return 0
if __name__ == "__main__":
sys.exit(cli())
```
## /src/everything/.prettierignore
```prettierignore path="/src/everything/.prettierignore"
packages
dist
README.md
node_modules
```
## /src/everything/AGENTS.md
# MCP "Everything" Server - Development Guidelines
## Build, Test & Run Commands
- Build: `npm run build` - Compiles TypeScript to JavaScript
- Watch mode: `npm run watch` - Watches for changes and rebuilds automatically
- Run STDIO server: `npm run start:stdio` - Starts the MCP server using stdio transport
- Run SSE server: `npm run start:sse` - Starts the MCP server with SSE transport
- Run StreamableHttp server: `npm run start:streamableHttp` - Starts the MCP server with StreamableHttp transport
- Prepare release: `npm run prepare` - Builds the project for publishing
## Code Style Guidelines
- Use ES modules with `.js` extension in import paths
- Strictly type all functions and variables with TypeScript
- Follow zod schema patterns for tool input validation
- Prefer async/await over callbacks and Promise chains
- Place all imports at top of file, grouped by external then internal
- Use descriptive variable names that clearly indicate purpose
- Implement proper cleanup for timers and resources in server shutdown
- Handle errors with try/catch blocks and provide clear error messages
- Use consistent indentation (2 spaces) and trailing commas in multi-line objects
- Match existing code style, import order, and module layout in the respective folder.
- Use camelCase for variables/functions,
- Use PascalCase for types/classes,
- Use UPPER_CASE for constants
- Use kebab-case for file names and registered tools, prompts, and resources.
- Use verbs for tool names, e.g., `get-annotated-message` instead of `annotated-message`
## Extending the Server
The Everything Server is designed to be extended at well-defined points.
See [Extension Points](docs/extension.md) and [Project Structure](docs/structure.md).
The server factory is `src/everything/server/index.ts` and registers all features during startup as well as handling post-connection setup.
### High-level
- Tools live under `src/everything/tools/` and are registered via `registerTools(server)`.
- Resources live under `src/everything/resources/` and are registered via `registerResources(server)`.
- Prompts live under `src/everything/prompts/` and are registered via `registerPrompts(server)`.
- Subscriptions and simulated update routines are under `src/everything/resources/subscriptions.ts`.
- Logging helpers are under `src/everything/server/logging.ts`.
- Transport managers are under `src/everything/transports/`.
### When adding a new feature
- Follow the existing file/module pattern in its folder (naming, exports, and registration function).
- Export a `registerX(server)` function that registers new items with the MCP SDK in the same style as existing ones.
- Wire your new module into the central index (e.g., update `tools/index.ts`, `resources/index.ts`, or `prompts/index.ts`).
- Ensure schemas (for tools) are accurate JSON Schema and include helpful descriptions and examples.
`server/index.ts` and usages in `logging.ts` and `subscriptions.ts`.
- Keep the docs in `src/everything/docs/` up to date if you add or modify noteworthy features.
## /src/everything/Dockerfile
``` path="/src/everything/Dockerfile"
FROM node:22.12-alpine AS builder
COPY src/everything /app
COPY tsconfig.json /tsconfig.json
WORKDIR /app
RUN --mount=type=cache,target=/root/.npm npm install
FROM node:22-alpine AS release
WORKDIR /app
COPY --from=builder /app/dist /app/dist
COPY --from=builder /app/package.json /app/package.json
COPY --from=builder /app/package-lock.json /app/package-lock.json
ENV NODE_ENV=production
RUN npm ci --ignore-scripts --omit-dev
CMD ["node", "dist/index.js"]
```
## /src/everything/README.md
# Everything MCP Server
**[Architecture](docs/architecture.md)
| [Project Structure](docs/structure.md)
| [Startup Process](docs/startup.md)
| [Server Features](docs/features.md)
| [Extension Points](docs/extension.md)
| [How It Works](docs/how-it-works.md)**
This MCP server attempts to exercise all the features of the MCP protocol. It is not intended to be a useful server, but rather a test server for builders of MCP clients. It implements prompts, tools, resources, sampling, and more to showcase MCP capabilities.
## Tools, Resources, Prompts, and Other Features
A complete list of the registered MCP primitives and other protocol features demonstrated can be found in the [Server Features](docs/features.md) document.
## Usage with Claude Desktop (uses [stdio Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio))
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"everything": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-everything"
]
}
}
}
```
On Windows, use `cmd /c` to launch `npx`:
```json
{
"mcpServers": {
"everything": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-everything"
]
}
}
}
```
## Usage with VS Code
For quick installation, use one of the one-click install buttons below...
[](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D&quality=insiders)
[](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Feverything%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Feverything%22%5D%7D&quality=insiders)
For manual installation, you can configure the MCP server using one of these methods:
**Method 1: User Configuration (Recommended)**
Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
**Method 2: Workspace Configuration**
Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
> For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
#### NPX
```json
{
"servers": {
"everything": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-everything"]
}
}
}
```
On Windows, use:
```json
{
"servers": {
"everything": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-everything"]
}
}
}
```
## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
```shell
cd src/everything
npm install
npm run start:sse
```
## Run from source with [Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)
```shell
cd src/everything
npm install
npm run start:streamableHttp
```
## Running as an installed package
### Install
```shell
npm install -g @modelcontextprotocol/server-everything@latest
````
### Run the default (stdio) server
```shell
npx @modelcontextprotocol/server-everything
```
### Or specify stdio explicitly
```shell
npx @modelcontextprotocol/server-everything stdio
```
### Run the SSE server
```shell
npx @modelcontextprotocol/server-everything sse
```
### Run the streamable HTTP server
```shell
npx @modelcontextprotocol/server-everything streamableHttp
```
## /src/everything/__tests__/prompts.test.ts
```ts path="/src/everything/__tests__/prompts.test.ts"
import { describe, it, expect, vi } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerSimplePrompt } from '../prompts/simple.js';
import { registerArgumentsPrompt } from '../prompts/args.js';
import { registerPromptWithCompletions } from '../prompts/completions.js';
import { registerEmbeddedResourcePrompt } from '../prompts/resource.js';
// Helper to capture registered prompt handlers
function createMockServer() {
const handlers: Map<string, Function> = new Map();
const configs: Map<string, any> = new Map();
const mockServer = {
registerPrompt: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
configs.set(name, config);
}),
} as unknown as McpServer;
return { mockServer, handlers, configs };
}
describe('Prompts', () => {
describe('simple-prompt', () => {
it('should return fixed message with no arguments', () => {
const { mockServer, handlers } = createMockServer();
registerSimplePrompt(mockServer);
const handler = handlers.get('simple-prompt')!;
const result = handler();
expect(result).toEqual({
messages: [
{
role: 'user',
content: {
type: 'text',
text: 'This is a simple prompt without arguments.',
},
},
],
});
});
});
describe('args-prompt', () => {
it('should include city in message', () => {
const { mockServer, handlers } = createMockServer();
registerArgumentsPrompt(mockServer);
const handler = handlers.get('args-prompt')!;
const result = handler({ city: 'San Francisco' });
expect(result.messages[0].content.text).toBe("What's weather in San Francisco?");
});
it('should include city and state in message', () => {
const { mockServer, handlers } = createMockServer();
registerArgumentsPrompt(mockServer);
const handler = handlers.get('args-prompt')!;
const result = handler({ city: 'San Francisco', state: 'California' });
expect(result.messages[0].content.text).toBe(
"What's weather in San Francisco, California?"
);
});
it('should handle city only (optional state omitted)', () => {
const { mockServer, handlers } = createMockServer();
registerArgumentsPrompt(mockServer);
const handler = handlers.get('args-prompt')!;
const result = handler({ city: 'New York' });
expect(result.messages[0].content.text).toBe("What's weather in New York?");
expect(result.messages[0].content.text).not.toContain(',');
expect(result.messages[0].role).toBe('user');
expect(result.messages[0].content.type).toBe('text');
});
});
describe('completable-prompt', () => {
it('should generate promotion message with department and name', () => {
const { mockServer, handlers } = createMockServer();
registerPromptWithCompletions(mockServer);
const handler = handlers.get('completable-prompt')!;
const result = handler({ department: 'Engineering', name: 'Alice' });
expect(result.messages[0].content.text).toBe(
'Please promote Alice to the head of the Engineering team.'
);
});
it('should work with different departments', () => {
const { mockServer, handlers } = createMockServer();
registerPromptWithCompletions(mockServer);
const handler = handlers.get('completable-prompt')!;
const salesResult = handler({ department: 'Sales', name: 'David' });
expect(salesResult.messages[0].content.text).toContain('Sales');
expect(salesResult.messages[0].content.text).toContain('David');
expect(salesResult.messages[0].role).toBe('user');
const marketingResult = handler({ department: 'Marketing', name: 'Grace' });
expect(marketingResult.messages[0].content.text).toContain('Marketing');
expect(marketingResult.messages[0].content.text).toContain('Grace');
});
});
describe('resource-prompt', () => {
it('should return text resource reference', () => {
const { mockServer, handlers } = createMockServer();
registerEmbeddedResourcePrompt(mockServer);
const handler = handlers.get('resource-prompt')!;
const result = handler({ resourceType: 'Text', resourceId: '1' });
expect(result.messages).toHaveLength(2);
expect(result.messages[0].content.text).toContain('Text');
expect(result.messages[0].content.text).toContain('1');
expect(result.messages[1].content.type).toBe('resource');
expect(result.messages[1].content.resource.uri).toContain('text/1');
});
it('should return blob resource reference', () => {
const { mockServer, handlers } = createMockServer();
registerEmbeddedResourcePrompt(mockServer);
const handler = handlers.get('resource-prompt')!;
const result = handler({ resourceType: 'Blob', resourceId: '5' });
expect(result.messages[0].content.text).toContain('Blob');
expect(result.messages[1].content.resource.uri).toContain('blob/5');
});
it('should reject invalid resource type', () => {
const { mockServer, handlers } = createMockServer();
registerEmbeddedResourcePrompt(mockServer);
const handler = handlers.get('resource-prompt')!;
expect(() => handler({ resourceType: 'Invalid', resourceId: '1' })).toThrow(
'Invalid resourceType'
);
});
it('should reject invalid resource ID', () => {
const { mockServer, handlers } = createMockServer();
registerEmbeddedResourcePrompt(mockServer);
const handler = handlers.get('resource-prompt')!;
expect(() => handler({ resourceType: 'Text', resourceId: '-1' })).toThrow(
'Invalid resourceId'
);
expect(() => handler({ resourceType: 'Text', resourceId: '0' })).toThrow(
'Invalid resourceId'
);
expect(() => handler({ resourceType: 'Text', resourceId: 'abc' })).toThrow(
'Invalid resourceId'
);
});
it('should include both intro text and resource messages', () => {
const { mockServer, handlers } = createMockServer();
registerEmbeddedResourcePrompt(mockServer);
const handler = handlers.get('resource-prompt')!;
const result = handler({ resourceType: 'Text', resourceId: '3' });
expect(result.messages).toHaveLength(2);
expect(result.messages[0].role).toBe('user');
expect(result.messages[0].content.type).toBe('text');
expect(result.messages[1].role).toBe('user');
expect(result.messages[1].content.type).toBe('resource');
});
});
});
```
## /src/everything/__tests__/registrations.test.ts
```ts path="/src/everything/__tests__/registrations.test.ts"
import { describe, it, expect, vi } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
// Create mock server
function createMockServer() {
return {
registerTool: vi.fn(),
registerPrompt: vi.fn(),
registerResource: vi.fn(),
server: {
getClientCapabilities: vi.fn(() => ({})),
setRequestHandler: vi.fn(),
},
sendLoggingMessage: vi.fn(),
sendResourceUpdated: vi.fn(),
} as unknown as McpServer;
}
describe('Registration Index Files', () => {
describe('tools/index.ts', () => {
it('should register all standard tools', async () => {
const { registerTools } = await import('../tools/index.js');
const mockServer = createMockServer();
registerTools(mockServer);
// Should register 12 standard tools (non-conditional)
expect(mockServer.registerTool).toHaveBeenCalledTimes(12);
// Verify specific tools are registered
const registeredTools = (mockServer.registerTool as any).mock.calls.map(
(call: any[]) => call[0]
);
expect(registeredTools).toContain('echo');
expect(registeredTools).toContain('get-sum');
expect(registeredTools).toContain('get-env');
expect(registeredTools).toContain('get-tiny-image');
expect(registeredTools).toContain('get-structured-content');
expect(registeredTools).toContain('get-annotated-message');
expect(registeredTools).toContain('trigger-long-running-operation');
expect(registeredTools).toContain('get-resource-links');
expect(registeredTools).toContain('get-resource-reference');
expect(registeredTools).toContain('gzip-file-as-resource');
expect(registeredTools).toContain('toggle-simulated-logging');
expect(registeredTools).toContain('toggle-subscriber-updates');
});
it('should register conditional tools based on capabilities', async () => {
const { registerConditionalTools } = await import('../tools/index.js');
// Server with all capabilities including experimental tasks API
const mockServerWithCapabilities = {
registerTool: vi.fn(),
server: {
getClientCapabilities: vi.fn(() => ({
roots: {},
elicitation: {},
sampling: {},
})),
},
experimental: {
tasks: {
registerToolTask: vi.fn(),
},
},
} as unknown as McpServer;
registerConditionalTools(mockServerWithCapabilities);
// Should register 3 conditional tools + 3 task-based tools when all capabilities present
expect(mockServerWithCapabilities.registerTool).toHaveBeenCalledTimes(3);
const registeredTools = (
mockServerWithCapabilities.registerTool as any
).mock.calls.map((call: any[]) => call[0]);
expect(registeredTools).toContain('get-roots-list');
expect(registeredTools).toContain('trigger-elicitation-request');
expect(registeredTools).toContain('trigger-sampling-request');
// Task-based tools are registered via experimental.tasks.registerToolTask
expect(mockServerWithCapabilities.experimental.tasks.registerToolTask).toHaveBeenCalled();
});
it('should not register conditional tools when capabilities missing', async () => {
const { registerConditionalTools } = await import('../tools/index.js');
const mockServerNoCapabilities = {
registerTool: vi.fn(),
server: {
getClientCapabilities: vi.fn(() => ({})),
},
experimental: {
tasks: {
registerToolTask: vi.fn(),
},
},
} as unknown as McpServer;
registerConditionalTools(mockServerNoCapabilities);
// Should not register any capability-gated tools when capabilities are missing
expect(mockServerNoCapabilities.registerTool).not.toHaveBeenCalled();
});
});
describe('prompts/index.ts', () => {
it('should register all prompts', async () => {
const { registerPrompts } = await import('../prompts/index.js');
const mockServer = createMockServer();
registerPrompts(mockServer);
// Should register 4 prompts
expect(mockServer.registerPrompt).toHaveBeenCalledTimes(4);
const registeredPrompts = (mockServer.registerPrompt as any).mock.calls.map(
(call: any[]) => call[0]
);
expect(registeredPrompts).toContain('simple-prompt');
expect(registeredPrompts).toContain('args-prompt');
expect(registeredPrompts).toContain('completable-prompt');
expect(registeredPrompts).toContain('resource-prompt');
});
});
describe('resources/index.ts', () => {
it('should register resource templates', async () => {
const { registerResources } = await import('../resources/index.js');
const mockServer = createMockServer();
registerResources(mockServer);
// Should register at least the 2 resource templates (text and blob) plus file resources
expect(mockServer.registerResource).toHaveBeenCalled();
const registeredResources = (mockServer.registerResource as any).mock.calls.map(
(call: any[]) => call[0]
);
expect(registeredResources).toContain('Dynamic Text Resource');
expect(registeredResources).toContain('Dynamic Blob Resource');
});
it('should read instructions from file', async () => {
const { readInstructions } = await import('../resources/index.js');
const instructions = readInstructions();
// Should return a string (either content or error message)
expect(typeof instructions).toBe('string');
expect(instructions.length).toBeGreaterThan(0);
});
});
});
```
## /src/everything/__tests__/resources.test.ts
```ts path="/src/everything/__tests__/resources.test.ts"
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
textResource,
blobResource,
textResourceUri,
blobResourceUri,
RESOURCE_TYPE_TEXT,
RESOURCE_TYPE_BLOB,
RESOURCE_TYPES,
resourceTypeCompleter,
resourceIdForPromptCompleter,
resourceIdForResourceTemplateCompleter,
registerResourceTemplates,
} from '../resources/templates.js';
import {
getSessionResourceURI,
registerSessionResource,
} from '../resources/session.js';
import { registerFileResources } from '../resources/files.js';
import {
setSubscriptionHandlers,
beginSimulatedResourceUpdates,
stopSimulatedResourceUpdates,
} from '../resources/subscriptions.js';
describe('Resource Templates', () => {
describe('Constants', () => {
it('should include both types in RESOURCE_TYPES array', () => {
expect(RESOURCE_TYPES).toContain(RESOURCE_TYPE_TEXT);
expect(RESOURCE_TYPES).toContain(RESOURCE_TYPE_BLOB);
expect(RESOURCE_TYPES).toHaveLength(2);
});
});
describe('textResourceUri', () => {
it('should create URL for text resource', () => {
const uri = textResourceUri(1);
expect(uri.toString()).toBe('demo://resource/dynamic/text/1');
});
it('should handle different resource IDs', () => {
expect(textResourceUri(5).toString()).toBe('demo://resource/dynamic/text/5');
expect(textResourceUri(100).toString()).toBe('demo://resource/dynamic/text/100');
});
});
describe('blobResourceUri', () => {
it('should create URL for blob resource', () => {
const uri = blobResourceUri(1);
expect(uri.toString()).toBe('demo://resource/dynamic/blob/1');
});
it('should handle different resource IDs', () => {
expect(blobResourceUri(5).toString()).toBe('demo://resource/dynamic/blob/5');
expect(blobResourceUri(100).toString()).toBe('demo://resource/dynamic/blob/100');
});
});
describe('textResource', () => {
it('should create text resource with correct structure', () => {
const uri = textResourceUri(1);
const resource = textResource(uri, 1);
expect(resource.uri).toBe(uri.toString());
expect(resource.mimeType).toBe('text/plain');
expect(resource.text).toContain('Resource 1');
expect(resource.text).toContain('plaintext');
});
it('should include timestamp in content', () => {
const uri = textResourceUri(2);
const resource = textResource(uri, 2);
// Timestamp format varies, just check it contains time-related content
expect(resource.text).toMatch(/\d/);
});
});
describe('blobResource', () => {
it('should create blob resource with correct structure', () => {
const uri = blobResourceUri(1);
const resource = blobResource(uri, 1);
expect(resource.uri).toBe(uri.toString());
expect(resource.mimeType).toBe('text/plain');
expect(resource.blob).toBeDefined();
});
it('should create valid base64 encoded content', () => {
const uri = blobResourceUri(3);
const resource = blobResource(uri, 3);
// Decode and verify content
const decoded = Buffer.from(resource.blob, 'base64').toString();
expect(decoded).toContain('Resource 3');
expect(decoded).toContain('base64 blob');
});
});
describe('resourceTypeCompleter', () => {
it('should be defined as a completable schema', () => {
// The completer is a zod schema wrapped with completable
expect(resourceTypeCompleter).toBeDefined();
// It should have the zod parse method
expect(typeof (resourceTypeCompleter as any).parse).toBe('function');
});
it('should validate string resource types', () => {
// Test that valid strings pass validation
expect(() => (resourceTypeCompleter as any).parse('Text')).not.toThrow();
expect(() => (resourceTypeCompleter as any).parse('Blob')).not.toThrow();
});
});
describe('resourceIdForPromptCompleter', () => {
it('should be defined as a completable schema', () => {
expect(resourceIdForPromptCompleter).toBeDefined();
expect(typeof (resourceIdForPromptCompleter as any).parse).toBe('function');
});
it('should validate string IDs', () => {
// Test that valid strings pass validation
expect(() => (resourceIdForPromptCompleter as any).parse('1')).not.toThrow();
expect(() => (resourceIdForPromptCompleter as any).parse('100')).not.toThrow();
});
});
describe('resourceIdForResourceTemplateCompleter', () => {
it('should validate positive integer IDs', () => {
expect(resourceIdForResourceTemplateCompleter('1')).toEqual(['1']);
expect(resourceIdForResourceTemplateCompleter('50')).toEqual(['50']);
});
it('should reject invalid IDs', () => {
expect(resourceIdForResourceTemplateCompleter('0')).toEqual([]);
expect(resourceIdForResourceTemplateCompleter('-5')).toEqual([]);
expect(resourceIdForResourceTemplateCompleter('not-a-number')).toEqual([]);
});
});
describe('registerResourceTemplates', () => {
it('should register text and blob resource templates', () => {
const registeredResources: any[] = [];
const mockServer = {
registerResource: vi.fn((...args) => {
registeredResources.push(args);
}),
} as unknown as McpServer;
registerResourceTemplates(mockServer);
expect(mockServer.registerResource).toHaveBeenCalledTimes(2);
// Check text resource registration
const textRegistration = registeredResources.find((r) =>
r[0].includes('Text')
);
expect(textRegistration).toBeDefined();
expect(textRegistration[1]).toBeInstanceOf(ResourceTemplate);
// Check blob resource registration
const blobRegistration = registeredResources.find((r) =>
r[0].includes('Blob')
);
expect(blobRegistration).toBeDefined();
});
});
});
describe('Session Resources', () => {
describe('getSessionResourceURI', () => {
it('should generate correct URI for resource name', () => {
expect(getSessionResourceURI('test')).toBe('demo://resource/session/test');
});
it('should handle various resource names', () => {
expect(getSessionResourceURI('my-file')).toBe('demo://resource/session/my-file');
expect(getSessionResourceURI('document_123')).toBe(
'demo://resource/session/document_123'
);
});
});
describe('registerSessionResource', () => {
it('should register text resource and return resource link', () => {
const registrations: any[] = [];
const mockServer = {
registerResource: vi.fn((...args) => {
registrations.push(args);
}),
} as unknown as McpServer;
const resource = {
uri: 'demo://resource/session/test-file',
name: 'test-file',
mimeType: 'text/plain',
description: 'A test file',
};
const result = registerSessionResource(
mockServer,
resource,
'text',
'Hello, World!'
);
expect(result.type).toBe('resource_link');
expect(result.uri).toBe(resource.uri);
expect(result.name).toBe(resource.name);
expect(mockServer.registerResource).toHaveBeenCalledWith(
'test-file',
'demo://resource/session/test-file',
expect.objectContaining({
mimeType: 'text/plain',
description: 'A test file',
}),
expect.any(Function)
);
});
it('should register blob resource correctly', () => {
const mockServer = {
registerResource: vi.fn(),
} as unknown as McpServer;
const resource = {
uri: 'demo://resource/session/binary-file',
name: 'binary-file',
mimeType: 'application/octet-stream',
};
const blobContent = Buffer.from('binary data').toString('base64');
const result = registerSessionResource(mockServer, resource, 'blob', blobContent);
expect(result.type).toBe('resource_link');
expect(mockServer.registerResource).toHaveBeenCalled();
});
it('should return resource handler that provides correct content', async () => {
let capturedHandler: Function | null = null;
const mockServer = {
registerResource: vi.fn((_name, _uri, _config, handler) => {
capturedHandler = handler;
}),
} as unknown as McpServer;
const resource = {
uri: 'demo://resource/session/content-test',
name: 'content-test',
mimeType: 'text/plain',
};
registerSessionResource(mockServer, resource, 'text', 'Test content here');
expect(capturedHandler).not.toBeNull();
const handlerResult = await capturedHandler!(new URL(resource.uri));
expect(handlerResult.contents).toHaveLength(1);
expect(handlerResult.contents[0].text).toBe('Test content here');
expect(handlerResult.contents[0].mimeType).toBe('text/plain');
});
});
});
describe('File Resources', () => {
describe('registerFileResources', () => {
it('should register file resources when docs directory exists', () => {
const mockServer = {
registerResource: vi.fn(),
} as unknown as McpServer;
registerFileResources(mockServer);
// The docs folder exists in the everything server and contains files
// so registerResource should have been called
expect(mockServer.registerResource).toHaveBeenCalled();
});
});
});
describe('Subscriptions', () => {
describe('setSubscriptionHandlers', () => {
it('should set request handlers on server', () => {
const mockServer = {
server: {
setRequestHandler: vi.fn(),
},
sendLoggingMessage: vi.fn(),
} as unknown as McpServer;
setSubscriptionHandlers(mockServer);
// Should set both subscribe and unsubscribe handlers
expect(mockServer.server.setRequestHandler).toHaveBeenCalledTimes(2);
});
});
describe('simulated resource updates lifecycle', () => {
afterEach(() => {
// Clean up any intervals
stopSimulatedResourceUpdates('lifecycle-test-session');
});
it('should start and stop updates without errors', () => {
const mockServer = {
server: {
notification: vi.fn(),
},
} as unknown as McpServer;
// Start updates - should work for both defined and undefined sessionId
beginSimulatedResourceUpdates(mockServer, 'lifecycle-test-session');
beginSimulatedResourceUpdates(mockServer, undefined);
// Stop updates - should handle all cases gracefully
stopSimulatedResourceUpdates('lifecycle-test-session');
stopSimulatedResourceUpdates('non-existent-session');
stopSimulatedResourceUpdates(undefined);
// If we got here without throwing, the lifecycle works correctly
expect(true).toBe(true);
});
});
});
```
## /src/everything/__tests__/server.test.ts
```ts path="/src/everything/__tests__/server.test.ts"
import { describe, it, expect, vi } from 'vitest';
import { createServer } from '../server/index.js';
describe('Server Factory', () => {
describe('createServer', () => {
it('should return a ServerFactoryResponse object', () => {
const result = createServer();
expect(result).toHaveProperty('server');
expect(result).toHaveProperty('cleanup');
});
it('should return a cleanup function', () => {
const { cleanup } = createServer();
expect(typeof cleanup).toBe('function');
});
it('should create an McpServer instance', () => {
const { server } = createServer();
expect(server).toBeDefined();
expect(server.server).toBeDefined();
});
it('should have an oninitialized handler set', () => {
const { server } = createServer();
expect(server.server.oninitialized).toBeDefined();
});
it('should allow multiple servers to be created', () => {
const result1 = createServer();
const result2 = createServer();
expect(result1.server).toBeDefined();
expect(result2.server).toBeDefined();
expect(result1.server).not.toBe(result2.server);
});
});
});
```
## /src/everything/__tests__/tools.test.ts
```ts path="/src/everything/__tests__/tools.test.ts"
import { describe, it, expect, vi } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerEchoTool, EchoSchema } from '../tools/echo.js';
import { registerGetSumTool } from '../tools/get-sum.js';
import { registerGetEnvTool } from '../tools/get-env.js';
import { registerGetTinyImageTool, MCP_TINY_IMAGE } from '../tools/get-tiny-image.js';
import { registerGetStructuredContentTool } from '../tools/get-structured-content.js';
import { registerGetAnnotatedMessageTool } from '../tools/get-annotated-message.js';
import { registerTriggerLongRunningOperationTool } from '../tools/trigger-long-running-operation.js';
import { registerGetResourceLinksTool } from '../tools/get-resource-links.js';
import { registerGetResourceReferenceTool } from '../tools/get-resource-reference.js';
import { registerToggleSimulatedLoggingTool } from '../tools/toggle-simulated-logging.js';
import { registerToggleSubscriberUpdatesTool } from '../tools/toggle-subscriber-updates.js';
import { registerTriggerSamplingRequestTool } from '../tools/trigger-sampling-request.js';
import { registerTriggerElicitationRequestTool } from '../tools/trigger-elicitation-request.js';
import { registerGetRootsListTool } from '../tools/get-roots-list.js';
import { registerGZipFileAsResourceTool } from '../tools/gzip-file-as-resource.js';
// Helper to capture registered tool handlers
function createMockServer() {
const handlers: Map<string, Function> = new Map();
const configs: Map<string, any> = new Map();
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
configs.set(name, config);
}),
server: {
getClientCapabilities: vi.fn(() => ({})),
notification: vi.fn(),
},
sendLoggingMessage: vi.fn(),
sendResourceUpdated: vi.fn(),
} as unknown as McpServer;
return { mockServer, handlers, configs };
}
describe('Tools', () => {
describe('echo', () => {
it('should echo back the message', async () => {
const { mockServer, handlers } = createMockServer();
registerEchoTool(mockServer);
const handler = handlers.get('echo')!;
const result = await handler({ message: 'Hello, World!' });
expect(result).toEqual({
content: [{ type: 'text', text: 'Echo: Hello, World!' }],
});
});
it('should handle empty message', async () => {
const { mockServer, handlers } = createMockServer();
registerEchoTool(mockServer);
const handler = handlers.get('echo')!;
const result = await handler({ message: '' });
expect(result).toEqual({
content: [{ type: 'text', text: 'Echo: ' }],
});
});
it('should reject invalid input', async () => {
const { mockServer, handlers } = createMockServer();
registerEchoTool(mockServer);
const handler = handlers.get('echo')!;
await expect(handler({})).rejects.toThrow();
await expect(handler({ message: 123 })).rejects.toThrow();
});
});
describe('EchoSchema', () => {
it('should validate correct input', () => {
const result = EchoSchema.parse({ message: 'test' });
expect(result).toEqual({ message: 'test' });
});
it('should reject missing message', () => {
expect(() => EchoSchema.parse({})).toThrow();
});
it('should reject non-string message', () => {
expect(() => EchoSchema.parse({ message: 123 })).toThrow();
});
});
describe('get-sum', () => {
it('should calculate sum of two positive numbers', async () => {
const { mockServer, handlers } = createMockServer();
registerGetSumTool(mockServer);
const handler = handlers.get('get-sum')!;
const result = await handler({ a: 5, b: 3 });
expect(result).toEqual({
content: [{ type: 'text', text: 'The sum of 5 and 3 is 8.' }],
});
});
it('should calculate sum with negative numbers', async () => {
const { mockServer, handlers } = createMockServer();
registerGetSumTool(mockServer);
const handler = handlers.get('get-sum')!;
const result = await handler({ a: -5, b: 3 });
expect(result).toEqual({
content: [{ type: 'text', text: 'The sum of -5 and 3 is -2.' }],
});
});
it('should calculate sum with zero', async () => {
const { mockServer, handlers } = createMockServer();
registerGetSumTool(mockServer);
const handler = handlers.get('get-sum')!;
const result = await handler({ a: 0, b: 0 });
expect(result).toEqual({
content: [{ type: 'text', text: 'The sum of 0 and 0 is 0.' }],
});
});
it('should handle floating point numbers', async () => {
const { mockServer, handlers } = createMockServer();
registerGetSumTool(mockServer);
const handler = handlers.get('get-sum')!;
const result = await handler({ a: 1.5, b: 2.5 });
expect(result).toEqual({
content: [{ type: 'text', text: 'The sum of 1.5 and 2.5 is 4.' }],
});
});
it('should reject invalid input', async () => {
const { mockServer, handlers } = createMockServer();
registerGetSumTool(mockServer);
const handler = handlers.get('get-sum')!;
await expect(handler({})).rejects.toThrow();
await expect(handler({ a: 'not a number', b: 5 })).rejects.toThrow();
await expect(handler({ a: 5 })).rejects.toThrow();
});
});
describe('get-env', () => {
it('should return all environment variables as JSON', async () => {
const { mockServer, handlers } = createMockServer();
registerGetEnvTool(mockServer);
const handler = handlers.get('get-env')!;
process.env.TEST_VAR_EVERYTHING = 'test_value';
const result = await handler({});
expect(result.content).toHaveLength(1);
expect(result.content[0].type).toBe('text');
const envJson = JSON.parse(result.content[0].text);
expect(envJson.TEST_VAR_EVERYTHING).toBe('test_value');
delete process.env.TEST_VAR_EVERYTHING;
});
it('should return valid JSON', async () => {
const { mockServer, handlers } = createMockServer();
registerGetEnvTool(mockServer);
const handler = handlers.get('get-env')!;
const result = await handler({});
expect(() => JSON.parse(result.content[0].text)).not.toThrow();
});
});
describe('get-tiny-image', () => {
it('should return image content with text descriptions', async () => {
const { mockServer, handlers } = createMockServer();
registerGetTinyImageTool(mockServer);
const handler = handlers.get('get-tiny-image')!;
const result = await handler({});
expect(result.content).toHaveLength(3);
expect(result.content[0]).toEqual({
type: 'text',
text: "Here's the image you requested:",
});
expect(result.content[1]).toEqual({
type: 'image',
data: MCP_TINY_IMAGE,
mimeType: 'image/png',
});
expect(result.content[2]).toEqual({
type: 'text',
text: 'The image above is the MCP logo.',
});
});
it('should return valid base64 image data', async () => {
const { mockServer, handlers } = createMockServer();
registerGetTinyImageTool(mockServer);
const handler = handlers.get('get-tiny-image')!;
const result = await handler({});
const imageContent = result.content[1];
expect(imageContent.type).toBe('image');
expect(imageContent.mimeType).toBe('image/png');
// Verify it's valid base64
expect(() => Buffer.from(imageContent.data, 'base64')).not.toThrow();
});
});
describe('get-structured-content', () => {
it('should return weather for New York', async () => {
const { mockServer, handlers } = createMockServer();
registerGetStructuredContentTool(mockServer);
const handler = handlers.get('get-structured-content')!;
const result = await handler({ location: 'New York' });
expect(result.structuredContent).toEqual({
temperature: 33,
conditions: 'Cloudy',
humidity: 82,
});
expect(result.content[0].type).toBe('text');
expect(JSON.parse(result.content[0].text)).toEqual(result.structuredContent);
});
it('should return weather for Chicago', async () => {
const { mockServer, handlers } = createMockServer();
registerGetStructuredContentTool(mockServer);
const handler = handlers.get('get-structured-content')!;
const result = await handler({ location: 'Chicago' });
expect(result.structuredContent).toEqual({
temperature: 36,
conditions: 'Light rain / drizzle',
humidity: 82,
});
});
it('should return weather for Los Angeles', async () => {
const { mockServer, handlers } = createMockServer();
registerGetStructuredContentTool(mockServer);
const handler = handlers.get('get-structured-content')!;
const result = await handler({ location: 'Los Angeles' });
expect(result.structuredContent).toEqual({
temperature: 73,
conditions: 'Sunny / Clear',
humidity: 48,
});
});
});
describe('get-annotated-message', () => {
it('should return error message with high priority', async () => {
const { mockServer, handlers } = createMockServer();
registerGetAnnotatedMessageTool(mockServer);
const handler = handlers.get('get-annotated-message')!;
const result = await handler({ messageType: 'error', includeImage: false });
expect(result.content).toHaveLength(1);
expect(result.content[0].text).toBe('Error: Operation failed');
expect(result.content[0].annotations).toEqual({
priority: 1.0,
audience: ['user', 'assistant'],
});
});
it('should return success message with medium priority', async () => {
const { mockServer, handlers } = createMockServer();
registerGetAnnotatedMessageTool(mockServer);
const handler = handlers.get('get-annotated-message')!;
const result = await handler({ messageType: 'success', includeImage: false });
expect(result.content[0].text).toBe('Operation completed successfully');
expect(result.content[0].annotations.priority).toBe(0.7);
expect(result.content[0].annotations.audience).toEqual(['user']);
});
it('should return debug message with low priority', async () => {
const { mockServer, handlers } = createMockServer();
registerGetAnnotatedMessageTool(mockServer);
const handler = handlers.get('get-annotated-message')!;
const result = await handler({ messageType: 'debug', includeImage: false });
expect(result.content[0].text).toContain('Debug:');
expect(result.content[0].annotations.priority).toBe(0.3);
expect(result.content[0].annotations.audience).toEqual(['assistant']);
});
it('should include annotated image when requested', async () => {
const { mockServer, handlers } = createMockServer();
registerGetAnnotatedMessageTool(mockServer);
const handler = handlers.get('get-annotated-message')!;
const result = await handler({ messageType: 'success', includeImage: true });
expect(result.content).toHaveLength(2);
expect(result.content[1].type).toBe('image');
expect(result.content[1].annotations).toEqual({
priority: 0.5,
audience: ['user'],
});
});
});
describe('trigger-long-running-operation', () => {
it('should complete operation and return result', async () => {
const { mockServer, handlers } = createMockServer();
registerTriggerLongRunningOperationTool(mockServer);
const handler = handlers.get('trigger-long-running-operation')!;
// Use very short duration for test
const result = await handler(
{ duration: 0.1, steps: 2 },
{ _meta: {}, requestId: 'test-123' }
);
expect(result.content[0].text).toContain('Long running operation completed');
expect(result.content[0].text).toContain('Duration: 0.1 seconds');
expect(result.content[0].text).toContain('Steps: 2');
}, 10000);
it('should send progress notifications when progressToken provided', async () => {
const { mockServer, handlers } = createMockServer();
registerTriggerLongRunningOperationTool(mockServer);
const handler = handlers.get('trigger-long-running-operation')!;
await handler(
{ duration: 0.1, steps: 2 },
{ _meta: { progressToken: 'token-123' }, requestId: 'test-456', sessionId: 'session-1' }
);
expect(mockServer.server.notification).toHaveBeenCalledTimes(2);
expect(mockServer.server.notification).toHaveBeenCalledWith(
expect.objectContaining({
method: 'notifications/progress',
params: expect.objectContaining({
progressToken: 'token-123',
}),
}),
expect.any(Object)
);
}, 10000);
});
describe('get-resource-links', () => {
it('should return specified number of resource links', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceLinksTool(mockServer);
const handler = handlers.get('get-resource-links')!;
const result = await handler({ count: 3 });
// 1 intro text + 3 resource links
expect(result.content).toHaveLength(4);
expect(result.content[0].type).toBe('text');
expect(result.content[0].text).toContain('3 resource links');
// Check resource links
for (let i = 1; i < 4; i++) {
expect(result.content[i].type).toBe('resource_link');
expect(result.content[i].uri).toBeDefined();
expect(result.content[i].name).toBeDefined();
}
});
it('should alternate between text and blob resources', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceLinksTool(mockServer);
const handler = handlers.get('get-resource-links')!;
const result = await handler({ count: 4 });
// Odd IDs (1, 3) are blob, even IDs (2, 4) are text
expect(result.content[1].name).toContain('Blob');
expect(result.content[2].name).toContain('Text');
expect(result.content[3].name).toContain('Blob');
expect(result.content[4].name).toContain('Text');
});
it('should use default count of 3', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceLinksTool(mockServer);
const handler = handlers.get('get-resource-links')!;
const result = await handler({});
// 1 intro text + 3 resource links (default)
expect(result.content).toHaveLength(4);
});
});
describe('get-resource-reference', () => {
it('should return text resource reference', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceReferenceTool(mockServer);
const handler = handlers.get('get-resource-reference')!;
const result = await handler({ resourceType: 'Text', resourceId: 1 });
expect(result.content).toHaveLength(3);
expect(result.content[0].text).toContain('Resource 1');
expect(result.content[1].type).toBe('resource');
expect(result.content[1].resource.uri).toContain('text/1');
expect(result.content[2].text).toContain('URI');
});
it('should return blob resource reference', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceReferenceTool(mockServer);
const handler = handlers.get('get-resource-reference')!;
const result = await handler({ resourceType: 'Blob', resourceId: 5 });
expect(result.content[1].resource.uri).toContain('blob/5');
});
it('should reject invalid resource type', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceReferenceTool(mockServer);
const handler = handlers.get('get-resource-reference')!;
await expect(handler({ resourceType: 'Invalid', resourceId: 1 })).rejects.toThrow(
'Invalid resourceType'
);
});
it('should reject invalid resource ID', async () => {
const { mockServer, handlers } = createMockServer();
registerGetResourceReferenceTool(mockServer);
const handler = handlers.get('get-resource-reference')!;
await expect(handler({ resourceType: 'Text', resourceId: -1 })).rejects.toThrow(
'Invalid resourceId'
);
await expect(handler({ resourceType: 'Text', resourceId: 0 })).rejects.toThrow(
'Invalid resourceId'
);
await expect(handler({ resourceType: 'Text', resourceId: 1.5 })).rejects.toThrow(
'Invalid resourceId'
);
});
});
describe('toggle-simulated-logging', () => {
it('should start logging when not active', async () => {
const { mockServer, handlers } = createMockServer();
registerToggleSimulatedLoggingTool(mockServer);
const handler = handlers.get('toggle-simulated-logging')!;
const result = await handler({}, { sessionId: 'test-session-1' });
expect(result.content[0].text).toContain('Started');
expect(result.content[0].text).toContain('test-session-1');
});
it('should stop logging when already active', async () => {
const { mockServer, handlers } = createMockServer();
registerToggleSimulatedLoggingTool(mockServer);
const handler = handlers.get('toggle-simulated-logging')!;
// First call starts logging
await handler({}, { sessionId: 'test-session-2' });
// Second call stops logging
const result = await handler({}, { sessionId: 'test-session-2' });
expect(result.content[0].text).toContain('Stopped');
expect(result.content[0].text).toContain('test-session-2');
});
it('should handle undefined sessionId', async () => {
const { mockServer, handlers } = createMockServer();
registerToggleSimulatedLoggingTool(mockServer);
const handler = handlers.get('toggle-simulated-logging')!;
const result = await handler({}, {});
expect(result.content[0].text).toContain('Started');
});
});
describe('toggle-subscriber-updates', () => {
it('should start updates when not active', async () => {
const { mockServer, handlers } = createMockServer();
registerToggleSubscriberUpdatesTool(mockServer);
const handler = handlers.get('toggle-subscriber-updates')!;
const result = await handler({}, { sessionId: 'sub-session-1' });
expect(result.content[0].text).toContain('Started');
expect(result.content[0].text).toContain('sub-session-1');
});
it('should stop updates when already active', async () => {
const { mockServer, handlers } = createMockServer();
registerToggleSubscriberUpdatesTool(mockServer);
const handler = handlers.get('toggle-subscriber-updates')!;
// First call starts updates
await handler({}, { sessionId: 'sub-session-2' });
// Second call stops updates
const result = await handler({}, { sessionId: 'sub-session-2' });
expect(result.content[0].text).toContain('Stopped');
expect(result.content[0].text).toContain('sub-session-2');
});
});
describe('trigger-sampling-request', () => {
it('should not register when client does not support sampling', () => {
const { mockServer } = createMockServer();
registerTriggerSamplingRequestTool(mockServer);
// Tool should not be registered since mock server returns empty capabilities
expect(mockServer.registerTool).not.toHaveBeenCalled();
});
it('should register when client supports sampling', () => {
const handlers: Map<string, Function> = new Map();
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ sampling: {} })),
},
} as unknown as McpServer;
registerTriggerSamplingRequestTool(mockServer);
expect(mockServer.registerTool).toHaveBeenCalledWith(
'trigger-sampling-request',
expect.objectContaining({
title: 'Trigger Sampling Request Tool',
description: expect.stringContaining('Sampling'),
}),
expect.any(Function)
);
});
it('should send sampling request and return result', async () => {
const handlers: Map<string, Function> = new Map();
const mockSendRequest = vi.fn().mockResolvedValue({
model: 'test-model',
content: { type: 'text', text: 'LLM response' },
});
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ sampling: {} })),
},
} as unknown as McpServer;
registerTriggerSamplingRequestTool(mockServer);
const handler = handlers.get('trigger-sampling-request')!;
const result = await handler(
{ prompt: 'Test prompt', maxTokens: 50 },
{ sendRequest: mockSendRequest }
);
expect(mockSendRequest).toHaveBeenCalledWith(
expect.objectContaining({
method: 'sampling/createMessage',
params: expect.objectContaining({
maxTokens: 50,
}),
}),
expect.anything()
);
expect(result.content[0].text).toContain('LLM sampling result');
});
});
describe('trigger-elicitation-request', () => {
it('should not register when client does not support elicitation', () => {
const { mockServer } = createMockServer();
registerTriggerElicitationRequestTool(mockServer);
expect(mockServer.registerTool).not.toHaveBeenCalled();
});
it('should register when client supports elicitation', () => {
const handlers: Map<string, Function> = new Map();
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ elicitation: {} })),
},
} as unknown as McpServer;
registerTriggerElicitationRequestTool(mockServer);
expect(mockServer.registerTool).toHaveBeenCalledWith(
'trigger-elicitation-request',
expect.objectContaining({
title: 'Trigger Elicitation Request Tool',
description: expect.stringContaining('Elicitation'),
}),
expect.any(Function)
);
});
it('should handle accept action with user content', async () => {
const handlers: Map<string, Function> = new Map();
const mockSendRequest = vi.fn().mockResolvedValue({
action: 'accept',
content: {
name: 'John Doe',
check: true,
email: 'john@example.com',
},
});
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ elicitation: {} })),
},
} as unknown as McpServer;
registerTriggerElicitationRequestTool(mockServer);
const handler = handlers.get('trigger-elicitation-request')!;
const result = await handler({}, { sendRequest: mockSendRequest });
expect(result.content[0].text).toContain('✅');
expect(result.content[0].text).toContain('provided');
expect(result.content[1].text).toContain('John Doe');
});
it('should handle decline action', async () => {
const handlers: Map<string, Function> = new Map();
const mockSendRequest = vi.fn().mockResolvedValue({
action: 'decline',
});
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ elicitation: {} })),
},
} as unknown as McpServer;
registerTriggerElicitationRequestTool(mockServer);
const handler = handlers.get('trigger-elicitation-request')!;
const result = await handler({}, { sendRequest: mockSendRequest });
expect(result.content[0].text).toContain('❌');
expect(result.content[0].text).toContain('declined');
});
it('should handle cancel action', async () => {
const handlers: Map<string, Function> = new Map();
const mockSendRequest = vi.fn().mockResolvedValue({
action: 'cancel',
});
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ elicitation: {} })),
},
} as unknown as McpServer;
registerTriggerElicitationRequestTool(mockServer);
const handler = handlers.get('trigger-elicitation-request')!;
const result = await handler({}, { sendRequest: mockSendRequest });
expect(result.content[0].text).toContain('⚠️');
expect(result.content[0].text).toContain('cancelled');
});
});
describe('get-roots-list', () => {
it('should not register when client does not support roots', () => {
const { mockServer } = createMockServer();
registerGetRootsListTool(mockServer);
expect(mockServer.registerTool).not.toHaveBeenCalled();
});
it('should register when client supports roots', () => {
const handlers: Map<string, Function> = new Map();
const mockServer = {
registerTool: vi.fn((name: string, config: any, handler: Function) => {
handlers.set(name, handler);
}),
server: {
getClientCapabilities: vi.fn(() => ({ roots: {} })),
},
} as unknown as McpServer;
registerGetRootsListTool(mockServer);
expect(mockServer.registerTool).toHaveBeenCalledWith(
'get-roots-list',
expect.objectContaining({
title: 'Get Roots List Tool',
description: expect.stringContaining('roots'),
}),
expect.any(Function)
);
});
});
describe('gzip-file-as-resource', () => {
it('should compress data URI and return resource link', async () => {
const registeredResources: any[] = [];
const mockServer = {
registerTool: vi.fn(),
registerResource: vi.fn((...args) => {
registeredResources.push(args);
}),
} as unknown as McpServer;
// Get the handler
let handler: Function | null = null;
(mockServer.registerTool as any).mockImplementation(
(name: string, config: any, h: Function) => {
handler = h;
}
);
registerGZipFileAsResourceTool(mockServer);
// Create a data URI with test content
const testContent = 'Hello, World!';
const dataUri = `data:text/plain;base64,${Buffer.from(testContent).toString('base64')}`;
const result = await handler!(
{ name: 'test.txt.gz', data: dataUri, outputType: 'resourceLink' }
);
expect(result.content[0].type).toBe('resource_link');
expect(result.content[0].uri).toContain('test.txt.gz');
});
it('should return resource directly when outputType is resource', async () => {
const mockServer = {
registerTool: vi.fn(),
registerResource: vi.fn(),
} as unknown as McpServer;
let handler: Function | null = null;
(mockServer.registerTool as any).mockImplementation(
(name: string, config: any, h: Function) => {
handler = h;
}
);
registerGZipFileAsResourceTool(mockServer);
const testContent = 'Test content for compression';
const dataUri = `data:text/plain;base64,${Buffer.from(testContent).toString('base64')}`;
const result = await handler!(
{ name: 'output.gz', data: dataUri, outputType: 'resource' }
);
expect(result.content[0].type).toBe('resource');
expect(result.content[0].resource.mimeType).toBe('application/gzip');
expect(result.content[0].resource.blob).toBeDefined();
});
it('should reject unsupported URL protocols', async () => {
const mockServer = {
registerTool: vi.fn(),
registerResource: vi.fn(),
} as unknown as McpServer;
let handler: Function | null = null;
(mockServer.registerTool as any).mockImplementation(
(name: string, config: any, h: Function) => {
handler = h;
}
);
registerGZipFileAsResourceTool(mockServer);
await expect(
handler!({ name: 'test.gz', data: 'ftp://example.com/file.txt', outputType: 'resource' })
).rejects.toThrow('Unsupported URL protocol');
});
});
});
```
## /src/everything/docs/architecture.md
# Everything Server – Architecture
**Architecture
| [Project Structure](structure.md)
| [Startup Process](startup.md)
| [Server Features](features.md)
| [Extension Points](extension.md)
| [How It Works](how-it-works.md)**
This documentation summarizes the current layout and runtime architecture of the `src/everything` package.
It explains how the server starts, how transports are wired, where tools, prompts, and resources are registered, and how to extend the system.
## High‑level Overview
### Purpose
A minimal, modular MCP server showcasing core Model Context Protocol features. It exposes simple tools, prompts, and resources, and can be run over multiple transports (STDIO, SSE, and Streamable HTTP).
### Design
A small “server factory” constructs the MCP server and registers features.
Transports are separate entry points that create/connect the server and handle network concerns.
Tools, prompts, and resources are organized in their own submodules.
### Multi‑client
The server supports multiple concurrent clients. Tracking per session data is demonstrated with
resource subscriptions and simulated logging.
## Build and Distribution
- TypeScript sources are compiled into `dist/` via `npm run build`.
- The `build` script copies `docs/` into `dist/` so instruction files ship alongside the compiled server.
- The CLI bin is configured in `package.json` as `mcp-server-everything` → `dist/index.js`.
## [Project Structure](structure.md)
## [Startup Process](startup.md)
## [Server Features](features.md)
## [Extension Points](extension.md)
## [How It Works](how-it-works.md)
## /src/everything/docs/extension.md
# Everything Server - Extension Points
**[Architecture](architecture.md)
| [Project Structure](structure.md)
| [Startup Process](startup.md)
| [Server Features](features.md)
| Extension Points
| [How It Works](how-it-works.md)**
## Adding Tools
- Create a new file under `tools/` with your `registerXTool(server)` function that registers the tool via `server.registerTool(...)`.
- Export and call it from `tools/index.ts` inside `registerTools(server)`.
## Adding Prompts
- Create a new file under `prompts/` with your `registerXPrompt(server)` function that registers the prompt via `server.registerPrompt(...)`.
- Export and call it from `prompts/index.ts` inside `registerPrompts(server)`.
## Adding Resources
- Create a new file under `resources/` with your `registerXResources(server)` function using `server.registerResource(...)` (optionally with `ResourceTemplate`).
- Export and call it from `resources/index.ts` inside `registerResources(server)`.
## /src/everything/docs/features.md
# Everything Server - Features
**[Architecture](architecture.md)
| [Project Structure](structure.md)
| [Startup Process](startup.md)
| Server Features
| [Extension Points](extension.md)
| [How It Works](how-it-works.md)**
## Tools
- `echo` (tools/echo.ts): Echoes the provided `message: string`. Uses Zod to validate inputs.
- `get-annotated-message` (tools/get-annotated-message.ts): Returns a `text` message annotated with `priority` and `audience` based on `messageType` (`error`, `success`, or `debug`); can optionally include an annotated `image`.
- `get-env` (tools/get-env.ts): Returns all environment variables from the running process as pretty-printed JSON text.
- `get-resource-links` (tools/get-resource-links.ts): Returns an intro `text` block followed by multiple `resource_link` items. For a requested `count` (1–10), alternates between dynamic Text and Blob resources using URIs from `resources/templates.ts`.
- `get-resource-reference` (tools/get-resource-reference.ts): Accepts `resourceType` (`text` or `blob`) and `resourceId` (positive integer). Returns a concrete `resource` content block (with its `uri`, `mimeType`, and data) with surrounding explanatory `text`.
- `get-roots-list` (tools/get-roots-list.ts): Returns the last list of roots sent by the client.
- `gzip-file-as-resource` (tools/gzip-file-as-resource.ts): Accepts a `name` and `data` (URL or data URI), fetches the data subject to size/time/domain constraints, compresses it, registers it as a session resource at `demo://resource/session/<name>` with `mimeType: application/gzip`, and returns either a `resource_link` (default) or an inline `resource` depending on `outputType`.
- `get-structured-content` (tools/get-structured-content.ts): Demonstrates structured responses. Accepts `location` input and returns both backward‑compatible `content` (a `text` block containing JSON) and `structuredContent` validated by an `outputSchema` (temperature, conditions, humidity).
- `get-sum` (tools/get-sum.ts): For two numbers `a` and `b` calculates and returns their sum. Uses Zod to validate inputs.
- `get-tiny-image` (tools/get-tiny-image.ts): Returns a tiny PNG MCP logo as an `image` content item with brief descriptive text before and after.
- `trigger-long-running-operation` (tools/trigger-trigger-long-running-operation.ts): Simulates a multi-step operation over a given `duration` and number of `steps`; reports progress via `notifications/progress` when a `progressToken` is provided by the client.
- `toggle-simulated-logging` (tools/toggle-simulated-logging.ts): Starts or stops simulated, random‑leveled logging for the invoking session. Respects the client’s selected minimum logging level.
- `toggle-subscriber-updates` (tools/toggle-subscriber-updates.ts): Starts or stops simulated resource update notifications for URIs the invoking session has subscribed to.
- `trigger-sampling-request` (tools/trigger-sampling-request.ts): Issues a `sampling/createMessage` request to the client/LLM using provided `prompt` and optional generation controls; returns the LLM's response payload.
- `simulate-research-query` (tools/simulate-research-query.ts): Demonstrates MCP Tasks (SEP-1686) with a simulated multi-stage research operation. Accepts `topic` and `ambiguous` parameters. Returns a task that progresses through stages with status updates. If `ambiguous` is true and client supports elicitation, sends an elicitation request directly to gather clarification before completing.
- `trigger-sampling-request-async` (tools/trigger-sampling-request-async.ts): Demonstrates bidirectional tasks where the server sends a sampling request that the client executes as a background task. Server polls for status and retrieves the LLM result when complete. Requires client to support `tasks.requests.sampling.createMessage`.
- `trigger-elicitation-request-async` (tools/trigger-elicitation-request-async.ts): Demonstrates bidirectional tasks where the server sends an elicitation request that the client executes as a background task. Server polls while waiting for user input. Requires client to support `tasks.requests.elicitation.create`.
## Prompts
- `simple-prompt` (prompts/simple.ts): No-argument prompt that returns a static user message.
- `args-prompt` (prompts/args.ts): Two-argument prompt with `city` (required) and `state` (optional) used to compose a question.
- `completable-prompt` (prompts/completions.ts): Demonstrates argument auto-completions with the SDK’s `completable` helper; `department` completions drive context-aware `name` suggestions.
- `resource-prompt` (prompts/resource.ts): Accepts `resourceType` ("Text" or "Blob") and `resourceId` (string convertible to integer) and returns messages that include an embedded dynamic resource of the selected type generated via `resources/templates.ts`.
## Resources
- Dynamic Text: `demo://resource/dynamic/text/{index}` (content generated on the fly)
- Dynamic Blob: `demo://resource/dynamic/blob/{index}` (base64 payload generated on the fly)
- Static Documents: `demo://resource/static/document/<filename>` (serves files from `src/everything/docs/` as static file-based resources)
- Session Scoped: `demo://resource/session/<name>` (per-session resources registered dynamically; available only for the lifetime of the session)
## Resource Subscriptions and Notifications
- Simulated update notifications are opt‑in and off by default.
- Clients may subscribe/unsubscribe to resource URIs using the MCP `resources/subscribe` and `resources/unsubscribe` requests.
- Use the `toggle-subscriber-updates` tool to start/stop a per‑session interval that emits `notifications/resources/updated { uri }` only for URIs that session has subscribed to.
- Multiple concurrent clients are supported; each client’s subscriptions are tracked per session and notifications are delivered independently via the server instance associated with that session.
## Simulated Logging
- Simulated logging is available but off by default.
- Use the `toggle-simulated-logging` tool to start/stop periodic log messages of varying levels (debug, info, notice, warning, error, critical, alert, emergency) per session.
- Clients can control the minimum level they receive via the standard MCP `logging/setLevel` request.
## Tasks (SEP-1686)
The server advertises support for MCP Tasks, enabling long-running operations with status tracking:
- **Capabilities advertised**: `tasks.list`, `tasks.cancel`, `tasks.requests.tools.call`
- **Task Store**: Uses `InMemoryTaskStore` from SDK experimental for task lifecycle management
- **Message Queue**: Uses `InMemoryTaskMessageQueue` for task-related messaging
### Task Lifecycle
1. Client calls `tools/call` with `task: true` parameter
2. Server returns `CreateTaskResult` with `taskId` instead of immediate result
3. Client polls `tasks/get` to check status and receive `statusMessage` updates
4. When status is `completed`, client calls `tasks/result` to retrieve the final result
### Task Statuses
- `working`: Task is actively processing
- `input_required`: Task needs additional input (server sends elicitation request directly)
- `completed`: Task finished successfully
- `failed`: Task encountered an error
- `cancelled`: Task was cancelled by client
### Demo Tools
**Server-side tasks (client calls server):**
Use the `simulate-research-query` tool to exercise the full task lifecycle. Set `ambiguous: true` to trigger elicitation - the server will send an `elicitation/create` request directly and await the response before completing.
**Client-side tasks (server calls client):**
Use `trigger-sampling-request-async` or `trigger-elicitation-request-async` to demonstrate bidirectional tasks where the server sends requests that the client executes as background tasks. These require the client to advertise `tasks.requests.sampling.createMessage` or `tasks.requests.elicitation.create` capabilities respectively.
### Bidirectional Task Flow
MCP Tasks are bidirectional - both server and client can be task executors:
| Direction | Request Type | Task Executor | Demo Tool |
| ---------------- | ------------------------ | ------------- | ----------------------------------- |
| Client -> Server | `tools/call` | Server | `simulate-research-query` |
| Server -> Client | `sampling/createMessage` | Client | `trigger-sampling-request-async` |
| Server -> Client | `elicitation/create` | Client | `trigger-elicitation-request-async` |
For client-side tasks:
1. Server sends request with task metadata (e.g., `params.task.ttl`)
2. Client creates task and returns `CreateTaskResult` with `taskId`
3. Server polls `tasks/get` for status updates
4. When complete, server calls `tasks/result` to retrieve the result
## /src/everything/docs/how-it-works.md
# Everything Server - How It Works
**[Architecture](architecture.md)
| [Project Structure](structure.md)
| [Startup Process](startup.md)
| [Server Features](features.md)
| [Extension Points](extension.md)
| How It Works**
# Conditional Tool Registration
### Module: `server/index.ts`
- Some tools require client support for the capability they demonstrate. These are:
- `get-roots-list`
- `trigger-elicitation-request`
- `trigger-sampling-request`
- Client capabilities aren't known until after initilization handshake is complete.
- Most tools are registered immediately during the Server Factory execution, prior to client connection.
- To defer registration of these commands until client capabilities are known, a `registerConditionalTools(server)` function is invoked from an `onintitialized` handler.
## Resource Subscriptions
### Module: `resources/subscriptions.ts`
- Tracks subscribers per URI: `Map<uri, Set<sessionId>>`.
- Installs handlers via `setSubscriptionHandlers(server)` to process subscribe/unsubscribe requests and keep the map updated.
- Updates are started/stopped on demand by the `toggle-subscriber-updates` tool, which calls `beginSimulatedResourceUpdates(server, sessionId)` and `stopSimulatedResourceUpdates(sessionId)`.
- `cleanup(sessionId?)` calls `stopSimulatedResourceUpdates(sessionId)` to clear intervals and remove session‑scoped state.
## Session‑scoped Resources
### Module: `resources/session.ts`
- `getSessionResourceURI(name: string)`: Builds a session resource URI: `demo://resource/session/<name>`.
- `registerSessionResource(server, resource, type, payload)`: Registers a resource with the given `uri`, `name`, and `mimeType`, returning a `resource_link`. The content is served from memory for the life of the session only. Supports `type: "text" | "blob"` and returns data in the corresponding field.
- Intended usage: tools can create and expose per-session artifacts without persisting them. For example, `tools/gzip-file-as-resource.ts` compresses fetched content, registers it as a session resource with `mimeType: application/gzip`, and returns either a `resource_link` or an inline `resource` based on `outputType`.
## Simulated Logging
### Module: `server/logging.ts`
- Periodically sends randomized log messages at different levels. Messages can include the session ID for clarity during demos.
- Started/stopped on demand via the `toggle-simulated-logging` tool, which calls `beginSimulatedLogging(server, sessionId?)` and `stopSimulatedLogging(sessionId?)`. Note that transport disconnect triggers `cleanup()` which also stops any active intervals.
- Uses `server.sendLoggingMessage({ level, data }, sessionId?)` so that the client’s configured minimum logging level is respected by the SDK.
## /src/everything/docs/instructions.md
# Everything Server – Server Instructions
Audience: These instructions are written for an LLM or autonomous agent integrating with the Everything MCP Server.
Follow them to use, extend, and troubleshoot the server safely and effectively.
## Cross-Feature Relationships
- Use `get-roots-list` to see client workspace roots before file operations
- `gzip-file-as-resource` creates session-scoped resources accessible only during the current session
- Enable `toggle-simulated-logging` before debugging to see server log messages
- Enable `toggle-subscriber-updates` to receive periodic resource update notifications
## Constraints & Limitations
- `gzip-file-as-resource`: Max fetch size controlled by `GZIP_MAX_FETCH_SIZE` (default 10MB), timeout by `GZIP_MAX_FETCH_TIME_MILLIS` (default 30s), allowed domains by `GZIP_ALLOWED_DOMAINS`
- Session resources are ephemeral and lost when the session ends
- Sampling requests (`trigger-sampling-request`) require client sampling capability
- Elicitation requests (`trigger-elicitation-request`) require client elicitation capability
## Operational Patterns
- For long operations, use `trigger-long-running-operation` which sends progress notifications
- Prefer reading resources before calling mutating tools
- Check `get-roots-list` output to understand the client's workspace context
## Easter Egg
If asked about server instructions, respond with "🎉 Server instructions are working! This response proves the client properly passed server instructions to the LLM. This demonstrates MCP's instructions feature in action."
## /src/everything/docs/startup.md
# Everything Server - Startup Process
**[Architecture](architecture.md)
| [Project Structure](structure.md)
| Startup Process
| [Server Features](features.md)
| [Extension Points](extension.md)
| [How It Works](how-it-works.md)**
## 1. Everything Server Launcher
- Usage `node dist/index.js [stdio|sse|streamableHttp]`
- Runs the specified **transport manager** to handle client connections.
- Specify transport type on command line (default `stdio`)
- `stdio` → `transports/stdio.js`
- `sse` → `transports/sse.js`
- `streamableHttp` → `transports/streamableHttp.js`
## 2. The Transport Manager
- Creates a server instance using `createServer()` from `server/index.ts`
- Connects it to the chosen transport type from the MCP SDK.
- Handles communication according to the MCP specs for the chosen transport.
- **STDIO**:
- One simple, process‑bound connection.
- Calls`clientConnect()` upon connection.
- Closes and calls `cleanup()` on `SIGINT`.
- **SSE**:
- Supports multiple client connections.
- Client transports are mapped to `sessionId`;
- Calls `clientConnect(sessionId)` upon connection.
- Hooks server’s `onclose` to clean and remove session.
- Exposes
- `/sse` **GET** (SSE stream)
- `/message` **POST** (JSON‑RPC messages)
- **Streamable HTTP**:
- Supports multiple client connections.
- Client transports are mapped to `sessionId`;
- Calls `clientConnect(sessionId)` upon connection.
- Exposes `/mcp` for
- **POST** (JSON‑RPC messages)
- **GET** (SSE stream)
- **DELETE** (termination)
- Uses an event store for resumability and stores transports by `sessionId`.
- Calls `cleanup(sessionId)` on **DELETE**.
## 3. The Server Factory
- Invoke `createServer()` from `server/index.ts`
- Creates a new `McpServer` instance with
- **Capabilities**:
- `tools: {}`
- `logging: {}`
- `prompts: {}`
- `resources: { subscribe: true }`
- **Server Instructions**
- Loaded from the docs folder (`server-instructions.md`).
- **Registrations**
- Registers **tools** via `registerTools(server)`.
- Registers **resources** via `registerResources(server)`.
- Registers **prompts** via `registerPrompts(server)`.
- **Other Request Handlers**
- Sets up resource subscription handlers via `setSubscriptionHandlers(server)`.
- Roots list change handler is added post-connection via
- **Returns**
- The `McpServer` instance
- A `clientConnect(sessionId)` callback that enables post-connection setup
- A `cleanup(sessionId?)` callback that stops any active intervals and removes any session‑scoped state
## Enabling Multiple Clients
Some of the transport managers defined in the `transports` folder can support multiple clients.
In order to do so, they must map certain data to a session identifier.
## /src/everything/docs/structure.md
# Everything Server - Project Structure
**[Architecture](architecture.md)
| Project Structure
| [Startup Process](startup.md)
| [Server Features](features.md)
| [Extension Points](extension.md)
| [How It Works](how-it-works.md)**
```
src/everything
├── index.ts
├── AGENTS.md
├── package.json
├── docs
│ ├── architecture.md
│ ├── extension.md
│ ├── features.md
│ ├── how-it-works.md
│ ├── instructions.md
│ ├── startup.md
│ └── structure.md
├── prompts
│ ├── index.ts
│ ├── args.ts
│ ├── completions.ts
│ ├── simple.ts
│ └── resource.ts
├── resources
│ ├── index.ts
│ ├── files.ts
│ ├── session.ts
│ ├── subscriptions.ts
│ └── templates.ts
├── server
│ ├── index.ts
│ ├── logging.ts
│ └── roots.ts
├── tools
│ ├── index.ts
│ ├── echo.ts
│ ├── get-annotated-message.ts
│ ├── get-env.ts
│ ├── get-resource-links.ts
│ ├── get-resource-reference.ts
│ ├── get-roots-list.ts
│ ├── get-structured-content.ts
│ ├── get-sum.ts
│ ├── get-tiny-image.ts
│ ├── gzip-file-as-resource.ts
│ ├── toggle-simulated-logging.ts
│ ├── toggle-subscriber-updates.ts
│ ├── trigger-elicitation-request.ts
│ ├── trigger-long-running-operation.ts
│ └── trigger-sampling-request.ts
└── transports
├── sse.ts
├── stdio.ts
└── streamableHttp.ts
```
# Project Contents
## `src/everything`:
### `index.ts`
- CLI entry point that selects and runs a specific transport module based on the first CLI argument: `stdio`, `sse`, or `streamableHttp`.
### `AGENTS.md`
- Directions for Agents/LLMs explaining coding guidelines and how to appropriately extend the server.
### `package.json`
- Package metadata and scripts:
- `build`: TypeScript compile to `dist/`, copies `docs/` into `dist/` and marks the compiled entry scripts as executable.
- `start:stdio`, `start:sse`, `start:streamableHttp`: Run built transports from `dist/`.
- Declares dependencies on `@modelcontextprotocol/sdk`, `express`, `cors`, `zod`, etc.
### `docs/`
- `architecture.md`
- This document.
- `server-instructions.md`
- Human‑readable instructions intended to be passed to the client/LLM as for guidance on server use. Loaded by the server at startup and returned in the "initialize" exchange.
### `prompts/`
- `index.ts`
- `registerPrompts(server)` orchestrator; delegates to prompt factory/registration methods from in individual prompt files.
- `simple.ts`
- Registers `simple-prompt`: a prompt with no arguments that returns a single user message.
- `args.ts`
- Registers `args-prompt`: a prompt with two arguments (`city` required, `state` optional) used to compose a message.
- `completions.ts`
- Registers `completable-prompt`: a prompt whose arguments support server-driven completions using the SDK’s `completable(...)` helper (e.g., completing `department` and context-aware `name`).
- `resource.ts`
- Exposes `registerEmbeddedResourcePrompt(server)` which registers `resource-prompt` — a prompt that accepts `resourceType` ("Text" or "Blob") and `resourceId` (integer), and embeds a dynamically generated resource of the requested type within the returned messages. Internally reuses helpers from `resources/templates.ts`.
### `resources/`
- `index.ts`
- `registerResources(server)` orchestrator; delegates to resource factory/registration methods from individual resource files.
- `templates.ts`
- Registers two dynamic, template‑driven resources using `ResourceTemplate`:
- Text: `demo://resource/dynamic/text/{index}` (MIME: `text/plain`)
- Blob: `demo://resource/dynamic/blob/{index}` (MIME: `application/octet-stream`, Base64 payload)
- The `{index}` path variable must be a finite positive integer. Content is generated on demand with a timestamp.
- Exposes helpers `textResource(uri, index)`, `textResourceUri(index)`, `blobResource(uri, index)`, and `blobResourceUri(index)` so other modules can construct and embed dynamic resources directly (e.g., from prompts).
- `files.ts`
- Registers static file-based resources for each file in the `docs/` folder.
- URIs follow the pattern: `demo://resource/static/document/<filename>`.
- Serves markdown files as `text/markdown`, `.txt` as `text/plain`, `.json` as `application/json`, others default to `text/plain`.
### `server/`
- `index.ts`
- Server factory that creates an `McpServer` with declared capabilities, loads server instructions, and registers tools, prompts, and resources.
- Sets resource subscription handlers via `setSubscriptionHandlers(server)`.
- Exposes `{ server, cleanup }` to the chosen transport. Cleanup stops any running intervals in the server when the transport disconnects.
- `logging.ts`
- Implements simulated logging. Periodically sends randomized log messages at various levels to the connected client session. Started/stopped on demand via a dedicated tool.
### `tools/`
- `index.ts`
- `registerTools(server)` orchestrator; delegates to tool factory/registration methods in individual tool files.
- `echo.ts`
- Registers an `echo` tool that takes a message and returns `Echo: {message}`.
- `get-annotated-message.ts`
- Registers an `annotated-message` tool which demonstrates annotated content items by emitting a primary `text` message with `annotations` that vary by `messageType` (`"error" | "success" | "debug"`), and optionally includes an annotated `image` (tiny PNG) when `includeImage` is true.
- `get-env.ts`
- Registers a `get-env` tool that returns the current process environment variables as formatted JSON text; useful for debugging configuration.
- `get-resource-links.ts`
- Registers a `get-resource-links` tool that returns an intro `text` block followed by multiple `resource_link` items.
- `get-resource-reference.ts`
- Registers a `get-resource-reference` tool that returns a reference for a selected dynamic resource.
- `get-roots-list.ts`
- Registers a `get-roots-list` tool that returns the last list of roots sent by the client.
- `gzip-file-as-resource.ts`
- Registers a `gzip-file-as-resource` tool that fetches content from a URL or data URI, compresses it, and then either:
- returns a `resource_link` to a session-scoped resource (default), or
- returns an inline `resource` with the gzipped data. The resource will be still discoverable for the duration of the session via `resources/list`.
- Uses `resources/session.ts` to register the gzipped blob as a per-session resource at a URI like `demo://resource/session/<name>` with `mimeType: application/gzip`.
- Environment controls:
- `GZIP_MAX_FETCH_SIZE` (bytes, default 10 MiB)
- `GZIP_MAX_FETCH_TIME_MILLIS` (ms, default 30000)
- `GZIP_ALLOWED_DOMAINS` (comma-separated allowlist; empty means all domains allowed)
- `trigger-elicitation-request.ts`
- Registers a `trigger-elicitation-request` tool that sends an `elicitation/create` request to the client/LLM and returns the elicitation result.
- `trigger-sampling-request.ts`
- Registers a `trigger-sampling-request` tool that sends a `sampling/createMessage` request to the client/LLM and returns the sampling result.
- `get-structured-content.ts`
- Registers a `get-structured-content` tool that demonstrates structuredContent block responses.
- `get-sum.ts`
- Registers an `get-sum` tool with a Zod input schema that sums two numbers `a` and `b` and returns the result.
- `get-tiny-image.ts`
- Registers a `get-tiny-image` tool, which returns a tiny PNG MCP logo as an `image` content item, along with surrounding descriptive `text` items.
- `trigger-long-running-operation.ts`
- Registers a `long-running-operation` tool that simulates a long-running task over a specified `duration` (seconds) and number of `steps`; emits `notifications/progress` updates when the client supplies a `progressToken`.
- `toggle-simulated-logging.ts`
- Registers a `toggle-simulated-logging` tool, which starts or stops simulated logging for the invoking session.
- `toggle-subscriber-updates.ts`
- Registers a `toggle-subscriber-updates` tool, which starts or stops simulated resource subscription update checks for the invoking session.
### `transports/`
- `stdio.ts`
- Starts a `StdioServerTransport`, created the server via `createServer()`, and connects it.
- Handles `SIGINT` to close cleanly and calls `cleanup()` to remove any live intervals.
- `sse.ts`
- Express server exposing:
- `GET /sse` to establish an SSE connection per session.
- `POST /message` for client messages.
- Manages multiple connected clients via a transport map.
- Starts an `SSEServerTransport`, created the server via `createServer()`, and connects it to a new transport.
- On server disconnect, calls `cleanup()` to remove any live intervals.
- `streamableHttp.ts`
- Express server exposing a single `/mcp` endpoint for POST (JSON‑RPC), GET (SSE stream), and DELETE (session termination) using `StreamableHTTPServerTransport`.
- Uses an `InMemoryEventStore` for resumable sessions and tracks transports by `sessionId`.
- Connects a fresh server instance on initialization POST and reuses the transport for subsequent requests.
## /src/everything/index.ts
```ts path="/src/everything/index.ts"
#!/usr/bin/env node
// Parse command line arguments first
const args = process.argv.slice(2);
const scriptName = args[0] || "stdio";
async function run() {
try {
// Dynamically import only the requested module to prevent all modules from initializing
switch (scriptName) {
case "stdio":
// Import and run the default server
await import("./transports/stdio.js");
break;
case "sse":
// Import and run the SSE server
await import("./transports/sse.js");
break;
case "streamableHttp":
// Import and run the streamable HTTP server
await import("./transports/streamableHttp.js");
break;
default:
console.error(`-`.repeat(53));
console.error(` Everything Server Launcher`);
console.error(` Usage: node ./index.js [stdio|sse|streamableHttp]`);
console.error(` Default transport: stdio`);
console.error(`-`.repeat(53));
console.error(`Unknown transport: ${scriptName}`);
console.log("Available transports:");
console.log("- stdio");
console.log("- sse");
console.log("- streamableHttp");
process.exit(1);
}
} catch (error) {
console.error("Error running script:", error);
process.exit(1);
}
}
await run();
```
## /src/everything/package.json
```json path="/src/everything/package.json"
{
"name": "@modelcontextprotocol/server-everything",
"version": "2.0.0",
"description": "MCP server that exercises all the features of the MCP protocol",
"license": "SEE LICENSE IN LICENSE",
"mcpName": "io.github.modelcontextprotocol/server-everything",
"author": "Model Context Protocol a Series of LF Projects, LLC.",
"homepage": "https://modelcontextprotocol.io",
"bugs": "https://github.com/modelcontextprotocol/servers/issues",
"repository": {
"type": "git",
"url": "https://github.com/modelcontextprotocol/servers.git"
},
"type": "module",
"bin": {
"mcp-server-everything": "dist/index.js"
},
"files": [
"dist"
],
"scripts": {
"build": "tsc && shx cp -r docs dist/ && shx chmod +x dist/*.js",
"prepare": "npm run build",
"watch": "tsc --watch",
"start:stdio": "node dist/index.js stdio",
"start:sse": "node dist/index.js sse",
"start:streamableHttp": "node dist/index.js streamableHttp",
"prettier:fix": "prettier --write .",
"prettier:check": "prettier --check .",
"test": "vitest run --coverage"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.29.0",
"cors": "^2.8.5",
"express": "^5.2.1",
"jszip": "^3.10.1",
"zod": "^4.0.0"
},
"devDependencies": {
"@types/cors": "^2.8.19",
"@types/express": "^5.0.6",
"@vitest/coverage-v8": "^2.1.8",
"prettier": "^2.8.8",
"shx": "^0.3.4",
"typescript": "^5.6.2",
"vitest": "^2.1.8"
}
}
```
## /src/everything/prompts/args.ts
```ts path="/src/everything/prompts/args.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
/**
* Register a prompt with arguments
* - Two arguments, one required and one optional
* - Combines argument values in the returned prompt
*
* @param server
*/
export const registerArgumentsPrompt = (server: McpServer) => {
// Prompt arguments
const promptArgsSchema = {
city: z.string().describe("Name of the city"),
state: z.string().describe("Name of the state").optional(),
};
// Register the prompt
server.registerPrompt(
"args-prompt",
{
title: "Arguments Prompt",
description: "A prompt with two arguments, one required and one optional",
argsSchema: promptArgsSchema,
},
(args) => {
const location = `${args?.city}${args?.state ? `, ${args?.state}` : ""}`;
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `What's weather in ${location}?`,
},
},
],
};
}
);
};
```
## /src/everything/prompts/completions.ts
```ts path="/src/everything/prompts/completions.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
/**
* Register a prompt with completable arguments
* - Two required arguments, both with completion handlers
* - First argument value will be included in context for second argument
* - Allows second argument to depend on the first argument value
*
* @param server
*/
export const registerPromptWithCompletions = (server: McpServer) => {
// Prompt arguments
const promptArgsSchema = {
department: completable(
z.string().describe("Choose the department."),
(value) => {
return ["Engineering", "Sales", "Marketing", "Support"].filter((d) =>
d.startsWith(value)
);
}
),
name: completable(
z
.string()
.describe("Choose a team member to lead the selected department."),
(value, context) => {
const department = context?.arguments?.["department"];
if (department === "Engineering") {
return ["Alice", "Bob", "Charlie"].filter((n) => n.startsWith(value));
} else if (department === "Sales") {
return ["David", "Eve", "Frank"].filter((n) => n.startsWith(value));
} else if (department === "Marketing") {
return ["Grace", "Henry", "Iris"].filter((n) => n.startsWith(value));
} else if (department === "Support") {
return ["John", "Kim", "Lee"].filter((n) => n.startsWith(value));
}
return [];
}
),
};
// Register the prompt
server.registerPrompt(
"completable-prompt",
{
title: "Team Management",
description: "First argument choice narrows values for second argument.",
argsSchema: promptArgsSchema,
},
({ department, name }) => ({
messages: [
{
role: "user",
content: {
type: "text",
text: `Please promote ${name} to the head of the ${department} team.`,
},
},
],
})
);
};
```
## /src/everything/prompts/index.ts
```ts path="/src/everything/prompts/index.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerSimplePrompt } from "./simple.js";
import { registerArgumentsPrompt } from "./args.js";
import { registerPromptWithCompletions } from "./completions.js";
import { registerEmbeddedResourcePrompt } from "./resource.js";
/**
* Register the prompts with the MCP server.
*
* @param server
*/
export const registerPrompts = (server: McpServer) => {
registerSimplePrompt(server);
registerArgumentsPrompt(server);
registerPromptWithCompletions(server);
registerEmbeddedResourcePrompt(server);
};
```
## /src/everything/prompts/resource.ts
```ts path="/src/everything/prompts/resource.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
resourceTypeCompleter,
resourceIdForPromptCompleter,
} from "../resources/templates.js";
import {
textResource,
textResourceUri,
blobResourceUri,
blobResource,
RESOURCE_TYPE_BLOB,
RESOURCE_TYPE_TEXT,
RESOURCE_TYPES,
} from "../resources/templates.js";
/**
* Register a prompt with an embedded resource reference
* - Takes a resource type and id
* - Returns the corresponding dynamically created resource
*
* @param server
*/
export const registerEmbeddedResourcePrompt = (server: McpServer) => {
// Prompt arguments
const promptArgsSchema = {
resourceType: resourceTypeCompleter,
resourceId: resourceIdForPromptCompleter,
};
// Register the prompt
server.registerPrompt(
"resource-prompt",
{
title: "Resource Prompt",
description: "A prompt that includes an embedded resource reference",
argsSchema: promptArgsSchema,
},
(args) => {
// Validate resource type argument
const resourceType = args.resourceType;
if (
!RESOURCE_TYPES.includes(
resourceType as typeof RESOURCE_TYPE_TEXT | typeof RESOURCE_TYPE_BLOB
)
) {
throw new Error(
`Invalid resourceType: ${args?.resourceType}. Must be ${RESOURCE_TYPE_TEXT} or ${RESOURCE_TYPE_BLOB}.`
);
}
// Validate resourceId argument
const resourceId = Number(args?.resourceId);
if (
!Number.isFinite(resourceId) ||
!Number.isInteger(resourceId) ||
resourceId < 1
) {
throw new Error(
`Invalid resourceId: ${args?.resourceId}. Must be a finite positive integer.`
);
}
// Get resource based on the resource type
const uri =
resourceType === RESOURCE_TYPE_TEXT
? textResourceUri(resourceId)
: blobResourceUri(resourceId);
const resource =
resourceType === RESOURCE_TYPE_TEXT
? textResource(uri, resourceId)
: blobResource(uri, resourceId);
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `This prompt includes the ${resourceType} resource with id: ${resourceId}. Please analyze the following resource:`,
},
},
{
role: "user",
content: {
type: "resource",
resource: resource,
},
},
],
};
}
);
};
```
## /src/everything/prompts/simple.ts
```ts path="/src/everything/prompts/simple.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
/**
* Register a simple prompt with no arguments
* - Returns the fixed text of the prompt with no modifications
*
* @param server
*/
export const registerSimplePrompt = (server: McpServer) => {
// Register the prompt
server.registerPrompt(
"simple-prompt",
{
title: "Simple Prompt",
description: "A prompt with no arguments",
},
() => ({
messages: [
{
role: "user",
content: {
type: "text",
text: "This is a simple prompt without arguments.",
},
},
],
})
);
};
```
## /src/everything/resources/files.ts
```ts path="/src/everything/resources/files.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { dirname, join } from "path";
import { fileURLToPath } from "url";
import { readdirSync, readFileSync, statSync } from "fs";
/**
* Register static file resources
* - Each file in src/everything/docs is exposed as an individual static resource
* - URIs follow the pattern: "demo://static/docs/<filename>"
* - Markdown (.md) files are served as mime type "text/markdown"
* - Text (.txt) files are served as mime type "text/plain"
* - JSON (.json) files are served as mime type "application/json"
*
* @param server
*/
export const registerFileResources = (server: McpServer) => {
// Read the entries in the docs directory
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const docsDir = join(__dirname, "..", "docs");
let entries: string[] = [];
try {
entries = readdirSync(docsDir);
} catch (e) {
// If docs/ folder is missing or unreadable, just skip registration
return;
}
// Register each file as a static resource
for (const name of entries) {
// Only process files, not directories
const fullPath = join(docsDir, name);
try {
const st = statSync(fullPath);
if (!st.isFile()) continue;
} catch {
continue;
}
// Prepare file resource info
const uri = `demo://resource/static/document/${encodeURIComponent(name)}`;
const mimeType = getMimeType(name);
const description = `Static document file exposed from /docs: ${name}`;
// Register file resource
server.registerResource(
name,
uri,
{ mimeType, description },
async (uri) => {
const text = readFileSafe(fullPath);
return {
contents: [
{
uri: uri.toString(),
mimeType,
text,
},
],
};
}
);
}
};
/**
* Get the mimetype based on filename
* @param fileName
*/
function getMimeType(fileName: string): string {
const lower = fileName.toLowerCase();
if (lower.endsWith(".md") || lower.endsWith(".markdown"))
return "text/markdown";
if (lower.endsWith(".txt")) return "text/plain";
if (lower.endsWith(".json")) return "application/json";
return "text/plain";
}
/**
* Read a file or return an error message if it fails
* @param path
*/
function readFileSafe(path: string): string {
try {
return readFileSync(path, "utf-8");
} catch (e) {
return `Error reading file: ${path}. ${e}`;
}
}
```
## /src/everything/resources/index.ts
```ts path="/src/everything/resources/index.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerResourceTemplates } from "./templates.js";
import { registerFileResources } from "./files.js";
import { fileURLToPath } from "url";
import { dirname, join } from "path";
import { readFileSync } from "fs";
/**
* Register the resources with the MCP server.
* @param server
*/
export const registerResources = (server: McpServer) => {
registerResourceTemplates(server);
registerFileResources(server);
};
/**
* Reads the server instructions from the corresponding markdown file.
* Attempts to load the content of the file located in the `docs` directory.
* If the file cannot be loaded, an error message is returned instead.
*
* @return {string} The content of the server instructions file, or an error message if reading fails.
*/
export function readInstructions(): string {
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const filePath = join(__dirname, "..", "docs", "instructions.md");
let instructions;
try {
instructions = readFileSync(filePath, "utf-8");
} catch (e) {
instructions = "Server instructions not loaded: " + e;
}
return instructions;
}
```
## /src/everything/resources/session.ts
```ts path="/src/everything/resources/session.ts"
import { McpServer, RegisteredResource } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Resource, ResourceLink } from "@modelcontextprotocol/sdk/types.js";
/**
* Tracks registered session resources by URI to allow updating/removing on re-registration.
* This prevents "Resource already registered" errors when a tool creates a resource
* with the same URI multiple times during a session.
*/
const registeredResources = new Map<string, RegisteredResource>();
/**
* Generates a session-scoped resource URI string based on the provided resource name.
*
* @param {string} name - The name of the resource to create a URI for.
* @returns {string} The formatted session resource URI.
*/
export const getSessionResourceURI = (name: string): string => {
return `demo://resource/session/${name}`;
};
/**
* Registers a session-scoped resource with the provided server and returns a resource link.
*
* The registered resource is available during the life of the session only; it is not otherwise persisted.
*
* @param {McpServer} server - The server instance responsible for handling the resource registration.
* @param {Resource} resource - The resource object containing metadata such as URI, name, description, and mimeType.
* @param {"text"|"blob"} type
* @param payload
* @returns {ResourceLink} An object representing the resource link, with associated metadata.
*/
export const registerSessionResource = (
server: McpServer,
resource: Resource,
type: "text" | "blob",
payload: string
): ResourceLink => {
// Destructure resource
const { uri, name, mimeType, description, title, annotations, icons, _meta } =
resource;
// Prepare the resource content to return
// See https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resource-contents
const resourceContent =
type === "text"
? {
uri: uri.toString(),
mimeType,
text: payload,
}
: {
uri: uri.toString(),
mimeType,
blob: payload,
};
// Check if a resource with this URI is already registered and remove it
const existingResource = registeredResources.get(uri);
if (existingResource) {
existingResource.remove();
registeredResources.delete(uri);
}
// Register file resource
const registeredResource = server.registerResource(
name,
uri,
{ mimeType, description, title, annotations, icons, _meta },
async () => {
return {
contents: [resourceContent],
};
}
);
// Track the registered resource for potential future removal
registeredResources.set(uri, registeredResource);
return { type: "resource_link", ...resource };
};
```
## /src/everything/resources/subscriptions.ts
```ts path="/src/everything/resources/subscriptions.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
SubscribeRequestSchema,
UnsubscribeRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// Track subscriber session id lists by URI
const subscriptions: Map<string, Set<string | undefined>> = new Map<
string,
Set<string | undefined>
>();
// Interval to send notifications to subscribers
const subsUpdateIntervals: Map<string | undefined, NodeJS.Timeout | undefined> =
new Map<string | undefined, NodeJS.Timeout | undefined>();
/**
* Sets up the subscription and unsubscription handlers for the provided server.
*
* The function defines two request handlers:
* 1. A `Subscribe` handler that allows clients to subscribe to specific resource URIs.
* 2. An `Unsubscribe` handler that allows clients to unsubscribe from specific resource URIs.
*
* The `Subscribe` handler performs the following actions:
* - Extracts the URI and session ID from the request.
* - Logs a message acknowledging the subscription request.
* - Updates the internal tracking of subscribers for the given URI.
*
* The `Unsubscribe` handler performs the following actions:
* - Extracts the URI and session ID from the request.
* - Logs a message acknowledging the unsubscription request.
* - Removes the subscriber for the specified URI.
*
* @param {McpServer} server - The server instance to which subscription handlers will be attached.
*/
export const setSubscriptionHandlers = (server: McpServer) => {
// Set the subscription handler
server.server.setRequestHandler(
SubscribeRequestSchema,
async (request, extra) => {
// Get the URI to subscribe to
const { uri } = request.params;
// Get the session id (can be undefined for stdio)
const sessionId = extra.sessionId as string;
// Acknowledge the subscribe request
await server.sendLoggingMessage(
{
level: "info",
data: `Received Subscribe Resource request for URI: ${uri} ${
sessionId ? `from session ${sessionId}` : ""
}`,
},
sessionId
);
// Get the subscribers for this URI
const subscribers = subscriptions.has(uri)
? (subscriptions.get(uri) as Set<string>)
: new Set<string>();
subscribers.add(sessionId);
subscriptions.set(uri, subscribers);
return {};
}
);
// Set the unsubscription handler
server.server.setRequestHandler(
UnsubscribeRequestSchema,
async (request, extra) => {
// Get the URI to subscribe to
const { uri } = request.params;
// Get the session id (can be undefined for stdio)
const sessionId = extra.sessionId as string;
// Acknowledge the subscribe request
await server.sendLoggingMessage(
{
level: "info",
data: `Received Unsubscribe Resource request: ${uri} ${
sessionId ? `from session ${sessionId}` : ""
}`,
},
sessionId
);
// Remove the subscriber
if (subscriptions.has(uri)) {
const subscribers = subscriptions.get(uri) as Set<string>;
if (subscribers.has(sessionId)) subscribers.delete(sessionId);
}
return {};
}
);
};
/**
* Sends simulated resource update notifications to the subscribed client.
*
* This function iterates through all resource URIs stored in the subscriptions
* and checks if the specified session ID is subscribed to them. If so, it sends
* a notification through the provided server. If the session ID is no longer valid
* (disconnected), it removes the session ID from the list of subscribers.
*
* @param {McpServer} server - The server instance used to send notifications.
* @param {string | undefined} sessionId - The session ID of the client to check for subscriptions.
* @returns {Promise<void>} Resolves once all applicable notifications are sent.
*/
const sendSimulatedResourceUpdates = async (
server: McpServer,
sessionId: string | undefined
): Promise<void> => {
// Search all URIs for ones this client is subscribed to
for (const uri of subscriptions.keys()) {
const subscribers = subscriptions.get(uri) as Set<string | undefined>;
// If this client is subscribed, send the notification
if (subscribers.has(sessionId)) {
await server.server.notification({
method: "notifications/resources/updated",
params: { uri },
});
} else {
subscribers.delete(sessionId); // subscriber has disconnected
}
}
};
/**
* Starts the process of simulating resource updates and sending server notifications
* to the client for the resources they are subscribed to. If the update interval is
* already active, invoking this function will not start another interval.
*
* @param server
* @param sessionId
*/
export const beginSimulatedResourceUpdates = (
server: McpServer,
sessionId: string | undefined
) => {
if (!subsUpdateIntervals.has(sessionId)) {
// Send once immediately
sendSimulatedResourceUpdates(server, sessionId);
// Set the interval to send later resource update notifications to this client
subsUpdateIntervals.set(
sessionId,
setInterval(() => sendSimulatedResourceUpdates(server, sessionId), 5000)
);
}
};
/**
* Stops simulated resource updates for a given session.
*
* This function halts any active intervals associated with the provided session ID
* and removes the session's corresponding entries from resource management collections.
* Session ID can be undefined for stdio.
*
* @param {string} [sessionId]
*/
export const stopSimulatedResourceUpdates = (sessionId?: string) => {
// Remove active intervals
if (subsUpdateIntervals.has(sessionId)) {
const subsUpdateInterval = subsUpdateIntervals.get(sessionId);
clearInterval(subsUpdateInterval);
subsUpdateIntervals.delete(sessionId);
}
};
```
## /src/everything/resources/templates.ts
```ts path="/src/everything/resources/templates.ts"
import { z } from "zod";
import {
CompleteResourceTemplateCallback,
McpServer,
ResourceTemplate,
} from "@modelcontextprotocol/sdk/server/mcp.js";
import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
// Resource types
export const RESOURCE_TYPE_TEXT = "Text" as const;
export const RESOURCE_TYPE_BLOB = "Blob" as const;
export const RESOURCE_TYPES: string[] = [
RESOURCE_TYPE_TEXT,
RESOURCE_TYPE_BLOB,
];
/**
* A completer function for resource types.
*
* This variable provides functionality to perform autocompletion for the resource types based on user input.
* It uses a schema description to validate the input and filters through a predefined list of resource types
* to return suggestions that start with the given input.
*
* The input value is expected to be a string representing the type of resource to fetch.
* The completion logic matches the input against available resource types.
*/
export const resourceTypeCompleter = completable(
z.string().describe("Type of resource to fetch"),
(value: string) => {
return RESOURCE_TYPES.filter((t) => t.startsWith(value));
}
);
/**
* A completer function for resource IDs as strings.
*
* The `resourceIdCompleter` accepts a string input representing the ID of a text resource
* and validates whether the provided value corresponds to an integer resource ID.
*
* NOTE: Currently, prompt arguments can only be strings since type is not field of `PromptArgument`
* Consequently, we must define it as a string and convert the argument to number before using it
* https://modelcontextprotocol.io/specification/2025-11-25/schema#promptargument
*
* If the value is a valid integer, it returns the value within an array.
* Otherwise, it returns an empty array.
*
* The input string is first transformed into a number and checked to ensure it is an integer.
* This helps validate and suggest appropriate resource IDs.
*/
export const resourceIdForPromptCompleter = completable(
z.string().describe("ID of the text resource to fetch"),
(value: string) => {
const resourceId = Number(value);
return Number.isInteger(resourceId) && resourceId > 0 ? [value] : [];
}
);
/**
* A callback function that acts as a completer for resource ID values, validating and returning
* the input value as part of a resource template.
*
* @typedef {CompleteResourceTemplateCallback}
* @param {string} value - The input string value to be evaluated as a resource ID.
* @returns {string[]} Returns an array containing the input value if it represents a positive
* integer resource ID, otherwise returns an empty array.
*/
export const resourceIdForResourceTemplateCompleter: CompleteResourceTemplateCallback =
(value: string) => {
const resourceId = Number(value);
return Number.isInteger(resourceId) && resourceId > 0 ? [value] : [];
};
const uriBase: string = "demo://resource/dynamic";
const textUriBase: string = `${uriBase}/text`;
const blobUriBase: string = `${uriBase}/blob`;
const textUriTemplate: string = `${textUriBase}/{resourceId}`;
const blobUriTemplate: string = `${blobUriBase}/{resourceId}`;
/**
* Create a dynamic text resource
* - Exposed for use by embedded resource prompt example
* @param uri
* @param resourceId
*/
export const textResource = (uri: URL, resourceId: number) => {
const timestamp = new Date().toLocaleTimeString();
return {
uri: uri.toString(),
mimeType: "text/plain",
text: `Resource ${resourceId}: This is a plaintext resource created at ${timestamp}`,
};
};
/**
* Create a dynamic blob resource
* - Exposed for use by embedded resource prompt example
* @param uri
* @param resourceId
*/
export const blobResource = (uri: URL, resourceId: number) => {
const timestamp = new Date().toLocaleTimeString();
const resourceText = Buffer.from(
`Resource ${resourceId}: This is a base64 blob created at ${timestamp}`
).toString("base64");
return {
uri: uri.toString(),
mimeType: "text/plain",
blob: resourceText,
};
};
/**
* Create a dynamic text resource URI
* - Exposed for use by embedded resource prompt example
* @param resourceId
*/
export const textResourceUri = (resourceId: number) =>
new URL(`${textUriBase}/${resourceId}`);
/**
* Create a dynamic blob resource URI
* - Exposed for use by embedded resource prompt example
* @param resourceId
*/
export const blobResourceUri = (resourceId: number) =>
new URL(`${blobUriBase}/${resourceId}`);
/**
* Parses the resource identifier from the provided URI and validates it
* against the given variables. Throws an error if the URI corresponds
* to an unknown resource or if the resource identifier is invalid.
*
* @param {URL} uri - The URI of the resource to be parsed.
* @param {Record<string, unknown>} variables - A record containing context-specific variables that include the resourceId.
* @returns {number} The parsed and validated resource identifier as an integer.
* @throws {Error} Throws an error if the URI matches unsupported base URIs or if the resourceId is invalid.
*/
const parseResourceId = (uri: URL, variables: Record<string, unknown>) => {
const uriError = `Unknown resource: ${uri.toString()}`;
if (
uri.toString().startsWith(textUriBase) &&
uri.toString().startsWith(blobUriBase)
) {
throw new Error(uriError);
} else {
const idxStr = String((variables as any).resourceId ?? "");
const idx = Number(idxStr);
if (Number.isFinite(idx) && Number.isInteger(idx) && idx > 0) {
return idx;
} else {
throw new Error(uriError);
}
}
};
/**
* Register resource templates with the MCP server.
* - Text and blob resources, dynamically generated from the URI {resourceId} variable
* - Any finite positive integer is acceptable for the resourceId variable
* - List resources method will not return these resources
* - These are only accessible via template URIs
* - Both blob and text resources:
* - have content that is dynamically generated, including a timestamp
* - have different template URIs
* - Blob: "demo://resource/dynamic/blob/{resourceId}"
* - Text: "demo://resource/dynamic/text/{resourceId}"
*
* @param server
*/
export const registerResourceTemplates = (server: McpServer) => {
// Register the text resource template
server.registerResource(
"Dynamic Text Resource",
new ResourceTemplate(textUriTemplate, {
list: undefined,
complete: { resourceId: resourceIdForResourceTemplateCompleter },
}),
{
mimeType: "text/plain",
description:
"Plaintext dynamic resource fabricated from the {resourceId} variable, which must be an integer.",
},
async (uri, variables) => {
const resourceId = parseResourceId(uri, variables);
return {
contents: [textResource(uri, resourceId)],
};
}
);
// Register the blob resource template
server.registerResource(
"Dynamic Blob Resource",
new ResourceTemplate(blobUriTemplate, {
list: undefined,
complete: { resourceId: resourceIdForResourceTemplateCompleter },
}),
{
mimeType: "application/octet-stream",
description:
"Binary (base64) dynamic resource fabricated from the {resourceId} variable, which must be an integer.",
},
async (uri, variables) => {
const resourceId = parseResourceId(uri, variables);
return {
contents: [blobResource(uri, resourceId)],
};
}
);
};
```
## /src/everything/server/index.ts
```ts path="/src/everything/server/index.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
InMemoryTaskStore,
InMemoryTaskMessageQueue,
} from "@modelcontextprotocol/sdk/experimental/tasks";
import {
setSubscriptionHandlers,
stopSimulatedResourceUpdates,
} from "../resources/subscriptions.js";
import { registerConditionalTools, registerTools } from "../tools/index.js";
import { registerResources, readInstructions } from "../resources/index.js";
import { registerPrompts } from "../prompts/index.js";
import { stopSimulatedLogging } from "./logging.js";
import { syncRoots } from "./roots.js";
// Server Factory response
export type ServerFactoryResponse = {
server: McpServer;
cleanup: (sessionId?: string) => void;
};
/**
* Server Factory
*
* This function initializes a `McpServer` with specific capabilities and instructions,
* registers tools, resources, and prompts, and configures resource subscription handlers.
*
* @returns {ServerFactoryResponse} An object containing the server instance, and a `cleanup`
* function for handling server-side cleanup when a session ends.
*
* Properties of the returned object:
* - `server` {Object}: The initialized server instance.
* - `cleanup` {Function}: Function to perform cleanup operations for a closing session.
*/
export const createServer: () => ServerFactoryResponse = () => {
// Read the server instructions
const instructions = readInstructions();
// Create task store and message queue for task support
const taskStore = new InMemoryTaskStore();
const taskMessageQueue = new InMemoryTaskMessageQueue();
let initializeTimeout: NodeJS.Timeout | null = null;
// Create the server
const server = new McpServer(
{
name: "mcp-servers/everything",
title: "Everything Reference Server",
version: "2.0.0",
},
{
capabilities: {
tools: {
listChanged: true,
},
prompts: {
listChanged: true,
},
resources: {
subscribe: true,
listChanged: true,
},
logging: {},
tasks: {
list: {},
cancel: {},
requests: {
tools: {
call: {},
},
},
},
},
instructions,
taskStore,
taskMessageQueue,
}
);
// Register the tools
registerTools(server);
// Register the resources
registerResources(server);
// Register the prompts
registerPrompts(server);
// Set resource subscription handlers
setSubscriptionHandlers(server);
// Perform post-initialization operations
server.server.oninitialized = async () => {
// Register conditional tools now that client capabilities are known.
// This finishes before the `notifications/initialized` handler finishes.
registerConditionalTools(server);
// Sync roots if the client supports them.
// This is delayed until after the `notifications/initialized` handler finishes,
// otherwise, the request gets lost.
const sessionId = server.server.transport?.sessionId;
initializeTimeout = setTimeout(() => syncRoots(server, sessionId), 350);
};
// Return the ServerFactoryResponse
return {
server,
cleanup: (sessionId?: string) => {
// Stop any simulated logging or resource updates that may have been initiated.
stopSimulatedLogging(sessionId);
stopSimulatedResourceUpdates(sessionId);
// Clean up task store timers
taskStore.cleanup();
if (initializeTimeout) clearTimeout(initializeTimeout);
},
} satisfies ServerFactoryResponse;
};
```
## /src/everything/server/logging.ts
```ts path="/src/everything/server/logging.ts"
import { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
// Map session ID to the interval for sending logging messages to the client
const logsUpdateIntervals: Map<string | undefined, NodeJS.Timeout | undefined> =
new Map<string | undefined, NodeJS.Timeout | undefined>();
/**
* Initiates a simulated logging process by sending random log messages to the client at a
* fixed interval. Each log message contains a random logging level and optional session ID.
*
* @param {McpServer} server - The server instance responsible for handling the logging messages.
* @param {string | undefined} sessionId - An optional identifier for the session. If provided,
* the session ID will be appended to log messages.
*/
export const beginSimulatedLogging = (
server: McpServer,
sessionId: string | undefined
) => {
const maybeAppendSessionId = sessionId ? ` - SessionId ${sessionId}` : "";
const messages: { level: LoggingLevel; data: string }[] = [
{ level: "debug", data: `Debug-level message${maybeAppendSessionId}` },
{ level: "info", data: `Info-level message${maybeAppendSessionId}` },
{ level: "notice", data: `Notice-level message${maybeAppendSessionId}` },
{
level: "warning",
data: `Warning-level message${maybeAppendSessionId}`,
},
{ level: "error", data: `Error-level message${maybeAppendSessionId}` },
{
level: "critical",
data: `Critical-level message${maybeAppendSessionId}`,
},
{ level: "alert", data: `Alert level-message${maybeAppendSessionId}` },
{
level: "emergency",
data: `Emergency-level message${maybeAppendSessionId}`,
},
];
/**
* Send a simulated logging message to the client
*/
const sendSimulatedLoggingMessage = async (sessionId: string | undefined) => {
// By using the `sendLoggingMessage` function to send the message, we
// ensure that the client's chosen logging level will be respected
await server.sendLoggingMessage(
messages[Math.floor(Math.random() * messages.length)],
sessionId
);
};
// Set the interval to send later logging messages to this client
if (!logsUpdateIntervals.has(sessionId)) {
// Send once immediately
sendSimulatedLoggingMessage(sessionId);
// Send a randomly-leveled log message every 5 seconds
logsUpdateIntervals.set(
sessionId,
setInterval(() => sendSimulatedLoggingMessage(sessionId), 5000)
);
}
};
/**
* Stops the simulated logging process for a given session.
*
* This function halts the periodic logging updates associated with the specified
* session ID by clearing the interval and removing the session's tracking
* reference. Session ID can be undefined for stdio.
*
* @param {string} [sessionId] - The optional unique identifier of the session.
*/
export const stopSimulatedLogging = (sessionId?: string) => {
// Remove active intervals
if (logsUpdateIntervals.has(sessionId)) {
const logsUpdateInterval = logsUpdateIntervals.get(sessionId);
clearInterval(logsUpdateInterval);
logsUpdateIntervals.delete(sessionId);
}
};
```
## /src/everything/server/roots.ts
```ts path="/src/everything/server/roots.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
Root,
RootsListChangedNotificationSchema,
} from "@modelcontextprotocol/sdk/types.js";
// Track roots by session id
export const roots: Map<string | undefined, Root[]> = new Map<
string | undefined,
Root[]
>();
/**
* Get the latest the client roots list for the session.
*
* - Request and cache the roots list for the session if it has not been fetched before.
* - Return the cached roots list for the session if it exists.
*
* When requesting the roots list for a session, it also sets up a `roots/list_changed`
* notification handler. This ensures that updates are automatically fetched and handled
* in real-time.
*
* This function is idempotent. It should only request roots from the client once per session,
* returning the cached version thereafter.
*
* @param {McpServer} server - An instance of the MCP server used to communicate with the client.
* @param {string} [sessionId] - An optional session id used to associate the roots list with a specific client session.
*
* @throws {Error} In case of a failure to request the roots from the client, an error log message is sent.
*/
export const syncRoots = async (server: McpServer, sessionId?: string) => {
const clientCapabilities = server.server.getClientCapabilities() || {};
const clientSupportsRoots: boolean = clientCapabilities?.roots !== undefined;
// Fetch the roots list for this client
if (clientSupportsRoots) {
// Function to request the updated roots list from the client
const requestRoots = async () => {
try {
// Request the updated roots list from the client
const response = await server.server.listRoots();
if (response && "roots" in response) {
// Store the roots list for this client
roots.set(sessionId, response.roots);
// Notify the client of roots received
await server.sendLoggingMessage(
{
level: "info",
logger: "everything-server",
data: `Roots updated: ${response?.roots?.length} root(s) received from client`,
},
sessionId
);
} else {
await server.sendLoggingMessage(
{
level: "info",
logger: "everything-server",
data: "Client returned no roots set",
},
sessionId
);
}
} catch (error) {
console.error(
`Failed to request roots from client ${sessionId}: ${
error instanceof Error ? error.message : String(error)
}`
);
}
};
// If the roots have not been synced for this client,
// set notification handler and request initial roots
if (!roots.has(sessionId)) {
// Set the list changed notification handler
server.server.setNotificationHandler(
RootsListChangedNotificationSchema,
requestRoots
);
// Request the initial roots list immediately
await requestRoots();
}
// Return the roots list for this client
return roots.get(sessionId);
}
};
```
## /src/everything/tools/echo.ts
```ts path="/src/everything/tools/echo.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
// Tool input schema
export const EchoSchema = z.object({
message: z.string().describe("Message to echo"),
});
// Tool configuration
const name = "echo";
const config = {
title: "Echo Tool",
description: "Echoes back the input string",
inputSchema: EchoSchema,
};
/**
* Registers the 'echo' tool.
*
* The registered tool validates input arguments using the EchoSchema and
* returns a response that echoes the message provided in the arguments.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
* @returns {void}
*/
export const registerEchoTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
const validatedArgs = EchoSchema.parse(args);
return {
content: [{ type: "text", text: `Echo: ${validatedArgs.message}` }],
};
});
};
```
## /src/everything/tools/get-annotated-message.ts
```ts path="/src/everything/tools/get-annotated-message.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import { MCP_TINY_IMAGE } from "./get-tiny-image.js";
// Tool input schema
const GetAnnotatedMessageSchema = z.object({
messageType: z
.enum(["error", "success", "debug"])
.describe("Type of message to demonstrate different annotation patterns"),
includeImage: z
.boolean()
.default(false)
.describe("Whether to include an example image"),
});
// Tool configuration
const name = "get-annotated-message";
const config = {
title: "Get Annotated Message Tool",
description:
"Demonstrates how annotations can be used to provide metadata about content.",
inputSchema: GetAnnotatedMessageSchema,
};
/**
* Registers the 'get-annotated-message' tool.
*
* The registered tool generates and sends messages with specific types, such as error,
* success, or debug, carrying associated annotations like priority level and intended
* audience.
*
* The response will have annotations and optionally contain an annotated image.
*
* @function
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerGetAnnotatedMessageTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
const { messageType, includeImage } = GetAnnotatedMessageSchema.parse(args);
const content: CallToolResult["content"] = [];
// Main message with different priorities/audiences based on type
if (messageType === "error") {
content.push({
type: "text",
text: "Error: Operation failed",
annotations: {
priority: 1.0, // Errors are highest priority
audience: ["user", "assistant"], // Both need to know about errors
},
});
} else if (messageType === "success") {
content.push({
type: "text",
text: "Operation completed successfully",
annotations: {
priority: 0.7, // Success messages are important but not critical
audience: ["user"], // Success mainly for user consumption
},
});
} else if (messageType === "debug") {
content.push({
type: "text",
text: "Debug: Cache hit ratio 0.95, latency 150ms",
annotations: {
priority: 0.3, // Debug info is low priority
audience: ["assistant"], // Technical details for assistant
},
});
}
// Optional image with its own annotations
if (includeImage) {
content.push({
type: "image",
data: MCP_TINY_IMAGE,
mimeType: "image/png",
annotations: {
priority: 0.5,
audience: ["user"], // Images primarily for user visualization
},
});
}
return { content };
});
};
```
## /src/everything/tools/get-env.ts
```ts path="/src/everything/tools/get-env.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
// Tool configuration
const name = "get-env";
const config = {
title: "Print Environment Tool",
description:
"Returns all environment variables, helpful for debugging MCP server configuration",
inputSchema: {},
};
/**
* Registers the 'get-env' tool.
*
* The registered tool Retrieves and returns the environment variables
* of the current process as a JSON-formatted string encapsulated in a text response.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
* @returns {void}
*/
export const registerGetEnvTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
return {
content: [
{
type: "text",
text: JSON.stringify(process.env, null, 2),
},
],
};
});
};
```
## /src/everything/tools/get-resource-links.ts
```ts path="/src/everything/tools/get-resource-links.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import {
textResource,
textResourceUri,
blobResourceUri,
blobResource,
} from "../resources/templates.js";
// Tool input schema
const GetResourceLinksSchema = z.object({
count: z
.number()
.min(1)
.max(10)
.default(3)
.describe("Number of resource links to return (1-10)"),
});
// Tool configuration
const name = "get-resource-links";
const config = {
title: "Get Resource Links Tool",
description:
"Returns up to ten resource links that reference different types of resources",
inputSchema: GetResourceLinksSchema,
};
/**
* Registers the 'get-resource-reference' tool.
*
* The registered tool retrieves a specified number of resource links and their metadata.
* Resource links are dynamically generated as either text or binary blob resources,
* based on their ID being even or odd.
* The response contains a "text" introductory block and multiple "resource_link" blocks.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerGetResourceLinksTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
const { count } = GetResourceLinksSchema.parse(args);
// Add intro text content block
const content: CallToolResult["content"] = [];
content.push({
type: "text",
text: `Here are ${count} resource links to resources available in this server:`,
});
// Create resource link content blocks
for (let resourceId = 1; resourceId <= count; resourceId++) {
// Get resource uri for text or blob resource based on odd/even resourceId
const isOdd = resourceId % 2 === 0;
const uri = isOdd
? textResourceUri(resourceId)
: blobResourceUri(resourceId);
// Get resource based on the resource type
const resource = isOdd
? textResource(uri, resourceId)
: blobResource(uri, resourceId);
content.push({
type: "resource_link",
uri: resource.uri,
name: `${isOdd ? "Text" : "Blob"} Resource ${resourceId}`,
description: `Resource ${resourceId}: ${
resource.mimeType === "text/plain"
? "plaintext resource"
: "binary blob resource"
}`,
mimeType: resource.mimeType,
});
}
return { content };
});
};
```
## /src/everything/tools/get-resource-reference.ts
```ts path="/src/everything/tools/get-resource-reference.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import {
textResource,
textResourceUri,
blobResourceUri,
blobResource,
RESOURCE_TYPE_BLOB,
RESOURCE_TYPE_TEXT,
RESOURCE_TYPES,
} from "../resources/templates.js";
// Tool input schema
const GetResourceReferenceSchema = z.object({
resourceType: z
.enum([RESOURCE_TYPE_TEXT, RESOURCE_TYPE_BLOB])
.default(RESOURCE_TYPE_TEXT),
resourceId: z
.number()
.default(1)
.describe("ID of the text resource to fetch"),
});
// Tool configuration
const name = "get-resource-reference";
const config = {
title: "Get Resource Reference Tool",
description: "Returns a resource reference that can be used by MCP clients",
inputSchema: GetResourceReferenceSchema,
};
/**
* Registers the 'get-resource-reference' tool.
*
* The registered tool validates and processes arguments for retrieving a resource
* reference. Supported resource types include predefined `RESOURCE_TYPE_TEXT` and
* `RESOURCE_TYPE_BLOB`. The retrieved resource's reference will include the resource
* ID, type, and its associated URI.
*
* The tool performs the following operations:
* 1. Validates the `resourceType` argument to ensure it matches a supported type.
* 2. Validates the `resourceId` argument to ensure it is a finite positive integer.
* 3. Constructs a URI for the resource based on its type (text or blob).
* 4. Retrieves the resource and returns it in a content block.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerGetResourceReferenceTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
// Validate resource type argument
const { resourceType } = args;
if (!RESOURCE_TYPES.includes(resourceType)) {
throw new Error(
`Invalid resourceType: ${args?.resourceType}. Must be ${RESOURCE_TYPE_TEXT} or ${RESOURCE_TYPE_BLOB}.`
);
}
// Validate resourceId argument
const resourceId = Number(args?.resourceId);
if (
!Number.isFinite(resourceId) ||
!Number.isInteger(resourceId) ||
resourceId < 1
) {
throw new Error(
`Invalid resourceId: ${args?.resourceId}. Must be a finite positive integer.`
);
}
// Get resource based on the resource type
const uri =
resourceType === RESOURCE_TYPE_TEXT
? textResourceUri(resourceId)
: blobResourceUri(resourceId);
const resource =
resourceType === RESOURCE_TYPE_TEXT
? textResource(uri, resourceId)
: blobResource(uri, resourceId);
return {
content: [
{
type: "text",
text: `Returning resource reference for Resource ${resourceId}:`,
},
{
type: "resource",
resource: resource,
},
{
type: "text",
text: `You can access this resource using the URI: ${resource.uri}`,
},
],
};
});
};
```
## /src/everything/tools/get-roots-list.ts
```ts path="/src/everything/tools/get-roots-list.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { syncRoots } from "../server/roots.js";
// Tool configuration
const name = "get-roots-list";
const config = {
title: "Get Roots List Tool",
description:
"Lists the current MCP roots provided by the client. Demonstrates the roots protocol capability even though this server doesn't access files.",
inputSchema: {},
};
/**
* Registers the 'get-roots-list' tool.
*
* If the client does not support the roots capability, the tool is not registered.
*
* The registered tool interacts with the MCP roots capability, which enables the server to access
* information about the client's workspace directories or file system roots.
*
* When supported, the server automatically retrieves and formats the current list of roots from the
* client upon connection and whenever the client sends a `roots/list_changed` notification.
*
* Therefore, this tool displays the roots that the server currently knows about for the connected
* client. If for some reason the server never got the initial roots list, the tool will request the
* list from the client again.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerGetRootsListTool = (server: McpServer) => {
// Does client support roots?
const clientCapabilities = server.server.getClientCapabilities() || {};
const clientSupportsRoots: boolean = clientCapabilities.roots !== undefined;
// If so, register tool
if (clientSupportsRoots) {
server.registerTool(
name,
config,
async (args, extra): Promise<CallToolResult> => {
// Get the current rootsFetch the current roots list from the client if need be
const currentRoots = await syncRoots(server, extra.sessionId);
// Respond if client supports roots but doesn't have any configured
if (
clientSupportsRoots &&
(!currentRoots || currentRoots.length === 0)
) {
return {
content: [
{
type: "text",
text:
"The client supports roots but no roots are currently configured.\n\n" +
"This could mean:\n" +
"1. The client hasn't provided any roots yet\n" +
"2. The client provided an empty roots list\n" +
"3. The roots configuration is still being loaded",
},
],
};
}
// Create formatted response if there is a list of roots
const rootsList = currentRoots
? currentRoots
.map((root, index) => {
return `${index + 1}. ${root.name || "Unnamed Root"}\n URI: ${
root.uri
}`;
})
.join("\n\n")
: "No roots found";
return {
content: [
{
type: "text",
text:
`Current MCP Roots (${
currentRoots!.length
} total):\n\n${rootsList}\n\n` +
"Note: This server demonstrates the roots protocol capability but doesn't actually access files. " +
"The roots are provided by the MCP client and can be used by servers that need file system access.",
},
],
};
}
);
}
};
```
## /src/everything/tools/get-structured-content.ts
```ts path="/src/everything/tools/get-structured-content.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
CallToolResult,
ContentBlock,
} from "@modelcontextprotocol/sdk/types.js";
// Tool input schema
const GetStructuredContentInputSchema = {
location: z
.enum(["New York", "Chicago", "Los Angeles"])
.describe("Choose city"),
};
// Tool output schema
const GetStructuredContentOutputSchema = z.object({
temperature: z.number().describe("Temperature in celsius"),
conditions: z.string().describe("Weather conditions description"),
humidity: z.number().describe("Humidity percentage"),
});
// Tool configuration
const name = "get-structured-content";
const config = {
title: "Get Structured Content Tool",
description:
"Returns structured content along with an output schema for client data validation",
inputSchema: GetStructuredContentInputSchema,
outputSchema: GetStructuredContentOutputSchema,
};
/**
* Registers the 'get-structured-content' tool.
*
* The registered tool processes incoming arguments using a predefined input schema,
* generates structured content with weather information including temperature,
* conditions, and humidity, and returns both backward-compatible content blocks
* and structured content in the response.
*
* The response contains:
* - `content`: An array of content blocks, presented as JSON stringified objects.
* - `structuredContent`: A JSON structured representation of the weather data.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerGetStructuredContentTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
// Get simulated weather for the chosen city
let weather;
switch (args.location) {
case "New York":
weather = {
temperature: 33,
conditions: "Cloudy",
humidity: 82,
};
break;
case "Chicago":
weather = {
temperature: 36,
conditions: "Light rain / drizzle",
humidity: 82,
};
break;
case "Los Angeles":
weather = {
temperature: 73,
conditions: "Sunny / Clear",
humidity: 48,
};
break;
}
const backwardCompatibleContentBlock: ContentBlock = {
type: "text",
text: JSON.stringify(weather),
};
return {
content: [backwardCompatibleContentBlock],
structuredContent: weather,
};
});
};
```
## /src/everything/tools/get-sum.ts
```ts path="/src/everything/tools/get-sum.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
// Tool input schema
const GetSumSchema = z.object({
a: z.number().describe("First number"),
b: z.number().describe("Second number"),
});
// Tool configuration
const name = "get-sum";
const config = {
title: "Get Sum Tool",
description: "Returns the sum of two numbers",
inputSchema: GetSumSchema,
};
/**
* Registers the 'get-sum' tool.
**
* The registered tool processes input arguments, validates them using a predefined schema,
* calculates the sum of two numeric values, and returns the result in a content block.
*
* Expects input arguments to conform to a specific schema that includes two numeric properties, `a` and `b`.
* Validation is performed to ensure the input adheres to the expected structure before calculating the sum.
*
* The result is returned as a Promise resolving to an object containing the computed sum in a text format.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerGetSumTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
const validatedArgs = GetSumSchema.parse(args);
const sum = validatedArgs.a + validatedArgs.b;
return {
content: [
{
type: "text",
text: `The sum of ${validatedArgs.a} and ${validatedArgs.b} is ${sum}.`,
},
],
};
});
};
```
## /src/everything/tools/get-tiny-image.ts
```ts path="/src/everything/tools/get-tiny-image.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
// A tiny encoded MCP logo image
export const MCP_TINY_IMAGE =
"iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAKsGlDQ1BJQ0MgUHJvZmlsZQAASImVlwdUU+kSgOfe9JDQEiIgJfQmSCeAlBBaAAXpYCMkAUKJMRBU7MriClZURLCs6KqIgo0idizYFsWC3QVZBNR1sWDDlXeBQ9jdd9575805c+a7c+efmf+e/z9nLgCdKZDJMlF1gCxpjjwyyI8dn5DIJvUABRiY0kBdIMyWcSMiwgCTUft3+dgGyJC9YzuU69/f/1fREImzhQBIBMbJomxhFsbHMe0TyuQ5ALg9mN9kbo5siK9gzJRjDWL8ZIhTR7hviJOHGY8fjomO5GGsDUCmCQTyVACaKeZn5wpTsTw0f4ztpSKJFGPsGbyzsmaLMMbqgiUWI8N4KD8n+S95Uv+WM1mZUyBIVfLIXoaF7C/JlmUK5v+fn+N/S1amYrSGOaa0NHlwJGaxvpAHGbNDlSxNnhI+yhLRcPwwpymCY0ZZmM1LHGWRwD9UuTZzStgop0gC+co8OfzoURZnB0SNsnx2pLJWipzHHWWBfKyuIiNG6U8T85X589Ki40Y5VxI7ZZSzM6JCx2J4Sr9cEansXywN8hurG6jce1b2X/Yr4SvX5qRFByv3LhjrXyzljuXMjlf2JhL7B4zFxCjjZTl+ylqyzAhlvDgzSOnPzo1Srs3BDuTY2gjlN0wXhESMMoRBELAhBjIhB+QggECQgBTEOeJ5Q2cUeLNl8+WS1LQcNhe7ZWI2Xyq0m8B2tHd0Bhi6syNH4j1r+C4irGtjvhWVAF4nBgcHT475Qm4BHEkCoNaO+SxnAKh3A1w5JVTIc0d8Q9cJCEAFNWCCDhiACViCLTiCK3iCLwRACIRDNCTATBBCGmRhnc+FhbAMCqAI1sNmKIOdsBv2wyE4CvVwCs7DZbgOt+AePIZ26IJX0AcfYQBBEBJCRxiIDmKImCE2iCPCQbyRACQMiUQSkCQkFZEiCmQhsgIpQoqRMmQXUokcQU4g55GrSCvyEOlAepF3yFcUh9JQJqqPmqMTUQ7KRUPRaHQGmorOQfPQfHQtWopWoAfROvQ8eh29h7ajr9B+HOBUcCycEc4Wx8HxcOG4RFwKTo5bjCvEleAqcNW4Rlwz7g6uHfca9wVPxDPwbLwt3hMfjI/BC/Fz8Ivxq/Fl+P34OvxF/B18B74P/51AJ+gRbAgeBD4hnpBKmEsoIJQQ9hJqCZcI9whdhI9EIpFFtCC6EYOJCcR04gLiauJ2Yg3xHLGV2EnsJ5FIOiQbkhcpnCQg5ZAKSFtJB0lnSbdJXaTPZBWyIdmRHEhOJEvJy8kl5APkM+Tb5G7yAEWdYkbxoIRTRJT5lHWUPZRGyk1KF2WAqkG1oHpRo6np1GXUUmo19RL1CfW9ioqKsYq7ylQVicpSlVKVwypXVDpUvtA0adY0Hm06TUFbS9tHO0d7SHtPp9PN6b70RHoOfS29kn6B/oz+WZWhaqfKVxWpLlEtV61Tva36Ro2iZqbGVZuplqdWonZM7abaa3WKurk6T12gvli9XP2E+n31fg2GhoNGuEaWxmqNAxpXNXo0SZrmmgGaIs18zd2aFzQ7GTiGCYPHEDJWMPYwLjG6mESmBZPPTGcWMQ8xW5h9WppazlqxWvO0yrVOa7WzcCxzFp+VyVrHOspqY30dpz+OO048btW46nG3x33SHq/tqy3WLtSu0b6n/VWHrROgk6GzQade56kuXtdad6ruXN0dupd0X49njvccLxxfOP7o+Ed6qJ61XqTeAr3dejf0+vUN9IP0Zfpb9S/ovzZgGfgapBtsMjhj0GvIMPQ2lBhuMjxr+JKtxeayM9ml7IvsPiM9o2AjhdEuoxajAWML4xjj5cY1xk9NqCYckxSTTSZNJn2mhqaTTReaVpk+MqOYcczSzLaYNZt9MrcwjzNfaV5v3mOhbcG3yLOosnhiSbf0sZxjWWF514poxbHKsNpudcsatXaxTrMut75pg9q42khsttu0TiBMcJ8gnVAx4b4tzZZrm2tbZdthx7ILs1tuV2/3ZqLpxMSJGyY2T/xu72Kfab/H/rGDpkOIw3KHRod3jtaOQsdyx7tOdKdApyVODU5vnW2cxc47nB+4MFwmu6x0aXL509XNVe5a7drrZuqW5LbN7T6HyYngrOZccSe4+7kvcT/l/sXD1SPH46jHH562nhmeBzx7JllMEk/aM6nTy9hL4LXLq92b7Z3k/ZN3u4+Rj8Cnwue5r4mvyHevbzfXipvOPch942fvJ/er9fvE8+At4p3zx/kH+Rf6twRoBsQElAU8CzQOTA2sCuwLcglaEHQumBAcGrwh+D5fny/kV/L7QtxCFoVcDKWFRoWWhT4Psw6ThzVORieHTN44+ckUsynSKfXhEM4P3xj+NMIiYk7EyanEqRFTy6e+iHSIXBjZHMWImhV1IOpjtF/0uujHMZYxipimWLXY6bGVsZ/i/OOK49rjJ8Yvir+eoJsgSWhIJCXGJu5N7J8WMG3ztK7pLtMLprfNsJgxb8bVmbozM2eenqU2SzDrWBIhKS7pQNI3QbigQtCfzE/eltwn5Am3CF+JfEWbRL1iL3GxuDvFK6U4pSfVK3Vjam+aT1pJ2msJT1ImeZsenL4z/VNGeMa+jMHMuMyaLHJWUtYJqaY0Q3pxtsHsebNbZTayAln7HI85m+f0yUPle7OR7BnZDTlMbDi6obBU/KDoyPXOLc/9PDd27rF5GvOk827Mt56/an53XmDezwvwC4QLmhYaLVy2sGMRd9Guxcji5MVNS0yW5C/pWhq0dP8y6rKMZb8st19evPzDirgVjfn6+UvzO38I+qGqQLVAXnB/pefKnT/if5T82LLKadXWVd8LRYXXiuyLSoq+rRauvrbGYU3pmsG1KWtb1rmu27GeuF66vm2Dz4b9xRrFecWdGydvrNvE3lS46cPmWZuvljiX7NxC3aLY0l4aVtqw1XTr+q3fytLK7pX7ldds09u2atun7aLtt3f47qjeqb+zaOfXnyQ/PdgVtKuuwryiZDdxd+7uF3ti9zT/zPm5cq/u3qK9f+6T7mvfH7n/YqVbZeUBvQPrqtAqRVXvwekHbx3yP9RQbVu9q4ZVU3QYDisOvzySdKTtaOjRpmOcY9XHzY5vq2XUFtYhdfPr+urT6tsbEhpaT4ScaGr0bKw9aXdy3ymjU+WntU6vO0M9k39m8Gze2f5zsnOvz6ee72ya1fT4QvyFuxenXmy5FHrpyuXAyxeauc1nr3hdOXXV4+qJa5xr9dddr9fdcLlR+4vLL7Utri11N91uNtzyv9XYOqn1zG2f2+fv+N+5fJd/9/q9Kfda22LaHtyffr/9gehBz8PMh28f5T4aeLz0CeFJ4VP1pyXP9J5V/Gr1a027a/vpDv+OG8+jnj/uFHa++i37t29d+S/oL0q6Dbsrexx7TvUG9t56Oe1l1yvZq4HXBb9r/L7tjeWb43/4/nGjL76v66387eC71e913u/74PyhqT+i/9nHrI8Dnwo/63ze/4Xzpflr3NfugbnfSN9K/7T6s/F76Pcng1mDgzKBXDA8CuAwRVNSAN7tA6AnADCwGYI6bWSmHhZk5D9gmOA/8cjcPSyuANWYGRqNeOcADmNqvhRAzRdgaCyK9gXUyUmpo/Pv8Kw+JAbYv8K0HECi2x6tebQU/iEjc/xf+v6nBWXWv9l/AV0EC6JTIblRAAAAeGVYSWZNTQAqAAAACAAFARIAAwAAAAEAAQAAARoABQAAAAEAAABKARsABQAAAAEAAABSASgAAwAAAAEAAgAAh2kABAAAAAEAAABaAAAAAAAAAJAAAAABAAAAkAAAAAEAAqACAAQAAAABAAAAFKADAAQAAAABAAAAFAAAAAAXNii1AAAACXBIWXMAABYlAAAWJQFJUiTwAAAB82lUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNi4wLjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyI+CiAgICAgICAgIDx0aWZmOllSZXNvbHV0aW9uPjE0NDwvdGlmZjpZUmVzb2x1dGlvbj4KICAgICAgICAgPHRpZmY6T3JpZW50YXRpb24+MTwvdGlmZjpPcmllbnRhdGlvbj4KICAgICAgICAgPHRpZmY6WFJlc29sdXRpb24+MTQ0PC90aWZmOlhSZXNvbHV0aW9uPgogICAgICAgICA8dGlmZjpSZXNvbHV0aW9uVW5pdD4yPC90aWZmOlJlc29sdXRpb25Vbml0PgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KReh49gAAAjRJREFUOBGFlD2vMUEUx2clvoNCcW8hCqFAo1dKhEQpvsF9KrWEBh/ALbQ0KkInBI3SWyGPCCJEQliXgsTLefaca/bBWjvJzs6cOf/fnDkzOQJIjWm06/XKBEGgD8c6nU5VIWgBtQDPZPWtJE8O63a7LBgMMo/Hw0ql0jPjcY4RvmqXy4XMjUYDUwLtdhtmsxnYbDbI5/O0djqdFFKmsEiGZ9jP9gem0yn0ej2Yz+fg9XpfycimAD7DttstQTDKfr8Po9GIIg6Hw1Cr1RTgB+A72GAwgMPhQLBMJgNSXsFqtUI2myUo18pA6QJogefsPrLBX4QdCVatViklw+EQRFGEj88P2O12pEUGATmsXq+TaLPZ0AXgMRF2vMEqlQoJTSYTpNNpApvNZliv1/+BHDaZTAi2Wq1A3Ig0xmMej7+RcZjdbodUKkWAaDQK+GHjHPnImB88JrZIJAKFQgH2+z2BOczhcMiwRCIBgUAA+NN5BP6mj2DYff35gk6nA61WCzBn2JxO5wPM7/fLz4vD0E+OECfn8xl/0Gw2KbLxeAyLxQIsFgt8p75pDSO7h/HbpUWpewCike9WLpfB7XaDy+WCYrFI/slk8i0MnRRAUt46hPMI4vE4+Hw+ec7t9/44VgWigEeby+UgFArJWjUYOqhWG6x50rpcSfR6PVUfNOgEVRlTX0HhrZBKz4MZjUYWi8VoA+lc9H/VaRZYjBKrtXR8tlwumcFgeMWRbZpA9ORQWfVm8A/FsrLaxebd5wAAAABJRU5ErkJggg==";
// Tool configuration
const name = "get-tiny-image";
const config = {
title: "Get Tiny Image Tool",
description: "Returns a tiny MCP logo image.",
inputSchema: {},
};
/**
* Registers the "get-tiny-image" tool.
*
* The registered tool returns a response containing a small image alongside some
* descriptive text.
*
* The response structure includes textual content before and after the image.
* The image is served as a PNG data type and represents the default MCP tiny image.
*
* @param server - The McpServer instance where the tool will be registered.
*/
export const registerGetTinyImageTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
return {
content: [
{
type: "text",
text: "Here's the image you requested:",
},
{
type: "image",
data: MCP_TINY_IMAGE,
mimeType: "image/png",
},
{
type: "text",
text: "The image above is the MCP logo.",
},
],
};
});
};
```
## /src/everything/tools/gzip-file-as-resource.ts
```ts path="/src/everything/tools/gzip-file-as-resource.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult, Resource } from "@modelcontextprotocol/sdk/types.js";
import { gzipSync } from "node:zlib";
import {
getSessionResourceURI,
registerSessionResource,
} from "../resources/session.js";
// Maximum input file size - 10 MB default
const GZIP_MAX_FETCH_SIZE = Number(
process.env.GZIP_MAX_FETCH_SIZE ?? String(10 * 1024 * 1024)
);
// Maximum fetch time - 30 seconds default.
const GZIP_MAX_FETCH_TIME_MILLIS = Number(
process.env.GZIP_MAX_FETCH_TIME_MILLIS ?? String(30 * 1000)
);
// Comma-separated list of allowed domains. Empty means all domains are allowed.
const GZIP_ALLOWED_DOMAINS = (process.env.GZIP_ALLOWED_DOMAINS ?? "")
.split(",")
.map((d) => d.trim().toLowerCase())
.filter((d) => d.length > 0);
// Tool input schema
const GZipFileAsResourceSchema = z.object({
name: z.string().describe("Name of the output file").default("README.md.gz"),
data: z
.url()
.describe("URL or data URI of the file content to compress")
.default(
"https://raw.githubusercontent.com/modelcontextprotocol/servers/refs/heads/main/README.md"
),
outputType: z
.enum(["resourceLink", "resource"])
.default("resourceLink")
.describe(
"How the resulting gzipped file should be returned. 'resourceLink' returns a link to a resource that can be read later, 'resource' returns a full resource object."
),
});
// Tool configuration
const name = "gzip-file-as-resource";
const config = {
title: "GZip File as Resource Tool",
description:
"Compresses a single file using gzip compression. Depending upon the selected output type, returns either the compressed data as a gzipped resource or a resource link, allowing it to be downloaded in a subsequent request during the current session.",
inputSchema: GZipFileAsResourceSchema,
};
/**
* Registers the `gzip-file-as-resource` tool.
*
* The registered tool compresses input data using gzip, and makes the resulting file accessible
* as a resource for the duration of the session.
*
* The tool supports two output types:
* - "resource": Returns the resource directly, including its URI, MIME type, and base64-encoded content.
* - "resourceLink": Returns a link to access the resource later.
*
* If an unrecognized `outputType` is provided, the tool throws an error.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
* @throws {Error} Throws an error if an unknown output type is specified.
*/
export const registerGZipFileAsResourceTool = (server: McpServer) => {
server.registerTool(name, config, async (args): Promise<CallToolResult> => {
const {
name,
data: dataUri,
outputType,
} = GZipFileAsResourceSchema.parse(args);
// Validate data uri
const url = validateDataURI(dataUri);
// Fetch the data
const response = await fetchSafely(url, {
maxBytes: GZIP_MAX_FETCH_SIZE,
timeoutMillis: GZIP_MAX_FETCH_TIME_MILLIS,
});
// Compress the data using gzip
const inputBuffer = Buffer.from(response);
const compressedBuffer = gzipSync(inputBuffer);
// Create resource
const uri = getSessionResourceURI(name);
const blob = compressedBuffer.toString("base64");
const mimeType = "application/gzip";
const resource = <Resource>{ uri, name, mimeType };
// Register resource, get resource link in return
const resourceLink = registerSessionResource(
server,
resource,
"blob",
blob
);
// Return the resource or a resource link that can be used to access this resource later
if (outputType === "resource") {
return {
content: [
{
type: "resource",
resource: { uri, mimeType, blob },
},
],
};
} else if (outputType === "resourceLink") {
return {
content: [resourceLink],
};
} else {
throw new Error(`Unknown outputType: ${outputType}`);
}
});
};
/**
* Validates a given data URI to ensure it follows the appropriate protocols and rules.
*
* @param {string} dataUri - The data URI to validate. Must be an HTTP, HTTPS, or data protocol URL. If a domain is provided, it must match the allowed domains list if applicable.
* @return {URL} The validated and parsed URL object.
* @throws {Error} If the data URI does not use a supported protocol or does not meet allowed domains criteria.
*/
function validateDataURI(dataUri: string): URL {
// Validate Inputs
const url = new URL(dataUri);
try {
if (
url.protocol !== "http:" &&
url.protocol !== "https:" &&
url.protocol !== "data:"
) {
throw new Error(
`Unsupported URL protocol for ${dataUri}. Only http, https, and data URLs are supported.`
);
}
if (
GZIP_ALLOWED_DOMAINS.length > 0 &&
(url.protocol === "http:" || url.protocol === "https:")
) {
const domain = url.hostname;
const domainAllowed = GZIP_ALLOWED_DOMAINS.some((allowedDomain) => {
return domain === allowedDomain || domain.endsWith(`.${allowedDomain}`);
});
if (!domainAllowed) {
throw new Error(`Domain ${domain} is not in the allowed domains list.`);
}
}
} catch (error) {
throw new Error(
`Error processing file ${dataUri}: ${
error instanceof Error ? error.message : String(error)
}`
);
}
return url;
}
/**
* Fetches data safely from a given URL while ensuring constraints on maximum byte size and timeout duration.
*
* @param {URL} url The URL to fetch data from.
* @param {Object} options An object containing options for the fetch operation.
* @param {number} options.maxBytes The maximum allowed size (in bytes) of the response. If the response exceeds this size, the operation will be aborted.
* @param {number} options.timeoutMillis The timeout duration (in milliseconds) for the fetch operation. If the fetch takes longer, it will be aborted.
* @return {Promise<ArrayBuffer>} A promise that resolves with the response as an ArrayBuffer if successful.
* @throws {Error} Throws an error if the response size exceeds the defined limit, the fetch times out, or the response is otherwise invalid.
*/
async function fetchSafely(
url: URL,
{ maxBytes, timeoutMillis }: { maxBytes: number; timeoutMillis: number }
): Promise<ArrayBuffer> {
const controller = new AbortController();
const timeout = setTimeout(
() =>
controller.abort(
`Fetching ${url} took more than ${timeoutMillis} ms and was aborted.`
),
timeoutMillis
);
try {
// Fetch the data
const response = await fetch(url, { signal: controller.signal });
if (!response.body) {
throw new Error("No response body");
}
// Note: we can't trust the Content-Length header: a malicious or clumsy server could return much more data than advertised.
// We check it here for early bail-out, but we still need to monitor actual bytes read below.
const contentLengthHeader = response.headers.get("content-length");
if (contentLengthHeader != null) {
const contentLength = parseInt(contentLengthHeader, 10);
if (contentLength > maxBytes) {
throw new Error(
`Content-Length for ${url} exceeds max of ${maxBytes}: ${contentLength}`
);
}
}
// Read the fetched data from the response body
const reader = response.body.getReader();
const chunks = [];
let totalSize = 0;
// Read chunks until done
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
totalSize += value.length;
if (totalSize > maxBytes) {
reader.cancel();
throw new Error(`Response from ${url} exceeds ${maxBytes} bytes`);
}
chunks.push(value);
}
} finally {
reader.releaseLock();
}
// Combine chunks into a single buffer
const buffer = new Uint8Array(totalSize);
let offset = 0;
for (const chunk of chunks) {
buffer.set(chunk, offset);
offset += chunk.length;
}
return buffer.buffer;
} finally {
clearTimeout(timeout);
}
}
```
## /src/everything/tools/index.ts
```ts path="/src/everything/tools/index.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerGetAnnotatedMessageTool } from "./get-annotated-message.js";
import { registerEchoTool } from "./echo.js";
import { registerGetEnvTool } from "./get-env.js";
import { registerGetResourceLinksTool } from "./get-resource-links.js";
import { registerGetResourceReferenceTool } from "./get-resource-reference.js";
import { registerGetRootsListTool } from "./get-roots-list.js";
import { registerGetStructuredContentTool } from "./get-structured-content.js";
import { registerGetSumTool } from "./get-sum.js";
import { registerGetTinyImageTool } from "./get-tiny-image.js";
import { registerGZipFileAsResourceTool } from "./gzip-file-as-resource.js";
import { registerToggleSimulatedLoggingTool } from "./toggle-simulated-logging.js";
import { registerToggleSubscriberUpdatesTool } from "./toggle-subscriber-updates.js";
import { registerTriggerElicitationRequestTool } from "./trigger-elicitation-request.js";
import { registerTriggerLongRunningOperationTool } from "./trigger-long-running-operation.js";
import { registerTriggerSamplingRequestTool } from "./trigger-sampling-request.js";
import { registerTriggerSamplingRequestAsyncTool } from "./trigger-sampling-request-async.js";
import { registerTriggerElicitationRequestAsyncTool } from "./trigger-elicitation-request-async.js";
import { registerSimulateResearchQueryTool } from "./simulate-research-query.js";
/**
* Register the tools with the MCP server.
* @param server
*/
export const registerTools = (server: McpServer) => {
registerEchoTool(server);
registerGetAnnotatedMessageTool(server);
registerGetEnvTool(server);
registerGetResourceLinksTool(server);
registerGetResourceReferenceTool(server);
registerGetStructuredContentTool(server);
registerGetSumTool(server);
registerGetTinyImageTool(server);
registerGZipFileAsResourceTool(server);
registerToggleSimulatedLoggingTool(server);
registerToggleSubscriberUpdatesTool(server);
registerTriggerLongRunningOperationTool(server);
};
/**
* Register the tools that are conditional upon client capabilities.
* These must be registered conditionally, after initialization.
*/
export const registerConditionalTools = (server: McpServer) => {
registerGetRootsListTool(server);
registerTriggerElicitationRequestTool(server);
registerTriggerSamplingRequestTool(server);
// Task-based research tool (uses experimental tasks API)
registerSimulateResearchQueryTool(server);
// Bidirectional task tools - server sends requests that client executes as tasks
registerTriggerSamplingRequestAsyncTool(server);
registerTriggerElicitationRequestAsyncTool(server);
};
```
## /src/everything/tools/toggle-simulated-logging.ts
```ts path="/src/everything/tools/toggle-simulated-logging.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import {
beginSimulatedLogging,
stopSimulatedLogging,
} from "../server/logging.js";
// Tool configuration
const name = "toggle-simulated-logging";
const config = {
title: "Toggle Simulated Logging",
description: "Toggles simulated, random-leveled logging on or off.",
inputSchema: {},
};
// Track enabled clients by session id
const clients: Set<string | undefined> = new Set<string | undefined>();
/**
* Registers the `toggle-simulated-logging` tool.
*
* The registered tool enables or disables the sending of periodic, random-leveled
* logging messages the connected client.
*
* When invoked, it either starts or stops simulated logging based on the session's
* current state. If logging for the specified session is active, it will be stopped;
* if it is inactive, logging will be started.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerToggleSimulatedLoggingTool = (server: McpServer) => {
server.registerTool(
name,
config,
async (_args, extra): Promise<CallToolResult> => {
const sessionId = extra?.sessionId;
let response: string;
if (clients.has(sessionId)) {
stopSimulatedLogging(sessionId);
clients.delete(sessionId);
response = `Stopped simulated logging for session ${sessionId}`;
} else {
beginSimulatedLogging(server, sessionId);
clients.add(sessionId);
response = `Started simulated, random-leveled logging for session ${sessionId} at a 5 second pace. Client's selected logging level will be respected. If an interval elapses and the message to be sent is below the selected level, it will not be sent. Thus at higher chosen logging levels, messages should arrive further apart. `;
}
return {
content: [{ type: "text", text: `${response}` }],
};
}
);
};
```
## /src/everything/tools/toggle-subscriber-updates.ts
```ts path="/src/everything/tools/toggle-subscriber-updates.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import {
beginSimulatedResourceUpdates,
stopSimulatedResourceUpdates,
} from "../resources/subscriptions.js";
// Tool configuration
const name = "toggle-subscriber-updates";
const config = {
title: "Toggle Subscriber Updates",
description: "Toggles simulated resource subscription updates on or off.",
inputSchema: {},
};
// Track enabled clients by session id
const clients: Set<string | undefined> = new Set<string | undefined>();
/**
* Registers the `toggle-subscriber-updates` tool.
*
* The registered tool enables or disables the sending of periodic, simulated resource
* update messages the connected client for any subscriptions they have made.
*
* When invoked, it either starts or stops simulated resource updates based on the session's
* current state. If simulated updates for the specified session is active, it will be stopped;
* if it is inactive, simulated updates will be started.
*
* The response provides feedback indicating whether simulated updates were started or stopped,
* including the session ID.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerToggleSubscriberUpdatesTool = (server: McpServer) => {
server.registerTool(
name,
config,
async (_args, extra): Promise<CallToolResult> => {
const sessionId = extra?.sessionId;
let response: string;
if (clients.has(sessionId)) {
stopSimulatedResourceUpdates(sessionId);
clients.delete(sessionId);
response = `Stopped simulated resource updates for session ${sessionId}`;
} else {
beginSimulatedResourceUpdates(server, sessionId);
clients.add(sessionId);
response = `Started simulated resource updated notifications for session ${sessionId} at a 5 second pace. Client will receive updates for any resources the it is subscribed to.`;
}
return {
content: [{ type: "text", text: `${response}` }],
};
}
);
};
```
## /src/everything/tools/trigger-long-running-operation.ts
```ts path="/src/everything/tools/trigger-long-running-operation.ts"
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
// Tool input schema
const TriggerLongRunningOperationSchema = z.object({
duration: z
.number()
.default(10)
.describe("Duration of the operation in seconds"),
steps: z.number().default(5).describe("Number of steps in the operation"),
});
// Tool configuration
const name = "trigger-long-running-operation";
const config = {
title: "Trigger Long Running Operation Tool",
description: "Demonstrates a long running operation with progress updates.",
inputSchema: TriggerLongRunningOperationSchema,
};
/**
* Registers the 'trigger-tong-running-operation' tool.
*
* The registered tool starts a long-running operation defined by a specific duration and
* number of steps.
*
* Progress notifications are sent back to the client at each step if a `progressToken`
* is provided in the metadata.
*
* At the end of the operation, the tool returns a message indicating the completion of the
* operation, including the total duration and steps.
*
* @param {McpServer} server - The McpServer instance where the tool will be registered.
*/
export const registerTriggerLongRunningOperationTool = (server: McpServer) => {
server.registerTool(
name,
config,
async (args, extra): Promise<CallToolResult> => {
const validatedArgs = TriggerLongRunningOperationSchema.parse(args);
const { duration, steps } = validatedArgs;
const stepDuration = duration / steps;
const progressToken = extra._meta?.progressToken;
for (let i = 1; i < steps + 1; i++) {
await new Promise((resolve) =>
setTimeout(resolve, stepDuration * 1000)
);
if (progressToken !== undefined) {
await server.server.notification(
{
method: "notifications/progress",
params: {
progress: i,
total: steps,
progressToken,
},
},
{ relatedRequestId: extra.requestId }
);
}
}
return {
content: [
{
type: "text",
text: `Long running operation completed. Duration: ${duration} seconds, Steps: ${steps}.`,
},
],
};
}
);
};
```
## /src/everything/transports/stdio.ts
```ts path="/src/everything/transports/stdio.ts"
#!/usr/bin/env node
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createServer } from "../server/index.js";
console.error("Starting default (STDIO) server...");
/**
* The main method
* - Initializes the StdioServerTransport, sets up the server,
* - Handles cleanup on process exit.
*
* @return {Promise<void>} A promise that resolves when the main function has executed and the process exits.
*/
async function main(): Promise<void> {
const transport = new StdioServerTransport();
const { server, cleanup } = createServer();
// Connect transport to server
await server.connect(transport);
// Cleanup on exit
process.on("SIGINT", async () => {
await server.close();
cleanup();
process.exit(0);
});
}
main().catch((error) => {
console.error("Server error:", error);
process.exit(1);
});
```
## /src/everything/tsconfig.json
```json path="/src/everything/tsconfig.json"
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "."
},
"include": ["./**/*.ts"]
}
```
## /src/fetch/.python-version
```python-version path="/src/fetch/.python-version"
3.11
```
## /src/fetch/src/mcp_server_fetch/__main__.py
```py path="/src/fetch/src/mcp_server_fetch/__main__.py"
# __main__.py
from mcp_server_fetch import main
main()
```
The content has been capped at 50000 tokens. The user could consider applying other filters to refine the result. The better and more specific the context, the better the LLM can follow instructions. If the context seems verbose, the user can refine the filter using uithub. Thank you for using https://uithub.com - Perfect LLM context for any GitHub repo.