Skip to main content
Glama
mxrsoon

mcp-server-base-nodejs

by mxrsoon
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

mcp-server-base-nodejs

Base de servidor MCP em TypeScript com a DX do FastMCP: você escreve um método de classe normal, com tipos normais e JSDoc, e ele vira uma tool com JSON Schema, outputSchema e validação — sem escrever schema à mão.

export class ClockService {
  /**
   * Retorna a hora atual do servidor em UTC.
   *
   * Use quando precisar do instante presente para datar um registro,
   * calcular um intervalo ou resolver expressões como "hoje" e "agora".
   */
  public async now(): Promise<IUtcNow> {
    const date = new Date();
    return { iso: date.toISOString(), epochMillis: date.getTime(), timeZone: "UTC" };
  }
}

O JSDoc do método vira a description da tool. O tipo do parâmetro vira o input schema. O tipo de retorno vira o outputSchema. Nada é duplicado.

Como funciona

Tipos TypeScript são apagados no build e JSDoc não existe em runtime, então a extração acontece em tempo de compilação, via o transform do typia rodando dentro do ttsc (drop-in do tsc).

src/tools/ClockService.ts   →  typia.llm.controller<ClockService>()  →  createMcpServer()
     classe + JSDoc                 schemas gerados no build              servidor MCP

O @typia/mcp também valida os argumentos de cada chamada e, quando o modelo erra, devolve o erro de validação em formato que ele consegue corrigir sozinho.

Related MCP server: TypeSpec MCP Server

Requisitos

  • Node.js >= 20

  • Go instalado (o transform nativo do typia é compilado uma vez e fica em cache)

Uso

npm install
npm run build      # ttsc
npm start          # node dist/index.js (stdio)

Durante o desenvolvimento:

npm run dev        # ttsx src/index.ts
npm run typecheck  # ttsc --project tsconfig.test.json
npm test           # smoke test das tools
npm run inspect    # MCP Inspector apontando para o build

⚠️ tsc, ts-node e tsx não aplicam o transform. Use sempre ttsc / ttsx. Se o servidor subir e as tools vierem vazias, quase sempre é isso.

Registrando no cliente

{
  "mcpServers": {
    "base": {
      "command": "node",
      "args": ["/caminho/absoluto/mcp-server-base-nodejs/dist/index.js"]
    }
  }
}

Adicionando uma tool

  1. Crie um método público na classe de serviço (ou uma nova classe em src/tools/).

  2. Documente com JSDoc — a primeira frase é o resumo que o modelo lê.

  3. Tipe entrada e saída. Restrições viram schema:

import { tags } from "typia";

/** Converte um instante UTC para outro fuso horário. */
public async convert(props: {
  /** Instante de origem, em ISO 8601. */
  iso: string & tags.Format<"date-time">;
  /** Fuso de destino, no formato IANA. Ex.: `America/Sao_Paulo`. */
  timeZone: string & tags.MinLength<1>;
}): Promise<{ iso: string; timeZone: string }> {
  // ...
}

tags.Format<"date-time"> vira "format": "date-time", tags.MinLength<1> vira "minLength": 1, união de literais vira enum. Métodos recebem um único objeto de parâmetros.

Para uma nova classe, registre em src/server.ts.

Testes

npm test sobe o servidor via InMemoryTransport, lista as tools e verifica que a descrição veio do JSDoc e o outputSchema veio do tipo de retorno.

Isso existe por causa de um modo de falha específico: quando o build pula o ttsc, nada quebra — o servidor sobe normalmente, só que sem tool alguma. Uma compilação verde não pega isso; o teste pega.

Estrutura

src/
├── index.ts              # entrypoint, conecta no transporte stdio
├── server.ts             # monta o McpServer a partir das classes de tools
└── tools/
    └── ClockService.ts   # exemplo: hora atual em UTC
test/
└── tools.test.ts         # prova que a inferência aconteceu

Trade-offs

Vale saber antes de adotar em produção:

  • Depende do toolchain. Qualquer caminho de build que pule o ttsc (SWC, Babel, nest build, bundler sem @ttsc/unplugin) gera um servidor sem schemas. É o atrito principal em monorepo.

  • Sem decorator em função solta. Decorators só alcançam classe e método, por isso a classe funciona como namespace de tools.

  • Alternativa sem transform: Zod/Standard Schema no SDK oficial, com .describe() no lugar do JSDoc. Inverte a direção — o schema vira a fonte da verdade e o tipo é inferido dele. Menos ergonômico, zero build mágico.

Licença

MIT

Available Tools

1 tool
nowA

Retorna a hora atual do servidor em UTC.

Use quando precisar do instante presente para datar um registro, calcular um intervalo ou resolver expressões relativas como "hoje" e "agora". O valor não depende do fuso horário do cliente.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
isoYesData e hora em ISO 8601, sempre com sufixo `Z`.
timeZoneYesFuso horário da resposta. Sempre `UTC`.
epochMillisYesMilissegundos decorridos desde a época Unix (1970-01-01T00:00:00Z).

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It transparently states that the value is the server time in UTC and does not depend on the client's timezone, which is the key behavioral trait.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each earning its place: what it returns, when to use it, and a key behavioral guarantee. The main result is front-loaded and there is no redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is trivially simple, has no parameters, and has an output schema. The description covers purpose, use cases, and timezone behavior, leaving no meaningful gap for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. No parameter documentation is needed, and the description sensibly avoids inventing any.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Retorna'), resource ('hora atual do servidor'), and format ('em UTC'), making the tool's function unambiguous. There are no sibling tools, and the description clearly distinguishes server time from client-local time.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit use cases: dating a record, calculating an interval, and resolving relative expressions like 'hoje' and 'agora'. Since there are no sibling tools, no alternative routing is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observednow
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

There is only one tool, so there is no possibility of confusion or overlap with other tools. Its purpose is clearly described as returning the current UTC time.

Naming Consistency4/5

The name 'now' is simple and matches its function, but it does not follow the typical verb_noun pattern seen in many MCP servers. With only one tool, there is no inconsistency, but the naming is a slight deviation from standard conventions.

Tool Count1/5

A single tool that simply returns the current time is extremely thin for an MCP server. This falls into the 'single trivial tool' category, representing an extreme mismatch in scope.

Completeness1/5

The tool description mentions use cases like datestamping records, calculating intervals, and resolving relative expressions, but the server only provides a raw timestamp. There are no companion tools for calculations or conversions, making the surface severely incomplete for the implied domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • easy-mcp

    zcaceres
    A
    license
    Not graded
    quality
    C
    maintenance
    Simplifies creating MCP servers in TypeScript with an Express-like API and experimental decorators, enabling quick definition of tools, resources, and prompts.
    26
    196
    MIT

  • mcp-gen

    zodromon
    A
    license
    Not graded
    quality
    B
    maintenance
    Turn your typed TypeScript functions into an MCP server — tool, resource, and prompt schemas inferred from your types and JSDoc. No schema library, no decorators, no boilerplate.
    27
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mxrsoon/mcp-server-base-nodejs'

If you have feedback or need assistance with the MCP directory API, please join our Discord server