Merge branch 'main' into claude/issue-2526-20250824-0240

.github/pull_request_template.md

@@ -2,6 +2,12 @@
 
 ## 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 -->

.github/workflows/claude.yml

@@ -26,13 +26,13 @@ jobs:
       actions: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 
@@ -42,10 +42,8 @@ jobs:
 
           # Trigger when assigned to an issue
           assignee_trigger: "claude"
-          
-          # Allow Claude to run bash
-          # This should be safe given the repo is already public
-          allowed_tools: "Bash"
-          
-          custom_instructions: |
-            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.
+
+          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

@@ -14,7 +14,7 @@ jobs:
     outputs:
       packages: ${{ steps.find-packages.outputs.packages }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Find Python packages
         id: find-packages
@@ -31,13 +31,13 @@ jobs:
     name: Test ${{ matrix.package }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version-file: "src/${{ matrix.package }}/.python-version"
 
@@ -68,19 +68,19 @@ jobs:
     name: Build ${{ matrix.package }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        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
+        run: uv sync --locked --all-extras --dev
 
       - name: Run pyright
         working-directory: src/${{ matrix.package }}
@@ -91,7 +91,7 @@ jobs:
         run: uv build
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: dist-${{ matrix.package }}
           path: src/${{ matrix.package }}/dist/
@@ -112,7 +112,7 @@ jobs:
 
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: dist-${{ matrix.package }}
           path: dist/

.github/workflows/readme-pr-check.yml

@@ -0,0 +1,111 @@
+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 server lists are deprecated and will eventually be removed entirely, replaced by the registry.',
+                '',
+                '👉 **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

@@ -8,13 +8,14 @@ on:
 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@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -42,7 +43,7 @@ jobs:
           cat RELEASE_NOTES.md
 
       - name: Release notes
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: release-notes
           path: RELEASE_NOTES.md
@@ -68,10 +69,12 @@ jobs:
     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@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -115,7 +118,7 @@ jobs:
       id-token: write # Required for trusted publishing
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ needs.create-metadata.outputs.version }}
 
@@ -123,7 +126,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version-file: "src/${{ matrix.package }}/.python-version"
 
@@ -155,11 +158,11 @@ jobs:
     environment: release
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ needs.create-metadata.outputs.version }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm
@@ -192,16 +195,19 @@ jobs:
 
   create-release:
     needs: [update-packages, create-metadata, publish-pypi, publish-npm]
-    if: needs.update-packages.outputs.changes_made == 'true'
+    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@v4
+      - uses: actions/checkout@v6
 
       - name: Download release notes
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: release-notes
 

.github/workflows/typescript.yml

@@ -14,7 +14,7 @@ jobs:
     outputs:
       packages: ${{ steps.find-packages.outputs.packages }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Find JS packages
         id: find-packages
         working-directory: src
@@ -30,9 +30,9 @@ jobs:
     name: Test ${{ matrix.package }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm
@@ -41,21 +41,9 @@ jobs:
         working-directory: src/${{ matrix.package }}
         run: npm ci
 
-      - name: Check if tests exist
-        id: check-tests
-        working-directory: src/${{ matrix.package }}
-        run: |
-          if npm run test --silent 2>/dev/null; then
-            echo "has-tests=true" >> $GITHUB_OUTPUT
-          else
-            echo "has-tests=false" >> $GITHUB_OUTPUT
-          fi
-        continue-on-error: true
-
       - name: Run tests
-        if: steps.check-tests.outputs.has-tests == 'true'
         working-directory: src/${{ matrix.package }}
-        run: npm test
+        run: npm test --if-present
 
   build:
     needs: [detect-packages, test]
@@ -65,9 +53,9 @@ jobs:
     name: Build ${{ matrix.package }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm
@@ -96,8 +84,8 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm

.gitignore

@@ -122,6 +122,10 @@ dist
 # Stores VSCode versions used for testing VSCode extensions
 .vscode-test
 
+# IDEs
+.idea/
+.vscode/
+
 # yarn v2
 .yarn/cache
 .yarn/unplugged
@@ -298,3 +302,4 @@ cython_debug/
 #  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

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mcp-docs": {
+      "type": "http",
+      "url": "https://modelcontextprotocol.io/mcp"
+    }
+  }
+}

.vscode/settings.json

@@ -1 +0,0 @@
-{}

CONTRIBUTING.md

@@ -1,105 +1,40 @@
 # Contributing to MCP Servers
 
-Thank you for your interest in contributing to the Model Context Protocol (MCP) servers! This document provides guidelines and instructions for contributing.
+Thanks for your interest in contributing! Here's how you can help make this repo better.
 
-## Types of Contributions
+We accept changes through [the standard GitHub flow model](https://docs.github.com/en/get-started/using-github/github-flow).
 
-### 1. New Servers
+## Server Listings
 
-The repository contains reference implementations, as well as a list of community servers.
-We generally don't accept new servers into the repository. We do accept pull requests to the [README.md](./README.md)
-adding a reference to your servers.
+We are **no longer accepting PRs** to add server links to the README. Please publish your server to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead. Follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx).
 
-Please keep lists in alphabetical order to minimize merge conflicts when adding new items.
+You can browse published servers using the simple UI at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/).
 
-- Check the [modelcontextprotocol.io](https://modelcontextprotocol.io) documentation
-- Ensure your server doesn't duplicate existing functionality
-- Consider whether your server would be generally useful to others
-- Follow [security best practices](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) from the MCP documentation
-- Create a PR adding a link to your server to the [README.md](./README.md).
+## Server Implementations
 
-### 2. Improvements to Existing Servers
-Enhancements to existing servers are welcome! This includes:
+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.
 
-- Bug fixes
-- Performance improvements
-- New features
-- Security enhancements
+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.
 
-### 3. Documentation
-Documentation improvements are always welcome:
+We don't accept:
+- **New server implementations** — We encourage you to publish them to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead.
 
-- Fixing typos or unclear instructions
-- Adding examples
-- Improving setup instructions
-- Adding troubleshooting guides
+## Testing
 
-## Getting Started
+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.
 
-1. Fork the repository
-2. Clone your fork:
-   ```bash
-   git clone https://github.com/your-username/servers.git
-   ```
-3. Add the upstream remote:
-   ```bash
-   git remote add upstream https://github.com/modelcontextprotocol/servers.git
-   ```
-4. Create a branch:
-   ```bash
-   git checkout -b my-feature
-   ```
+## Documentation
 
-## Development Guidelines
+Improvements to existing documentation is welcome - although generally we'd prefer ergonomic improvements than documenting pain points if possible!
 
-### Code Style
-- Follow the existing code style in the repository
-- Include appropriate type definitions
-- Add comments for complex logic
-
-### Documentation
-- Include a detailed README.md in your server directory
-- Document all configuration options
-- Provide setup instructions
-- Include usage examples
-
-### Security
-- Follow security best practices
-- Implement proper input validation
-- Handle errors appropriately
-- Document security considerations
-
-## Submitting Changes
-
-1. Commit your changes:
-   ```bash
-   git add .
-   git commit -m "Description of changes"
-   ```
-2. Push to your fork:
-   ```bash
-   git push origin my-feature
-   ```
-3. Create a Pull Request through GitHub
-
-### Pull Request Guidelines
-
-- Thoroughly test your changes
-- Fill out the pull request template completely
-- Link any related issues
-- Provide clear description of changes
-- Include any necessary documentation updates
-- Add screenshots for UI changes
-- List any breaking changes
+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
 
-- Participate in [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions)
-- Follow the [Code of Conduct](CODE_OF_CONDUCT.md)
+[Learn how the MCP community communicates](https://modelcontextprotocol.io/community/communication).
 
-## Questions?
-
-- Check the [documentation](https://modelcontextprotocol.io)
-- Ask in GitHub Discussions
-
-Thank you for contributing to MCP Servers!
+Thank you for helping make MCP servers better for everyone!

SECURITY.md

@@ -3,7 +3,13 @@ Thank you for helping us keep our MCP servers secure.
 
 The **reference servers** in this repo are maintained by [Anthropic](https://www.anthropic.com/) as part of the Model Context Protocol project.
 
-The security of our systems and user data is Anthropic’s top priority. We appreciate the work of security researchers acting in good faith in identifying and reporting potential vulnerabilities.
+The security of our systems and user data is Anthropic's top priority. We appreciate the work of security researchers acting in good faith in identifying and reporting potential vulnerabilities.
+
+## 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.
+
+**Bug bounties are not awarded for security vulnerabilities found in these reference servers.** Our bug bounty program applies exclusively to the [MCP SDKs](https://github.com/modelcontextprotocol) maintained by Anthropic. If you discover a vulnerability in an MCP SDK that is maintained by Anthropic, please report it through our vulnerability disclosure program below.
 
 ## Vulnerability Disclosure Program
 

scripts/release.py

@@ -97,6 +97,9 @@ class PyPiPackage:
         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"""

src/everything/.prettierignore

@@ -0,0 +1,4 @@
+packages
+dist
+README.md
+node_modules

src/everything/AGENTS.md

@@ -0,0 +1,52 @@
+# 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:stremableHttp` - 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/CLAUDE.md

@@ -1,20 +0,0 @@
-# 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 server: `npm run start` - Starts the MCP server using stdio transport
-- Run SSE server: `npm run start:sse` - Starts the MCP server with SSE 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
-- Follow camelCase for variables/functions, PascalCase for types/classes, UPPER_CASE for constants
-- Handle errors with try/catch blocks and provide clear error messages
-- Use consistent indentation (2 spaces) and trailing commas in multi-line objects

src/everything/README.md

@@ -1,147 +1,17 @@
 # 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.
 
-## Components
+## Tools, Resources, Prompts, and Other Features
 
-### Tools
-
-1. `echo`
-   - Simple tool to echo back input messages
-   - Input:
-     - `message` (string): Message to echo back
-   - Returns: Text content with echoed message
-
-2. `add`
-   - Adds two numbers together
-   - Inputs:
-     - `a` (number): First number
-     - `b` (number): Second number
-   - Returns: Text result of the addition
-
-3. `longRunningOperation`
-   - Demonstrates progress notifications for long operations
-   - Inputs:
-     - `duration` (number, default: 10): Duration in seconds
-     - `steps` (number, default: 5): Number of progress steps
-   - Returns: Completion message with duration and steps
-   - Sends progress notifications during execution
-
-4. `printEnv`
-   - Prints all environment variables
-   - Useful for debugging MCP server configuration
-   - No inputs required
-   - Returns: JSON string of all environment variables
-
-5. `sampleLLM`
-   - Demonstrates LLM sampling capability using MCP sampling feature
-   - Inputs:
-     - `prompt` (string): The prompt to send to the LLM
-     - `maxTokens` (number, default: 100): Maximum tokens to generate
-   - Returns: Generated LLM response
-
-6. `getTinyImage`
-   - Returns a small test image
-   - No inputs required
-   - Returns: Base64 encoded PNG image data
-
-7. `annotatedMessage`
-   - Demonstrates how annotations can be used to provide metadata about content
-   - Inputs:
-     - `messageType` (enum: "error" | "success" | "debug"): Type of message to demonstrate different annotation patterns
-     - `includeImage` (boolean, default: false): Whether to include an example image
-   - Returns: Content with varying annotations:
-     - Error messages: High priority (1.0), visible to both user and assistant
-     - Success messages: Medium priority (0.7), user-focused
-     - Debug messages: Low priority (0.3), assistant-focused
-     - Optional image: Medium priority (0.5), user-focused
-   - Example annotations:
-     ```json
-     {
-       "priority": 1.0,
-       "audience": ["user", "assistant"]
-     }
-     ```
-
-8. `getResourceReference`
-   - Returns a resource reference that can be used by MCP clients
-   - Inputs:
-     - `resourceId` (number, 1-100): ID of the resource to reference
-   - Returns: A resource reference with:
-     - Text introduction
-     - Embedded resource with `type: "resource"`
-     - Text instruction for using the resource URI
-
-9. `startElicitation`
-   - Initiates an elicitation (interaction) within the MCP client.
-   - Inputs:
-      - `color` (string): Favorite color
-      - `number` (number, 1-100): Favorite number
-      - `pets` (enum): Favorite pet
-   - Returns: Confirmation of the elicitation demo with selection summary.
-
-10. `structuredContent`
-   - Demonstrates a tool returning structured content using the example in the specification
-   - Provides an output schema to allow testing of client SHOULD advisory to validate the result using the schema
-   - Inputs:
-     - `location` (string): A location or ZIP code, mock data is returned regardless of value
-   - Returns: a response with
-     - `structuredContent` field conformant to the output schema
-     - A backward compatible Text Content field, a SHOULD advisory in the specification
-
-### Resources
-
-The server provides 100 test resources in two formats:
-- Even numbered resources:
-  - Plaintext format
-  - URI pattern: `test://static/resource/{even_number}`
-  - Content: Simple text description
-
-- Odd numbered resources:
-  - Binary blob format
-  - URI pattern: `test://static/resource/{odd_number}`
-  - Content: Base64 encoded binary data
-
-Resource features:
-- Supports pagination (10 items per page)
-- Allows subscribing to resource updates
-- Demonstrates resource templates
-- Auto-updates subscribed resources every 5 seconds
-
-### Prompts
-
-1. `simple_prompt`
-   - Basic prompt without arguments
-   - Returns: Single message exchange
-
-2. `complex_prompt`
-   - Advanced prompt demonstrating argument handling
-   - Required arguments:
-     - `temperature` (number): Temperature setting
-   - Optional arguments:
-     - `style` (string): Output style preference
-   - Returns: Multi-turn conversation with images
-
-3. `resource_prompt`
-   - Demonstrates embedding resource references in prompts
-   - Required arguments:
-     - `resourceId` (number): ID of the resource to embed (1-100)
-   - Returns: Multi-turn conversation with an embedded resource reference
-   - Shows how to include resources directly in prompt messages
-
-### Logging
-
-The server sends random-leveled log messages every 15 seconds, e.g.:
-
-```json
-{
-  "method": "notifications/message",
-  "params": {
-	"level": "info",
-	"data": "Info-level message"
-  }
-}
-```
+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))
 
@@ -177,7 +47,7 @@ Add the configuration to your user-level MCP configuration file. Open the Comman
 **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/mcp).
+> 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
 

src/everything/docs/architecture.md

@@ -0,0 +1,44 @@
+# 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

@@ -0,0 +1,23 @@
+# 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)`.