starred/servers-modelcontextprotocol
1
0
Fork 0
mirror of https://github.com/modelcontextprotocol/servers.git synced 2026-04-19 08:33:23 +02:00
Code Issues Packages Projects Releases Wiki Activity

[WIP] Refactor everything server to be more modular and use recommended APIs.

Browse Source 
* 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
2025-12-05 13:26:08 -05:00
parent 8845118d61
commit 1c64b36c78
17 changed files with 904 additions and 527 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
src/everything/docs/architecture.md Normal file
View 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.