mirror of
https://github.com/modelcontextprotocol/servers.git
synced 2026-04-19 08:33:23 +02:00
[WIP] Refactor everything server to be more modular and use recommended APIs.
* Adding static resources, move server instructions to
the new docs folder, and add code formatting
* Add docs folder
* Add docs/architecture.md which describes the architecture of the project thus far.
* Refactor moved instructions.md to docs/server-instructions.md
* Add resources/static.ts
- in addStaticResources()
- read the file entries from the docs folder
- register each file as a resource (no template), with a readResource function that reads the file and returns it in a contents block with the appropriate mime type and contents
- getMimeType helper function gets the mime type for a filename
- readSafe helper function reads the file synchronously as utf-8 or returns an error string
* Add resources/index.ts
- import addStaticResources
- export registerResources function
- in registerResources()
- call addStaticResources
* In package.json
- add prettier devDependency
- add prettier:check script
- add prettier:fix script
- in build script, copy docs folder to dist
* All other changes were prettier formatting
This commit is contained in:
cliffhall
163
src/everything/docs/architecture.md
Normal file
163
src/everything/docs/architecture.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# Everything Server – Architecture and Layout
|
||||
|
||||
This document summarizes the current layout and runtime architecture of the `src/everything` package. It explains how the server starts, how transports are wired, where tools 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 a simple tool and both static and dynamic 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 and resources are organized in their own submodules.
|
||||
- Two server implementations exist:
|
||||
- `server/index.ts`: The lightweight, modular server used by transports in this package.
|
||||
- `server/everything.ts`: A comprehensive reference server (much larger, many tools/prompts/resources) kept for reference/testing but not wired up by default in the entry points.
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
src/everything
|
||||
├── index.ts
|
||||
├── server
|
||||
│ ├── index.ts
|
||||
│ └── everything.ts
|
||||
├── transports
|
||||
│ ├── stdio.ts
|
||||
│ ├── sse.ts
|
||||
│ └── streamableHttp.ts
|
||||
├── tools
|
||||
│ ├── index.ts
|
||||
│ └── echo.ts
|
||||
├── resources
|
||||
│ ├── index.ts
|
||||
│ ├── dynamic.ts
|
||||
│ └── static.ts
|
||||
├── docs
|
||||
│ ├── server-instructions.md
|
||||
│ └── architecture.md
|
||||
└── package.json
|
||||
```
|
||||
|
||||
At `src/everything`:
|
||||
|
||||
- index.ts
|
||||
|
||||
- CLI entry that selects and runs a specific transport module based on the first CLI argument: `stdio`, `sse`, or `streamableHttp`.
|
||||
|
||||
- server/
|
||||
|
||||
- index.ts
|
||||
- Server factory that creates an `McpServer` with declared capabilities, loads server instructions, and registers tools and resources.
|
||||
- Exposes `{ server, cleanup, startNotificationIntervals }` to the chosen transport.
|
||||
- everything.ts
|
||||
- A full “reference/monolith” implementation demonstrating most MCP features. Not the default path used by the transports in this package.
|
||||
|
||||
- transports/
|
||||
|
||||
- stdio.ts
|
||||
- Starts a `StdioServerTransport`, creates the server via `createServer()`, and connects it. Handles `SIGINT` to close cleanly.
|
||||
- sse.ts
|
||||
- Express server exposing:
|
||||
- `GET /sse` to establish an SSE connection per session.
|
||||
- `POST /message` for client messages.
|
||||
- Manages a `Map<sessionId, SSEServerTransport>` for sessions. Calls `startNotificationIntervals(sessionId)` after connect (hook currently a no‑op in the factory).
|
||||
- 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, then reuses transport for subsequent requests.
|
||||
|
||||
- tools/
|
||||
|
||||
- index.ts
|
||||
- `registerTools(server)` orchestrator, currently delegates to `addToolEcho`.
|
||||
- echo.ts
|
||||
- Defines a minimal `echo` tool with a Zod input schema and returns `Echo: {message}`.
|
||||
|
||||
- resources/
|
||||
|
||||
- index.ts
|
||||
- `registerResources(server)` orchestrator; delegates to static and dynamic resources.
|
||||
- dynamic.ts
|
||||
- Registers two dynamic, template‑driven resources using `ResourceTemplate`:
|
||||
- Text: `test://dynamic/resource/text/{index}` (MIME: `text/plain`)
|
||||
- Blob: `test://dynamic/resource/blob/{index}` (MIME: `application/octet-stream`, Base64 payload)
|
||||
- The `{index}` path variable must be a finite integer. Content is generated on demand with a GMT timestamp.
|
||||
- static.ts
|
||||
- Registers static resources for each file in the `docs/` folder.
|
||||
- URIs follow the pattern: `test://static/docs/<filename>`.
|
||||
- Serves markdown files as `text/markdown`, `.txt` as `text/plain`, `.json` as `application/json`, others default to `text/plain`.
|
||||
|
||||
- docs/
|
||||
|
||||
- server-instructions.md
|
||||
- Human‑readable instructions intended to be passed to the client/LLM as MCP server instructions. Loaded by the server at startup.
|
||||
- architecture.md (this document)
|
||||
|
||||
- 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.
|
||||
|
||||
## Startup and Runtime Flow
|
||||
|
||||
1. A transport is chosen via the CLI entry `index.ts`:
|
||||
|
||||
- `node dist/index.js stdio` → loads `transports/stdio.js`
|
||||
- `node dist/index.js sse` → loads `transports/sse.js`
|
||||
- `node dist/index.js streamableHttp` → loads `transports/streamableHttp.js`
|
||||
|
||||
2. The transport creates the server via `createServer()` from `server/index.ts` and connects it to the chosen transport type from the MCP SDK.
|
||||
|
||||
3. The server factory (`server/index.ts`) does the following:
|
||||
|
||||
- Creates `new McpServer({ name, title, version }, { capabilities, instructions })`.
|
||||
- Capabilities:
|
||||
- `tools: {}`
|
||||
- `logging: {}`
|
||||
- `prompts: {}`
|
||||
- `resources: { subscribe: true }`
|
||||
- Loads human‑readable “server instructions” from the docs folder (`server-instructions.md`).
|
||||
- Registers tools via `registerTools(server)`.
|
||||
- Registers resources via `registerResources(server)`.
|
||||
- Returns the server and two lifecycle hooks:
|
||||
- `cleanup`: transport may call on shutdown (currently a no‑op).
|
||||
- `startNotificationIntervals(sessionId?)`: currently a no‑op; wired in SSE transport for future periodic notifications.
|
||||
|
||||
4. Each transport is responsible for network/session lifecycle:
|
||||
- STDIO: simple process‑bound connection; closes on `SIGINT`.
|
||||
- SSE: maintains a session map keyed by `sessionId`, hooks server’s `onclose` to clean and remove session, exposes `/sse` (GET) and `/message` (POST) endpoints.
|
||||
- Streamable HTTP: exposes `/mcp` for POST (JSON‑RPC messages), GET (SSE stream), and DELETE (termination). Uses an event store for resumability and stores transports by `sessionId`.
|
||||
|
||||
## Registered Features (current minimal set)
|
||||
|
||||
- Tools
|
||||
|
||||
- `echo` (tools/echo.ts): Echoes the provided `message: string`. Uses Zod to validate inputs.
|
||||
|
||||
- Resources
|
||||
- Dynamic Text: `test://dynamic/resource/text/{index}` (content generated on the fly)
|
||||
- Dynamic Blob: `test://dynamic/resource/blob/{index}` (base64 payload generated on the fly)
|
||||
- Static Docs: `test://static/docs/<filename>` (serves files from `src/everything/docs/` as static resources)
|
||||
|
||||
## Extension Points
|
||||
|
||||
- Adding Tools
|
||||
|
||||
- Create a new file under `tools/` with your `addToolX(server)` function that registers the tool via `server.registerTool(...)`.
|
||||
- Export and call it from `tools/index.ts` inside `registerTools(server)`.
|
||||
|
||||
- Adding Resources
|
||||
|
||||
- Create a new file under `resources/` with your `addXResources(server)` function using `server.registerResource(...)` (optionally with `ResourceTemplate`).
|
||||
- Export and call it from `resources/index.ts` inside `registerResources(server)`.
|
||||
|
||||
- Adding Transports
|
||||
- Implement a new transport module under `transports/`.
|
||||
- Add a case to `index.ts` so the CLI can select it.
|
||||
|
||||
## 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`.
|
||||
|
||||
## Relationship to the Full Reference Server
|
||||
|
||||
The large `server/everything.ts` shows a comprehensive MCP server showcasing many features (tools with schemas, prompts, resource operations, notifications, etc.). The current transports in this package use the lean factory from `server/index.ts` instead, keeping the runtime small and focused while preserving the reference implementation for learning and experimentation.
|
||||
23
src/everything/docs/server-instructions.md
Normal file
23
src/everything/docs/server-instructions.md
Normal file
@@ -0,0 +1,23 @@
|
||||
Testing and demonstration server for MCP protocol features.
|
||||
|
||||
## Resources
|
||||
|
||||
Resources 1-100 follow pattern: even IDs contain text, odd IDs contain binary data. Resources are paginated at 10 items per page with cursor-based navigation.
|
||||
|
||||
## Key dependencies
|
||||
|
||||
Progress notifications require `_meta.progressToken` in tool calls. Resource subscriptions generate updates every 10 seconds.
|
||||
|
||||
## Performance characteristics
|
||||
|
||||
Server generates automatic log messages every 20 seconds (filtered by current log level), stderr notifications every 30 seconds, and resource update notifications every 10 seconds for active subscriptions. Log level changes affect message filtering in real-time.
|
||||
|
||||
## Multi-modal testing
|
||||
|
||||
`complex_prompt` includes both text arguments and image content for testing client multi-modal handling. `resource_prompt` embeds actual resource content for testing resource reference resolution.
|
||||
|
||||
Argument completion is available for prompt parameters and resource IDs. Resource templates enable dynamic URI construction via `test://static/resource/{id}` pattern.
|
||||
|
||||
## 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."
|
||||
Reference in New Issue
Block a user