MCP Server Starter
starter-series/mcp-server-starter
Bootstrap de servidor MCP com TypeScript, OIDC publish e CI/CD zero-config
Ver no GitHubTemplate pronto para desenvolvimento de servidores MCP (Model Context Protocol) com TypeScript, CI/CD automatizado e publicação OIDC no npm sem necessidade de secrets. Inclui padrões de segurança, validação com Zod e análise estática de código.
Instalação
npx convez-ai starter-series/mcp-server-starter1 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
Casos de uso
- Criar novo servidor MCP para integração com Claude
- Publicar tools reutilizáveis no npm com pipeline seguro
- Implementar recursos e prompts para o protocolo MCP
Veredito

Starter robusto e bem-estruturado para quem precisa lançar servidores MCP produção-ready. A cobertura de CI/CD com OIDC, segurança estática e padrões de validação elimina decisões arquiteturais repetitivas — ideal para times que valorizam ship-first com confiança.
README
A tradução para o português deste README ainda está na fila.
MCP Server Starter
TypeScript + OIDC npm Publishing + CI/CD.
Build your MCP server. One-click publish. Zero secrets needed.
English | 한국어
Part of Starter Series — Stop explaining CI/CD to your AI every time. Clone and start.
Docker Deploy · Discord Bot · Telegram Bot · Browser Extension · Electron App · npm Package · React Native · VS Code Extension · MCP Server · Python MCP Server · Cloudflare Pages
About This Starter
Currently implemented
- MCP SDK —
@modelcontextprotocol/sdkwith stdio transport - TypeScript — Strict mode (incl.
noUncheckedIndexedAccess+verbatimModuleSyntax), ES2023 target, Zod-validated input & output schemas - Safety annotations — readOnly/destructive/idempotent hints on every tool
- Prompts — Guided workflow templates via
registerPrompt(SDK v1.29+) - Resources — Data exposure pattern with metadata + handler
- Response helpers —
ok()anderr()for consistent tool responses - Config — Environment variable parsing pattern
- CI — gitleaks, npm audit, license compliance, ESLint, build, test
- CodeQL — Static security analysis (push/PR + weekly)
- CD — OIDC trusted publishing to npm (zero secrets needed)
- Dependabot — Automated dependency + GitHub Actions updates
Planned
Nothing on a public roadmap. The starter is intentionally finished; downstream projects extend it. Breaking-change waves (Node EOL, SDK majors) land via Dependabot.
Design intent
Bootstrap a publishable MCP server in under a minute. Stdio is the default because every local MCP client speaks it; HTTP transport is shown inline (see below) rather than bundled, to keep the dependency surface minimal. OIDC publishing means contributors never paste an npm token. Globally-unique tool names are enforced by convention — prefix with your module name, since name collisions across servers are the most common foot-gun.
Non-goals
- Auth primitives, HMAC signing, rate-limiting, audit logging, human-in-the-loop infra. Those belong in a host, not a server template.
- Express / HTTP transport in the default scaffold. Template stays small; HTTP is documented for those who need it.
- Opinionated logging, tracing, or observability stack. Pick what fits downstream.
Redacted
None. Public template.
Quick Start
Via create-starter (recommended):
npx @starter-series/create my-mcp-server --template mcp-server
cd my-mcp-server && npm install && npm run dev
Or clone directly:
git clone https://github.com/starter-series/mcp-server-starter my-mcp-server
cd my-mcp-server && npm install && npm run dev
Adding Tools
Tool names must be globally unique across all MCP servers a client connects to. Prefix with your module name (e.g.,
mymodule_actioninstead ofaction).
Create src/tools/your-tool.ts:
import { z } from 'zod';
import { ok, err } from '../helpers.js';
export const name = 'your_tool';
export const config = {
title: 'Your Tool',
description: 'What your tool does',
inputSchema: {
input: z.string().describe('Input parameter'),
},
// Declare `outputSchema` to return structured results — the 2026 MCP spec
// requires servers to populate `structuredContent` (validated against this
// schema) alongside the text mirror. Omit `outputSchema` for free-form
// text-only tools.
outputSchema: {
result: z.string().describe('Processed value'),
},
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
},
};
export async function handler({ input }: { input: string }) {
try {
const result = `Processed: ${input}`;
// Pass the structured payload as the second arg to `ok()` — it's set as
// `structuredContent` alongside the text mirror in `content[]`.
return ok(result, { result });
} catch (e) {
return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
}
}
Register in src/index.ts:
import * as yourTool from './tools/your-tool.js';
server.registerTool(yourTool.name, yourTool.config, yourTool.handler);
Adding Prompts
Prompts are reusable, parameterized message templates the client can surface to the user or feed to the model. Use registerPrompt (SDK v1.29+) for full control — title + description + Zod-validated argsSchema. See src/prompts/code-review.ts for a templated example.
Create src/prompts/your-prompt.ts:
import { z } from 'zod';
export const name = 'your-prompt';
export const title = 'Your Prompt';
export const description = 'Guided workflow description';
export const argsSchema = {
param: z.string().min(1).describe('Required parameter'),
};
export function handler({ param }: { param: string }) {
return {
description,
messages: [{
role: 'user' as const,
content: { type: 'text' as const, text: `Prompt text with ${param}` },
}],
};
}
Register in src/index.ts:
import * as yourPrompt from './prompts/your-prompt.js';
server.registerPrompt(
yourPrompt.name,
{ title: yourPrompt.title, description: yourPrompt.description, argsSchema: yourPrompt.argsSchema },
yourPrompt.handler,
);
Adding Resources
Resources expose data to the client (Tools perform actions). See src/resources/server-info.ts for a working example.
Create src/resources/your-resource.ts:
export const name = 'your-resource';
export const uri = 'info://your/resource';
export const metadata = {
title: 'Your Resource',
description: 'What this resource exposes',
mimeType: 'application/json',
};
export async function handler(resourceUri: URL) {
return {
contents: [{ uri: resourceUri.href, mimeType: metadata.mimeType, text: '...' }],
};
}
Register in src/index.ts:
import * as yourResource from './resources/your-resource.js';
server.registerResource(yourResource.name, yourResource.uri, yourResource.metadata, yourResource.handler);
HTTP Transport
This starter uses stdio (the standard for local MCP servers). If you need HTTP transport — for registries like Smithery/mcp.so or remote deployments — use StreamableHTTPServerTransport with Express:
import express from 'express';
import { randomUUID } from 'node:crypto';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
const app = express();
app.use(express.json());
const sessions = new Map<string, StreamableHTTPServerTransport>();
app.post('/mcp', async (req, res) => {
const sessionId = req.headers['mcp-session-id'] as string;
const existing = sessions.get(sessionId);
if (existing) {
await existing.handleRequest(req, res);
return;
}
if (!isInitializeRequest(req.body)) {
res.status(400).json({ error: 'Bad Request: Not an initialize request' });
return;
}
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => randomUUID(),
});
transport.onclose = () => {
const id = transport.sessionId;
if (id) sessions.delete(id);
};
const server = createServer(); // your McpServer factory
await server.connect(transport);
if (transport.sessionId) sessions.set(transport.sessionId, transport);
await transport.handleRequest(req, res);
});
app.get('/mcp', async (req, res) => {
const t = sessions.get(req.headers['mcp-session-id'] as string);
if (!t) return res.status(400).end();
await t.handleRequest(req, res);
});
app.delete('/mcp', async (req, res) => {
const t = sessions.get(req.headers['mcp-session-id'] as string);
if (!t) return res.status(400).end();
await t.handleRequest(req, res);
});
app.listen(3000);
Why the complexity? Without
isInitializeRequest, every POST creates a new transport → "Already connected" errors. Without GET, clients can't receive server notifications via SSE.
Stateless mode — if your server holds no per-session state (every tool call is independent), construct the transport with sessionIdGenerator: undefined and skip the session map. Stateless is simpler to deploy behind a stateless load balancer and is the recommended default for serverless hosts (Cloudflare Workers, Vercel functions). Keep the stateful pattern above only if you need server-initiated notifications or per-session caches.
See the MCP SDK docs for full details.
Testing Locally
MCP Inspector
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"my-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"]
}
}
}
After Publishing to npm
{
"mcpServers": {
"my-mcp-server": {
"command": "npx",
"args": ["-y", "my-mcp-server"]
}
}
}
CI/CD
CI (every push/PR)
- Secret scanning (gitleaks)
- Large file detection (>5 MB)
- License compliance (blocks GPL/AGPL)
- Security audit (
npm audit) - Lint (ESLint + TypeScript)
- Build (TypeScript compilation)
- Test (Jest)
Security & Maintenance
| Workflow | What it does |
|---|---|
CodeQL (codeql.yml) | Static analysis for security vulnerabilities (push/PR + weekly) |
Maintenance (maintenance.yml) | Weekly CI health check — auto-creates issue on failure |
Stale (stale.yml) | Labels inactive issues/PRs after 30 days, auto-closes after 7 more |
CD (manual trigger)
- CI gate (must pass)
- Version guard (prevents duplicate releases)
- npm publish with OIDC + provenance
- GitHub Release
Setup: See docs/NPM_PUBLISH_SETUP.md — trusted publishers configured on/after 2026-05-20 must select npm publish as an allowed action, or releases fail with an authorization error.
Project Structure
src/
├── index.ts # Server entry — tool/resource/prompt registration + transport
├── config.ts # Environment variable config
├── helpers.ts # ok() / err() response helpers
├── tools/
│ └── greet.ts # Example tool with annotations (replace with your own)
├── resources/
│ └── server-info.ts # Example resource exposing server metadata (replace)
└── prompts/
├── hello.ts # Zero-arg prompt example (replace with your own)
└── code-review.ts # Templated prompt with Zod-validated args
tests/
├── greet.test.js # Tool tests
├── helpers.test.js # Helper tests
├── server-info.test.js # Resource tests
├── hello.test.js # Prompt tests
└── code-review.test.js # Templated prompt tests
Scripts
| Command | Description |
|---|---|
npm run dev | Run with tsx (no build needed) |
npm run build | Compile TypeScript |
npm start | Run compiled server |
npm test | Build + run tests (pretest auto-builds) |
npm run lint | ESLint |
npm run version:patch | Bump patch version |
License
MIT