convez.ai
MCP Server
reaatech

mcp-server-starter-ts

reaatech/mcp-server-starter-ts

Ver no GitHub
BomPluginScore · de 0 a 100

Production-grade MCP server template — StreamableHTTP + SSE transports, Zod schemas, OTel instrumentation, idempotency middleware, prompt-injection sanitization, structured logging, Jest harness, Terraform for Cloud Run + AWS.

Instalação

$npx convez-ai reaatech/mcp-server-starter-ts

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
1
Acompanhando
0
Saúde
85%
Último commit
há 1 mês
Versão
@reaatech/mcp-server-auth@1.1.0
Issues abertas
6
Contribuidores
3

README

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

mcp-server-starter-ts

CI License: MIT TypeScript

Production-grade MCP (Model Context Protocol) server starter template in TypeScript. Built from Fortune-10 scale operational experience.

This monorepo provides core types, a server framework, pluggable middleware, observability, and transport layer — everything needed to build, secure, and operate an MCP server from day one.

Features

  • Core types & configuration — Zod-validated environment config, shared domain types, content block helpers
  • Server framework — Express 5 with composable middleware pipeline (auth, rate limit, idempotency, sanitization)
  • Pluggable auth — API key and Bearer token validation with timing-safe comparison
  • Tool system — Type-safe defineTool() helper, auto-discovery of .tool.ts files, built-in echo and health-check tools
  • Dual transports — Streamable HTTP (primary) + SSE (legacy) with session management and automatic cleanup
  • Observability — Pino structured logging with PII redaction, OpenTelemetry tracing, Prometheus-compatible metrics
  • Security middleware — Rate limiting (token bucket), request idempotency, prompt-injection input sanitization

Installation

Using the packages

Packages are published under the @reaatech scope and can be installed individually:

# Server framework (includes all middleware and transports)
pnpm add @reaatech/mcp-server-engine

# Core types and configuration
pnpm add @reaatech/mcp-server-core

# Authentication middleware (standalone)
pnpm add @reaatech/mcp-server-auth

# Tool registry and built-in tools
pnpm add @reaatech/mcp-server-tools

# Observability (logging, tracing, metrics)
pnpm add @reaatech/mcp-server-observability

# Transport layer (standalone)
pnpm add @reaatech/mcp-server-transport

Contributing

# Clone the repository
git clone https://github.com/reaatech/mcp-server-starter-ts.git
cd mcp-server-starter-ts

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run the test suite
pnpm test

# Run linting
pnpm lint

Quick Start

Create a minimal MCP server with built-in tools in under 10 lines:

import { startServer } from '@reaatech/mcp-server-engine';

// Built-in echo and health-check tools are available
// Auth, rate limiting, idempotency, and sanitization are configured
// Streamable HTTP and SSE transports are mounted
startServer();
PORT=8080 pnpm dev

See the examples/01-basic-server/ for the complete working example.

Packages

PackageDescription
@reaatech/mcp-server-coreCore types, Zod schemas, configuration, and version utilities
@reaatech/mcp-server-authPluggable authentication middleware
@reaatech/mcp-server-observabilityStructured logging, OpenTelemetry tracing, and metrics
@reaatech/mcp-server-transportFramework-agnostic MCP transports (Streamable HTTP, SSE) with Express & Fastify adapters
@reaatech/mcp-server-toolsTool registry, discovery, and built-in tools
@reaatech/mcp-server-engineMCP server framework (Express, middleware pipeline)

Tool Authoring

import { defineTool } from '@reaatech/mcp-server-tools';
import { z } from 'zod';
import { textContent } from '@reaatech/mcp-server-core';

export default defineTool({
  name: 'my-tool',
  description: 'Does something useful for the LLM',
  inputSchema: z.object({
    query: z.string().describe('The search query'),
  }),
  handler: async ({ query }, context) => {
    return {
      content: [textContent(`Results for: ${query}`)],
    };
  },
});

Tools are auto-discovered from .tool.ts files at startup via @reaatech/mcp-server-tools.

Deployment

Docker

docker build -t my-mcp-server .
docker run -p 8080:8080 -e API_KEY=your-key my-mcp-server

Environment Variables

VariableRequiredDefaultDescription
PORTNo8080Server port
NODE_ENVNodevelopmentEnvironment
API_KEYYes (prod)—Auth key
CORS_ORIGINNo*CORS allowed origins
AUTH_MODENoapi-keyapi-key or bearer
AUTH_BYPASS_IN_DEVNotrueSkip auth in dev when no key
RATE_LIMIT_RPMNo60Requests per minute per client
IDEMPOTENCY_TTL_MSNo300000Idempotency cache TTL (5 min)
SESSION_TIMEOUT_MSNo1800000MCP session expiry (30 min)
LOG_LEVELNoinfoPino log level
OTEL_EXPORTER_OTLP_ENDPOINTNo—OpenTelemetry collector URL
OTEL_SERVICE_NAMENomcp-serverService name in traces
OTEL_RESOURCE_ATTRIBUTESNo—Additional attributes (key=value,...)
SANITIZATION_DENY_PATTERNSNo—Extra sanitization patterns

Documentation

  • ARCHITECTURE.md — System design, package relationships, and data flows
  • AGENTS.md — Coding conventions and development guidelines
  • CONTRIBUTING.md — Contribution workflow and release process
  • docs/ — Deep dives on deployment, observability, security, and tool authoring

License

MIT

Ver o original no GitHub

Bom para

Relacionados