Skip to main content
Glama
abe-source

MCP TypeScript Boilerplate

by abe-source
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

MCP TypeScript Boilerplate

A starting point for building MCP servers with the official @modelcontextprotocol/sdk, no wrapper framework. Extracted from a working, published server (mcp-abuseipdb).

Layers

src/
  config.ts           env loading + validation — API key, base URL, timeout
  client.ts            generic fetch wrapper — no domain knowledge, rarely needs changes
  apiClient.ts          adds this API's auth header + error unwrapping, on top of client.ts
  endpoints/            one file per API endpoint you call — HTTP shape only
    example.ts
  tools/
    types.ts           the Tool interface every tool file implements
    example.ts          one tool: schema + handler, calls into endpoints/
    index.ts             tool registry — tools[] array
  server.ts             wires the tool registry into an McpServer instance
  index.ts               entrypoint: loadConfig() → createServer() → connect stdio transport

Related MCP server: TypeScript MCP Server Boilerplate

Adapting this to a new service

  1. src/config.ts — rename API_KEY to <SERVICE>_API_KEY, set the real BASE_URL

  2. src/apiClient.ts — match the target API's auth scheme (header name, Bearer vs custom) and error response shape

  3. src/endpoints/ — one function per endpoint, delete example.ts

  4. src/tools/ — one tool per file (schema + result formatting), delete example.ts, register real tools in tools/index.ts

  5. package.json — rename, update bin, description, repo URLs

Build

npm install
cp .env.example .env   # fill in API_KEY
npm run build
npm start

Design notes

  • client.ts has zero domain knowledge — it should not need to change between projects

  • apiClient.ts is the only layer that knows about auth and this API's error format

  • endpoints/ returns typed data, tools/ formats that data as MCP content — don't blend the two

  • stdio transport, so this works with Claude Desktop, Claude Code, and any other MCP-compatible client without extra setup

Available Tools

1 tool
get_exampleA

Fetch an example resource by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesResource ID to look up

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It fails to mention any side effects, authorization needs, or response format. For a read operation, at least the idempotent nature should be hinted.

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?

Single sentence with no wasted words. Perfectly concise and directly gets to the point without any fluff.

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

Completeness4/5

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is mostly complete. It could mention what is returned, but without an output schema, the current description suffices.

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

Parameters3/5

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

Schema coverage is 100% and the schema already describes the parameter as 'Resource ID to look up'. The description adds only 'by ID', which does not provide additional meaning beyond the schema. Baseline score of 3 is appropriate.

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?

Description clearly states the verb 'Fetch' and the resource 'example resource' with method 'by ID', making the tool's purpose unambiguous. No siblings to differentiate from, but the purpose is specific.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives. Since there are no sibling tools, the description is minimally adequate but lacks any context about prerequisites or when not to use it.

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 updatev1.0.0
    • First observedget_example
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

There is only one tool, so no ambiguity exists. An agent cannot confuse it with another tool.

Naming Consistency5/5

With a single tool, naming consistency is not a concern; there is no inconsistency to evaluate.

Tool Count4/5

As a boilerplate server, one tool is appropriate for its demonstration purpose. It is minimal but not unreasonable.

Completeness3/5

For a boilerplate, the single tool serves as an example. However, it lacks any create, update, or delete operations, which limits its completeness.

Maintenance

ActivitySlowing
ResponsivenessSyncing

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

  • TypeScript MCP Server

    you0best
    F
    license
    Not graded
    quality
    D
    maintenance
    A boilerplate project for quickly developing MCP servers using TypeScript SDK, with example implementations of calculator and greeting tools, plus resource handling capabilities.
    -

  • TypeScript MCP Server

    kimhailey
    F
    license
    A
    quality
    D
    maintenance
    A boilerplate for building MCP servers using TypeScript, with example tools like calculator and greet, plus resource support.
    6
    -

  • my-mcp-server

    Gwyn-Ahchoo
    F
    license
    B
    quality
    D
    maintenance
    A TypeScript MCP server boilerplate providing example tools and resources for rapid development of custom Model Context Protocol servers.
    8
    -

  • toni-mcp-server

    toni0402-han
    F
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript MCP server boilerplate providing example tools and resources for rapid development and testing of Model Context Protocol servers.
    -

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/abe-source/mcp-typescript-boilerplate'

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