@xylent_ai/mcp-typescript

Production-ready Model Context Protocol client and server toolkit for TypeScript/Node.js, covering Streamable HTTP transports, retries, auth, and Express integration.

Features

• Streamable HTTP client with lazy connections, per-call timeouts, retry/backoff, and capability negotiation.
• Registry-friendly server toolkit: drop-in StreamableMCPServer for Streamable HTTP, plus attachMcp for Express apps with auth and CORS.
• Authentication: Client auth (Basic/Bearer) plus server-side BasicAuth/NoAuth.
• Tools & resources: Register tools (Zod schemas) and, optionally, resources/templates on the server; list/call/read/subscribe from the client.
• Type-safe: Full TypeScript definitions; dynamic package version is sent in the MCP handshake.
• Examples included for both client and server usage.

Installation

# Client only
npm install @xylent_ai/mcp-typescript

# Server (Express) helpers
npm install @xylent_ai/mcp-typescript express
npm install -D @types/express

Quick Start

Streamable HTTP Client

import { StreamableMCPClient } from '@xylent_ai/mcp-typescript/mcp';

async function main() {
  const client = new StreamableMCPClient({
    baseUrl: 'http://localhost:3000', // will append /mcp if missing
    name: 'demo-client',
    timeout: 30_000,
  });

  try {
    const tools = await client.listTools();
    console.log(
      'Tools:',
      tools.tools?.map((t) => t.name)
    );

    const result = await client.callTool('echo', { text: 'hello world' });
    console.log('Result:', result);
  } finally {
    await client.close();
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Streamable HTTP Server (Express)

import express from 'express';
import { z } from 'zod';
import { StreamableMCPServer } from '@xylent_ai/mcp-typescript/mcp';

const app = express();
app.use(express.json());

const capabilities = {
  tools: {
    echo: {
      name: 'echo',
      description: 'Echo back text',
      category: 'utility',
      schema: z.object({ text: z.string() }),
      handler: async ({ text }) => ({
        content: [{ type: 'text', text }],
      }),
    },
  },
};

const server = new StreamableMCPServer({
  serverInfo: { name: 'demo-mcp-server' },
  serverOptions: { capabilities },
});

// Streamable MCP endpoint
app.post('/mcp', server.handlePost);

app.listen(3000, () => console.log('MCP server on http://localhost:3000/mcp'));

Express Helper (attachMcp)

Prefer a one-liner integration with auth/CORS built-in:

import express from 'express';
import { z } from 'zod';
import { attachMcp, BasicAuth } from '@xylent_ai/mcp-typescript/serverkit';

const app = express();
app.use(express.json());

const capabilities = {
  tools: {
    calc: {
      name: 'calc',
      description: 'Add numbers',
      category: 'math',
      schema: z.object({ a: z.number(), b: z.number() }),
      handler: async ({ a, b }) => ({
        content: [{ type: 'text', text: String(a + b) }],
      }),
    },
  },
};

attachMcp(app, {
  name: 'calc-service',
  capabilities,
  path: '/mcp',
  cors: true,
  auth: new BasicAuth(process.env.BASIC_USERNAME!, process.env.BASIC_PASSWORD!),
});

app.listen(3000, () => console.log('MCP service ready'));

Authentication

• Client: pass auth or transportOptions to StreamableMCPClient.
• Server: attachMcp defaults to NoAuth with a warning; StreamableMCPServer can sit behind any Express auth middleware.

const client = new StreamableMCPClient({
  baseUrl: 'http://localhost:3000',
  name: 'demo-client',
  auth: { type: 'basic', username: 'service-eval', password: 'secret123' },
  // Or: auth: { type: 'bearer', token },
});

Examples

• src/examples/attach-mcp-express.md
• src/examples/streamable-client.md
• src/examples/streamable-server.md

Development

npm install
npm run build
npm run lint
npm run format
npm run dev

License

Proprietary - Xylent Internal Use Only

Author

Santiago Blankleider [email protected]