@zuupee/mcp-server

General-purpose Model Context Protocol (MCP) server — a reusable foundation that exposes tools, resources, and prompts to AI clients (Cursor, Claude Desktop, MCP Inspector, etc.), with clear extension points for plugging in any backend or domain logic later.

Features

• stdio transport for local development (Cursor, Claude Desktop)

• Pluggable modules — add tools without touching core transport code

• Schema-first validation with Zod

• Built-in generic tools — HTTP fetch, JSON utilities, datetime helpers, server info

• Security defaults — deny-all HTTP host allowlist, read-only mode, secret redaction

• Structured logging to stderr (stdio-safe)

Related MCP server: Modular MCP Server

Quick start

Prerequisites

• Node.js 22+

• pnpm 9+

Setup

pnpm install
cp .env.example .env.local
pnpm dev

Cursor configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-server": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/mcp-server", "dev"],
      "env": {
        "MCP_MODULES": "meta,http,json,datetime",
        "READ_ONLY": "true",
        "HTTP_TOOL_ALLOWED_HOSTS": "api.github.com,httpbin.org"
      }
    }
  }
}

Built-in tools

Configuration

Environment variables (see .env.example):

CLI flags override env:

mcp-server --transport stdio --modules meta,http --read-only

Adding a custom module

1. Create plugins/my-service/index.ts implementing McpModule

2. Register tools that call your backend via ctx.http or ctx.secrets

3. Wire the module into MCP_MODULES (Phase 4 adds dynamic plugin loading)

See plugins/example/index.ts and docs/build-plan.md for the full extension guide.

Scripts

pnpm dev        # stdio server (tsx)
pnpm build      # compile to dist/
pnpm start      # run built bin
pnpm test       # unit + integration tests
pnpm inspect    # MCP Inspector against stdio
pnpm lint       # ESLint (no console.log in src/)

Architecture

src/
├── index.ts          # CLI entry
├── server.ts         # McpServer factory + instructions
├── config.ts         # env + CLI parsing
├── context.ts        # per-request context
├── registry/         # module registration
├── transport/        # stdio (http in Phase 3)
├── middleware/       # auth, read-only, audit logging
├── modules/          # built-in: meta, http, json, datetime
└── lib/              # errors, format, schema, result helpers

License

MIT