servers-modelcontextprotocol/src/everything/docs/instructions.md

Everything Server – LLM Instructions

Architecture | Project Structure | Startup Process | Server Features | Extension Points | How It Works

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

Using the Server

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.

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/setLevelset desired log level if supported by your client SDK; otherwise just read logs returned by tool/prompts as content parts.

Behavioral guidelines:

• 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.

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.
  • 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