mcp-tooling-ts

name

mcp-tooling-ts

description

Manage and maintain a TypeScript MCP server using @modelcontextprotocol/sdk with Express and Streamable HTTP/SSE. Supports setup, adding new MCP tools (handler.ts/prompt.ts/type.ts/index.ts), enforcing strict Zod schemas, token-lean prompts (Claude/Grok friendly), manual tool registration, and transport-level API key injection (query/header → env, never in tool params). All code examples use TypeScript (.ts files). Triggers: "setup MCP server", "add MCP tool", "create handler.ts prompt.ts type.ts", "register tool", "refactor MCP prompt", "API key via header/query".

MCP Tooling TS

Purpose

Standardize development of a TypeScript MCP server with:

• Manual tool registration
• Strict Zod schemas
• Token-efficient prompts
• Transport-level API key injection

---

Canonical Project Structure (Minimal)

src/
├─ mcp-node.ts              # Server entry (env injection here only)
├─ registerTools.ts         # Calls registerAllTools(server, env)
├─ tools/index.ts           # Manual registry of all tools
└─ utils/                   # Utility methods and helpers

---

Server Setup (Express + SSE + Streamable HTTP)

mcp-node.ts - Server Entry Point

All transport endpoints (SSE and Streamable HTTP) are implemented directly in mcp-node.ts:

import express from 'express';
import cors from 'cors';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp';
import { registerTools } from './registerTools';

// Environment injection
function buildEnvOverrides(req: express.Request) {
  const queryApiKey = typeof req.query.apiKey === "string" ? req.query.apiKey : undefined;
  const headerApiKey = req.get("x-api-key") ?? req.get("X-API-Key");
  const fusedashApiKey = queryApiKey ?? headerApiKey;

  return {
    ...process.env,
    ...(fusedashApiKey ? { FUSEDASH_API_KEY: fusedashApiKey } : {}),
  };
}

// Express app setup
const app = express();
app.use(cors()); // Enable CORS for MCP clients

// Health check endpoint
app.get("/", (_req, res) => {
  res.status(200).json({
    status: "healthy",
    endpoints: {
      mcp: "POST /mcp",
      sse: "GET /sse",
      health: "GET /"
    },
    timestamp: new Date().toISOString()
  });
});

---

Transport Types

1. Streamable HTTP (Stateless)

app.post("/mcp", express.json({ limit: "5mb" }), async (req, res) => {
  // Stateless: fresh server+transport per request
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // No sessions
  });

  const server = new McpServer({
    name: "your-mcp-server",
    version: "1.0.0",
  });

  try {
    const envOverrides = buildEnvOverrides(req);
    registerTools(server, envOverrides);

    await server.connect(transport);
    await transport.handleRequest(req as any, res as any, req.body);

    res.on("close", () => {
      try { transport.close(); } catch {}
      try { server.close(); } catch {}
    });
  } catch (err) {
    if (!res.headersSent) res.status(500).json({ error:  });
     { transport.(); }  {}
     { server.(); }  {}
  }
});

2. Server-Sent Events (Stateful Sessions)

const sessions = new Map<string, SessionData>();

interface SessionData {
  transport: SSEServerTransport;
  server: McpServer;
  lastActivity: number;
}

// SSE endpoint - creates persistent session
app.get('/sse', async (req, res) => {
  const sessionId = req.query?.sessionId as string | undefined;

  if (sessionId) {
    res.status(400).send('Session already exists');
    return;
  }

  const transport = new SSEServerTransport('/sse/message', res as any);
  const sessionServer = new McpServer({ name: 'MCP-Server', version: '1.0.0' });

  registerTools(sessionServer, buildEnvOverrides(req));
  await sessionServer.connect(transport);

  const sid = transport.sessionId;
  sessions.set(sid, {
    transport,
    : sessionServer,
    : .(),
  });

   isClosing = ;
  transport. =  () => {
     (isClosing) ;
    isClosing = ;

     session = sessions.(sid);
     (!session) ;

     {  session..(); }  {}
     {
       ( session.. === ) session..();
    }  {}

    sessions.(sid);
  };
});


app.(,  (req, res) => {
   sessionId = req.?.  ;
   session = sessions.(sessionId);

   (session) {
     {
      session. = .();
       session..(req  , res  );
    }  (err) {
       (!res.) res.().();
    }
  }  {
     (!res.) res.().();
  }
});

Session Management & Cleanup

Session Timeout Handling

const getMilliseconds = (minutes: number) => minutes * 60 * 1000;

// Read from .env, fall back to sensible defaults
const CLEAN_INACTIVE_SESSIONS_INTERVAL = getMilliseconds(
  Number(process.env.SESSION_CLEANUP_INTERVAL_MINUTES ?? 5)
);

setInterval(async () => {
  const now = Date.now();
  const SESSION_TIMEOUT = getMilliseconds(
    Number(process.env.SESSION_TIMEOUT_MINUTES ?? 30)
  );

  for (const [sessionId, sessionData] of sessions.entries()) {
    if (now - sessionData.lastActivity > SESSION_TIMEOUT) {
      console.log(`[CLEANUP] Inactive session: ${sessionId}`);

      try {
        await sessionData.server.close();
      } catch (e) {
        console.error(`[CLEANUP_ERROR]:`, e);
      }

      try {
        if ( sessionData.. === ) {
          sessionData..();
        }
      }  (e) {
        .(, e);
      }

      sessions.(sessionId);
    }
  }
}, );

---

Transport Comparison

Feature	Streamable HTTP	Server-Sent Events
State	Stateless (per request)	Stateful (persistent session)
Use Case	One-off tool calls	Chat conversations, streaming
Performance	Lower overhead	Higher overhead but persistent
Cleanup	Automatic (per request)	Manual (session timeout)
Complexity	Simple	Complex (session management)
Endpoint	POST /mcp	GET /sse + POST /sse/message

---

API Key Injection (Transport Level)

Query Parameter

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' \
  -G -d "apiKey=your-api-key-here"

Header Injection

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

SSE with API Key

curl -N "http://localhost:3000/sse?apiKey=your-api-key-here"

---

Single Tool Structure (Minimal)

src/tools/<ToolFolder>/
├─ handler.ts   # registerX(server, env) + server.tool(...)
├─ prompt.ts    # short (10–20 lines) prompt string
├─ type.ts      # Zod schema (.strict()) + inferred type
└─ index.ts     # re-exports

---

Architectural Invariants

1. API key is NEVER part of tool params.
2. API key is provided via:
   • /mcp?apiKey=...
   • x-api-key header
3. Only mcp-node.ts may parse query/header.
4. mcp-node.ts injects:
   • env.FUSEDASH_API_KEY
5. Tools read:
   • env.FUSEDASH_API_KEY
6. All tools must be manually registered in src/tools/index.ts.
7. All schemas must use .strict().
8. Utility methods are stored in src/utils/.
9. src/registerTools.ts contains the main registration logic.
10. Session cleanup timing is configured via .env:
    • SESSION_CLEANUP_INTERVAL_MINUTES (default: 5)
    • SESSION_TIMEOUT_MINUTES (default: 30)

---

Workflow

Add a New Tool

1. Create folder under src/tools/<ToolFolder>/
2. Add: type.ts, prompt.ts, handler.ts, index.ts
3. Import and call registerX(server, env) inside src/tools/index.ts
4. Ensure src/registerTools.ts calls registerAllTools(server, env)
5. Run pnpm build

Verify Tool Registration

• Confirm import exists in src/tools/index.ts
• Confirm server.tool("<toolName>", ...) exists
• Ensure src/registerTools.ts exists and is imported
• Run pnpm build

---

Prompt Rules

• 10–20 lines maximum
• No XML blocks
• Must include:
  • Purpose
  • Call when
  • Do NOT call when
  • Args summary
  • Rules: never invent args, no extra keys

---

Schema Rules

• Always .strict()
• Required strings: .min(1)
• Required arrays: .min(1)
• Use defaults to reduce prompt verbosity
• Never include apiKey

---

Output Format

STATUS: SUCCESS / FAILED / BLOCKED
Summary: ...
Files: ...
Commands: ...
Notes: ...

---