Skip to main content
Glama
mcp-server-demo

mcp-server-demo

by mcvalosborne

mcp-server-demo

A small Model Context Protocol server written in TypeScript. It speaks MCP over stdio, so a local client such as Claude Desktop or the MCP Inspector can launch it as a child process and call three example tools: counting words, converting a few units, and reading the title of a web page.

Architecture

flowchart LR
  Client["MCP client"] <--> Stdio["stdio"]
  Stdio <--> Server["MCP server"]
  Server <--> WordCount["word_count"]
  Server <--> ConvertUnits["convert_units"]
  Server <--> FetchTitle["fetch_page_title"]
  Server <--> Info["server-info"]

The client sends JSON-RPC on stdin and reads responses from stdout. The server registers each tool with a Zod input schema and validates arguments before the handler runs. One static resource, info://server, describes the server. Diagnostic logs go to stderr so they stay out of the protocol stream.

Related MCP server: toolbox-mcp

Tools

Tool

What it does

Arguments

word_count

Counts words, Unicode characters, non-whitespace characters, and lines.

text (string)

convert_units

Converts a number within length, weight, or temperature.

value (number), from (string), to (string)

fetch_page_title

Fetches an http(s) URL and returns the document title, final URL, and status code.

url (string), timeoutMs (optional integer, 100–15000, default 8000)

convert_units accepts mm, cm, m, km, in, ft, yd, mi; mg, g, kg, oz, lb; and C, F, K, plus ordinary names such as meter and pound. Units from different categories are rejected.

fetch_page_title allows only http and https. It rejects loopback, link-local, and private addresses, and names that resolve to those addresses, including on redirects. The request aborts at the timeout. Body reading stops at the title element or at 64 KiB. The check uses the addresses returned for that lookup; it does not re-check if DNS changes before the connection is made.

The server-info resource at info://server returns the server name, version, and tool list as JSON.

Quick start

Requires Node.js 20 or newer.

npm install
npm run build
npm test
npm start

npm start runs node dist/index.js and waits on stdin for a client. To open the server in MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

npm run dev runs the TypeScript entry with tsx, without a separate build. npm test runs the Vitest unit tests. npm run build compiles src/ to dist/.

Claude Desktop

Add the server to the Claude Desktop config file: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows. Use the absolute path to dist/index.js.

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-demo/dist/index.js"]
    }
  }
}

Restart Claude Desktop after saving the file.

Project structure

src/
  index.ts                 stdio entry point
  server.ts                creates the MCP server and registers tools
  tools/word-count.ts
  tools/convert-units.ts
  tools/fetch-page-title.ts
tests/                     unit tests for the tool functions, plus a client smoke test

Adding a tool

  1. Add src/tools/your-tool.ts. Export the pure function, a Zod object schema, and a register function.

  2. Call that register function from createServer in src/server.ts.

  3. Add a test under tests/ for the pure function.

  4. Run npm test and npm run build.

import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const input = z.object({
  name: z.string().describe("Name to greet."),
});

export function registerGreet(server: McpServer): void {
  server.registerTool(
    "greet",
    { description: "Return a greeting.", inputSchema: input },
    async ({ name }) => ({
      content: [{ type: "text", text: `Hello, ${name}.` }],
    }),
  );
}

License

Released under the MIT License. See LICENSE.

Available Tools

3 tools
convert_unitsConvert unitsA
Read-onlyIdempotent

Convert a number between units in the same category. Length: mm, cm, m, km, in, ft, yd, mi. Weight: mg, g, kg, oz, lb. Temperature: C, F, K. Names such as meter, pound, and celsius are accepted. Units from different categories cannot be converted.

Inputs: to (required), from (required), value (required).

fetch_page_titleFetch page titleA
Read-only

Fetch an http or https URL and return its document title, final URL, and status code. Loopback, link-local, and private hosts are rejected, including names that resolve to those addresses. Redirects are checked the same way. The request times out, and reading stops after the title or 64 KiB.

Inputs: url (required), timeoutMs.

word_countWord countA
Read-onlyIdempotent

Count words, characters, and lines in text. Words are runs of non-whitespace. Characters are Unicode code points. Lines are separated by newlines, and a trailing newline does not add an extra line.

Inputs: text (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools target completely different tasks: text statistics, unit conversion, and URL title retrieval. Their descriptions make the boundaries explicit, so an agent should not confuse them.

    Naming Consistency4/5

    All names use snake_case and are readable, but word_count is noun-first while convert_units and fetch_page_title are verb-first. This is a minor deviation from a consistent verb_noun pattern.

    Tool Count5/5

    Three tools is a well-scoped size for a demo server, and each tool has a clear standalone purpose. There is no bloat or obviously missing core tool for the stated utility surface.

    Completeness4/5

    Each tool is self-contained: word_count returns basic text stats, convert_units covers common length/weight/temperature units, and fetch_page_title returns title/metadata. Gaps such as full page content extraction or broader conversion categories are minor and outside the stated scope.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers