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

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

Browse Source 
Updated docs

* Refactor/renamed CLAUDE.md to AGENTS.md
* Updated instructions.md and startup.md
This commit is contained in:
cliffhall
2025-12-13 10:03:21 -05:00
parent 2093f2dfac
commit 115789036a
4 changed files with 116 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
src/everything/AGENTS.md Normal file
View File

@@ -0,0 +1,51 @@
# 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.
## Extending the Server
The Everything Server is designed to be extended at well-defined points.
See [Extension Points](docs/extension.md) and [Project Structure](docsstructure.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.
- If the feature is session‑aware, accept/pass `sessionId` where needed. See the `clientConnected(sessionId)` pattern in `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.

23
src/everything/CLAUDE.md
View File

@@ -1,23 +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 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
- 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

84
src/everything/docs/instructions.md
View File

@@ -1,32 +1,76 @@
# Everything Server - Instructions
**[Architecture](architecture.md)
| [Project Structure](structure.md)
| [Startup Process](startup.md)
| [Server Features](features.md)
| [Extension Points](extension.md)
| [How It Works](how-it-works.md)**
# Everything Server – LLM Instructions
**[Architecture](architecture.md) | [Project Structure](structure.md) | [Startup Process](startup.md) | [Server Features](features.md) | [Extension Points](extension.md) | [How It Works](how-it-works.md)**
A testing and demonstration server for MCP protocol features.
TODO: Update this doc
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.
## Resources
Date: 2025-12-13
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.
## Using the Server
## Key dependencies
You are speaking MCP. Always prefer discovering server capabilities dynamically and follow the MCP spec. The Everything server exposes prompts, tools, resources, logging, and subscriptions. It may run over `stdio`, SSE (deprecated), or Streamable HTTP.
Progress notifications require `_meta.progressToken` in tool calls. Resource subscriptions generate updates every 10 seconds.
Discover features:
- Prompts: `prompts/list` → then `prompts/get` with `name` and `arguments`.
- Tools: `tools/list` → then call tools via `tools/call` with validated params.
- Resources: `resources/list` → then `resources/read { uri }`.
- Logging: `logging/setLevel`set desired log level if supported by your client SDK; otherwise just read logs returned by tool/prompts as content parts.
## Performance characteristics
Behavioral guidelines:
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.
- Validate tool parameters before calling. Use JSON schemas from `tools/list`.
- Prefer idempotent reads first (resources, prompts) before mutating via tools.
- If the server provides instructions in the initialize result (this document), follow them over any prior assumptions.
## 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.
## Troubleshooting
Argument completion is available for prompt parameters and resource IDs. Resource templates enable dynamic URI construction via `demo://static/resource/{id}` pattern.
When things don’t work, follow this checklist before making code changes.
## Easter egg
Connectivity & Transport
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."
- Confirm the transport actually running:
- stdio: process is alive; stderr/stdout not blocked; your client launched it with the correct `command`/`args`.
- SSE: server exposes `/sse` (GET) and `/message` (POST). See [Startup Process](startup.md).
- Streamable HTTP: server exposes `/mcp` with `POST` (messages), `GET` (SSE stream), and `DELETE` (terminate).
- If multiple clients use HTTP transports, ensure your client sends/propagates `sessionId` consistently.
Initialization
- Check that `createServer()` returns capabilities you expect: `tools`, `prompts`, `resources.subscribe`, and `logging`.
- If instructions are missing in the `initialize` result, verify `readInstructions()` is reading this file correctly and the path is correct.
Discovery & Calls
- `tools/list` returns the tool and schema; if a call fails, re‑validate input against the schema and include required fields.
- `prompts/get` requires the exact `name` from `prompts/list`; ensure you pass all required `arguments`.
- `resources/read` requires a valid `uri` from `resources/list`. Some resources may be dynamic or require subscription.
Logging & Diagnostics
- Use your client SDK’s logging capability if available; the server supports per‑session logging levels over HTTP transports.
- For simulated logs/resources, ensure periodic tasks are started only _after_ `clientConnected(sessionId)` is invoked by the transport manager.
- If logs or updates don’t appear for HTTP transports, confirm the transport mapped the connection to a `sessionId` and that the server stored transport references keyed by it.
Common issues and fixes
- “Nothing listed”: Ensure registration functions ran. Check `registerTools`, `registerResources`, `registerPrompts` are invoked from `server/index.ts`.
- “Schema validation error”: Re‑read the tool’s JSON Schema and provide required fields with correct types.
- “Subscriptions not updating”: Verify subscription handlers are set via `setSubscriptionHandlers(server)` and that the client is keeping the SSE stream open.
- “Stuck after restart”: For HTTP transports, send `DELETE /mcp` (Streamable HTTP) or close SSE connections cleanly, then reconnect.
## 4) Conventions to Follow (when modifying code)
- Match existing code style, import order, and module layout in the respective folder.
- Keep changes minimal and localized; prefer adding small modules over editing many files.
- Update documentation under `src/everything/docs/` when behavior changes.
- Do not break stdio behavior while adding multi‑client HTTP features; both should work. Remember that `undefined` is a valid Map key for tracking session-related data in the case of stdio.
## 5) Helpful Links
- This project’s README: `src/everything/README.md`
- Architecture overview: `docs/architecture.md`
- Project structure: `docs/structure.md`
- Startup sequence and transports: `docs/startup.md`
- Features catalog: `docs/features.md`
- Extension points: `docs/extension.md`
- How it works (end‑to‑end walkthrough): `docs/how-it-works.md`

2
src/everything/docs/startup.md
View File

@@ -1,4 +1,4 @@
# Everything Server - Startup Flow
# Everything Server - Startup Process
**[Architecture](architecture.md)
| [Project Structure](structure.md)
| Startup Process