Merge pull request #3121 from cliffhall/new-everything-server

New everything server

Author: cliffhall

package-lock.json

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

src/everything/.prettierignore

@@ -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/AGENTS.md

@@ -1,166 +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
-
-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
-
-11. `listRoots`
-   - Lists the current MCP roots provided by the client
-   - Demonstrates the roots protocol capability even though this server doesn't access files
-   - No inputs required
-   - Returns: List of current roots with their URIs and names, or a message if no roots are set
-   - Shows how servers can interact with the MCP roots protocol
-
-### 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` (string): 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
-
-### Roots
-
-The server demonstrates the MCP roots protocol capability:
-
-- Declares `roots: { listChanged: true }` capability to indicate support for roots
-- Handles `roots/list_changed` notifications from clients
-- Requests initial roots during server initialization
-- Provides a `listRoots` tool to display current roots
-- Logs roots-related events for demonstration purposes
-
-Note: This server doesn't actually access files, but demonstrates how servers can interact with the roots protocol for clients that need to understand which directories are available for file operations.
-
-### Logging
-
-The server sends random-leveled log messages every 15 seconds, e.g.:
+## Tools, Resources, Prompts, and Other Features
 
-```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))