convez.ai
MCP ServerDevOps & InfraestruturaAvançado
Gonzih

MCP Substrate

Gonzih/mcp-substrate

Infraestrutura de produção para MCP servers com estado persistente e multi-cliente

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada de infraestrutura de produção para servidores MCP stateful. Resolve problemas operacionais críticos como isolamento de sessão multi-cliente, persistência de estado com Redis, workers singleton distribuídos e injeção de autenticação em chamadas de ferramentas.

Instalação

$npx convez-ai Gonzih/mcp-substrate

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Implantar MCP servers em produção com múltiplos clientes simultâneos
  • Manter estado de sessão através de reinicializações de pods em Kubernetes
  • Executar workers de background em apenas uma réplica de um cluster distribuído
  • Injetar credenciais por sessão em chamadas de ferramentas MCP

Veredito

Ferramenta essencial para levar MCP servers para produção com confiabilidade e escalabilidade. Resolve problemas reais de operação distribuída que o SDK base não cobre, ideal para equipes que precisam de session management robusto e coordenação entre réplicas.

README

A tradução para o português deste README ainda está na fila.

@gonzih/mcp-substrate

Production infrastructure for stateful MCP servers. Fills the operational gaps that @modelcontextprotocol/sdk maintainers closed as "won't fix":

ModuleProblem solved
createMcpAppShared-transport footgun (issue #961): one server instance per client session
SessionStore / RedisSessionStorePer-session state that survives pod restarts
withSingletonBackground workers that run in exactly one replica
defineStdioServerOrphan process accumulation when parent exits
withAuthPer-session credential injection into tool call context

Install

npm install @gonzih/mcp-substrate @modelcontextprotocol/sdk zod
# For Redis-backed features:
npm install ioredis

createMcpApp

Multi-client-safe HTTP handler. Creates a fresh McpServer per client session — no shared state.

import express from 'express';
import { createMcpApp } from '@gonzih/mcp-substrate';

const handler = createMcpApp(
  (server) => {
    server.registerTool(
      'echo',
      { description: 'Echoes the input', inputSchema: { message: z.string() } },
      async ({ message }) => ({ content: [{ type: 'text', text: message }] }),
    );
  },
  { name: 'my-server', version: '1.0.0' },
);

const app = express();
app.use(express.json());
app.all('/mcp', handler);
app.listen(3000);

Why: The naive pattern of one McpServer + one StreamableHTTPServerTransport for all requests causes session collisions. createMcpApp creates isolated server instances per session and routes by mcp-session-id header.

SessionStore / RedisSessionStore

Portable session state that survives Kubernetes pod restarts.

import Redis from 'ioredis';
import { RedisSessionStore } from '@gonzih/mcp-substrate';

const redis = new Redis(process.env.REDIS_URL!);
const sessions = new RedisSessionStore(redis, {
  keyPrefix: 'mcp:session:',
  defaultTtlSeconds: 3600,
});

// In your tool handler:
const ctx = await sessions.get(sessionId);
await sessions.set(sessionId, { ...ctx, lastSeen: Date.now() }, 3600);

Why: In-memory session maps are lost on pod restart. Redis gives you durable, cross-pod session state with automatic TTL eviction.

For local dev and tests, use MemorySessionStore — same interface, no Redis needed.

withSingleton

Run a background worker in exactly one process across N replicas.

import Redis from 'ioredis';
import { withSingleton } from '@gonzih/mcp-substrate';

const redis = new Redis(process.env.REDIS_URL!);

await withSingleton(redis, 'my-app:queue-poller', async () => {
  setInterval(() => pollQueue(), 3_000);
});

Why: With replicas: 3 in Kubernetes, a naive background poller runs three times. withSingleton uses Redis SET NX EX leader election so exactly one replica runs the worker. If the leader pod dies, the lock expires (default 30 s) and another replica takes over.

Options:

await withSingleton(redis, 'my-app:scheduler', worker, {
  ttlSeconds: 60,       // lock expiry (must be > refreshIntervalMs / 1000)
  refreshIntervalMs: 20_000,  // how often the leader renews the lock
});

defineStdioServer

Stdio MCP server with SIGTERM/EPIPE handling that prevents orphan process accumulation.

import { defineStdioServer } from '@gonzih/mcp-substrate';

await defineStdioServer(
  (server) => {
    server.registerTool('ping', { description: 'Returns pong' }, async () => ({
      content: [{ type: 'text', text: 'pong' }],
    }));
  },
  { name: 'my-stdio-server', version: '1.0.0' },
);

Why: When Claude Desktop or an IDE plugin exits, the spawned stdio server's stdout write end breaks. Without EPIPE handling, Node.js throws an unhandled exception; without SIGTERM handling, the process lingers indefinitely. defineStdioServer installs both handlers for a clean exit.

withAuth

Inject per-session credentials into every tool call without threading them through every function signature.

import { withAuth, getActiveCredentials } from '@gonzih/mcp-substrate';

// Call before registering tools
withAuth(server, async (extra) => ({
  tenantId: extra.authInfo?.extra?.tenantId as string ?? '',
  apiKey: await lookupApiKey(extra.sessionId),
}));

server.registerTool('fetch-data', { description: 'Fetches tenant data' }, async () => {
  const creds = getActiveCredentials();
  if (!creds?.apiKey) throw new Error('Missing API key');
  const data = await fetchTenantData(creds.tenantId, creds.apiKey);
  return { content: [{ type: 'text', text: JSON.stringify(data) }] };
});

Why: Tool handlers need caller-specific tokens (API keys, tenant IDs, OAuth tokens) when calling downstream services. Passing credentials through every function signature creates coupling. withAuth + getActiveCredentials() uses AsyncLocalStorage to make credentials available anywhere in the call stack without prop drilling.

Call withAuth before registering tools — it patches server.registerTool.

License

MIT

Ver o original no GitHub

Bom para

Relacionados