Skip to main content
Glama
enesjakozh
stevennevins

MCP Server Template

by stevennevins
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

MCP Server Template

A template for creating Model Context Protocol (MCP) servers in TypeScript. This template provides a solid foundation for building MCP-compatible servers with proper tooling, type safety, and best practices.

Features

  • 🚀 Full TypeScript support

  • 🏗️ Container-based dependency injection

  • 📦 Service-based architecture with DataProcessor interface

  • 🛠️ Example tool implementation with tests

  • 🧪 Vitest testing framework

  • 📝 Type definitions

  • 🔌 MCP SDK integration

Related MCP server: MCP Server Template

Getting Started

Development

  1. Install dependencies:

    npm install

  2. Start the development server with hot reload:

    npm run dev

  3. Build the project:

    npm run build

  4. Run tests:

    npm test

  5. Start the production server:

    npm start

Project Structure

src/
├── index.ts          # Entry point
├── interfaces/       # Interface definitions
│   └── tool.ts      # DataProcessor interface
└── tools/           # Tool implementations
    └── example.ts   # Example tool

Creating Tools

  1. Export your tool and handlers following the example in src/tools/example.ts:

    // In your-tool.ts
export const YOUR_TOOLS = [
  {
    name: "your-tool-name",
    description: "Your tool description",
    parameters: {
      // Your tool parameters schema
    },
  },
];

export const YOUR_HANDLERS = {
  "your-tool-name": async (request) => {
    // Your tool handler implementation
    return {
      toolResult: {
        content: [{ type: "text", text: "Result" }],
      },
    };
  },
};

  2. Register your tool in the ALL_TOOLS and ALL_HANDLERS constants in src/index.ts:

    // In src/index.ts
import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";

// Combine all tools
const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS];
const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };

The server will automatically:

  • List your tool in the available tools

  • Handle input validation

  • Process requests to your tool

  • Format responses according to the MCP protocol

Testing

The template includes a built-in TestClient for local testing and the MCP Inspector for visual debugging.

Using TestClient

The TestClient provides a simple way to test your tools:

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

Using MCP Inspector

The template includes the MCP Inspector for visual debugging of your tools:

  1. Start the inspector:

    npx @modelcontextprotocol/inspector node dist/index.js

  2. Open the inspector UI at http://localhost:5173

The inspector provides:

  • Visual interface for testing tools

  • Real-time request/response monitoring

  • Tool metadata inspection

  • Interactive testing environment

Local Testing with Cursor

To test your MCP server locally with Cursor:

  1. Build and link the package:

    npm run build
npm run link

  2. Verify the binary works:

    npx example-mcp-tool

  3. Add the server to Cursor:

    • Open Cursor settings

    • Navigate to the Features tab

    • Scroll down to MCP Servers section

    • Click "Add Server"

    • Select "Command" type

    • Give it a name (e.g., "Local Example Tool")

    • Enter the command: npx example-mcp-tool

    • Click Confirm

  4. Verify the server starts correctly in Cursor by checking the MCP Servers section shows your server as running.

Note: If you make changes to your code, remember to rebuild and relink:

npm run build
npm run link

When you're done testing, you can unlink the package:

npm run unlink

This will remove the global symlink created during development.

Available Tools

1 tool
example-toolC

An example tool that processes input data

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesInput string to process

TDQS

C2.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 the full burden of behavioral disclosure. It states the tool 'processes input data', which implies some action but doesn't reveal behavioral traits like whether it's read-only, destructive, requires authentication, has side effects, or rate limits. This leaves significant gaps in understanding how the tool behaves.

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

Conciseness4/5

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

The description is a single, efficient sentence with no wasted words, making it appropriately concise. However, it's front-loaded with the basic purpose but lacks structure or additional details that could enhance clarity, keeping it simple but under-specified.

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

Completeness2/5

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

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is incomplete. It doesn't explain what 'processes' means, the expected output, or behavioral context, leaving the agent with insufficient information to use the tool effectively despite the straightforward schema.

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?

The description adds no specific meaning about the 'input' parameter beyond what the schema provides, which has 100% coverage and describes it as 'Input string to process'. With high schema coverage, the baseline is 3, as the schema adequately documents the parameter, and the description doesn't compensate or add further semantics.

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

Purpose3/5

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

The description states the tool 'processes input data', which provides a basic purpose but is vague about what 'processes' entails. It doesn't specify the type of processing or outcome, and with no sibling tools, differentiation isn't needed. This is a minimal viable description that communicates a general function without specifics.

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

Usage Guidelines2/5

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

The description offers no guidance on when to use this tool, such as context, prerequisites, or alternatives. With no sibling tools, it doesn't need to distinguish from others, but it lacks any usage instructions or scenarios, leaving the agent without direction on appropriate application.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.8/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools, as there are no other tools to compare it against. The single tool's purpose is clearly defined, eliminating any ambiguity in tool selection.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect—there are no other tools to create inconsistency. The tool name 'example-tool' follows a simple, clear pattern without any conflicting conventions to evaluate.

Tool Count2/5

A single tool is generally too few for a server's purpose, as it limits functionality and suggests an incomplete or trivial implementation. For a server named 'MCP Server Template', one tool feels insufficient to demonstrate a coherent set of capabilities, making it borderline inadequate.

Completeness1/5

The server's purpose is unclear from the name 'MCP Server Template', but with only one generic tool ('example-tool'), there are significant gaps in coverage. It lacks any CRUD operations, lifecycle management, or domain-specific functions, making it severely incomplete for any practical application.

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

Appeared in Searches

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/stevennevins/mcp-server-template'

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