From 734d5c3ebb162088c2b1d96a6cec03f2b8ca0965 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Mon, 15 Dec 2025 17:01:33 -0500 Subject: [PATCH] Updated server instructions.md. See https://github.com/modelcontextprotocol/servers/pull/3121#discussion_r2616651611 --- src/everything/docs/instructions.md | 83 +++++++---------------------- 1 file changed, 18 insertions(+), 65 deletions(-) diff --git a/src/everything/docs/instructions.md b/src/everything/docs/instructions.md index d6cfa8e6..58a71e93 100644 --- a/src/everything/docs/instructions.md +++ b/src/everything/docs/instructions.md @@ -2,76 +2,29 @@ **[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)** -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. +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. -Date: 2025-12-13 +## Cross-Feature Relationships -## Using the Server +- Use `get-roots-list` to see client workspace roots before file operations +- `gzip-file-as-resource` creates session-scoped resources accessible only during the current session +- Enable `toggle-simulated-logging` before debugging to see server log messages +- Enable `toggle-subscriber-updates` to receive periodic resource update notifications -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. +## Constraints & Limitations -Discover features: +- `gzip-file-as-resource`: Max fetch size controlled by `GZIP_MAX_FETCH_SIZE` (default 10MB), timeout by `GZIP_MAX_FETCH_TIME_MILLIS` (default 30s), allowed domains by `GZIP_ALLOWED_DOMAINS` +- Session resources are ephemeral and lost when the session ends +- Sampling requests (`trigger-sampling-request`) require client sampling capability +- Elicitation requests (`trigger-elicitation-request`) require client elicitation capability -- 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. +## Operational Patterns -Behavioral guidelines: +- For long operations, use `trigger-long-running-operation` which sends progress notifications +- Prefer reading resources before calling mutating tools +- Check `get-roots-list` output to understand the client's workspace context -- 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. +## Easter Egg -## Troubleshooting - -When things don’t work, follow this checklist before making code changes. - -Connectivity & Transport - -- 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` +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."