typescript-mcp-server-demo

Node.js / TypeScript MCP-style tool server skeleton for startups wiring agent tools. Exposes list_tools + call_tool (JSON-RPC 2.0) over stdio or HTTP JSON. No API keys required — tools are local stubs suitable for demos and integration tests.

Why this shape

Protocol-light on purpose: integrate a tool plane without locking to one MCP SDK version. Swap handlers for real CRM / billing / support APIs when you harden.

Related MCP server: wazza-mcp-test-server

Tools

Demo CRM ids: cust_1001, cust_1002, cust_1003.

Architecture

Client (agent / IDE)
   |
   |- stdio: one JSON-RPC object per line on stdin -> stdout
   |- HTTP: /health /tools /rpc /tools/call
              |
              v
        handleRequest() -> ToolRegistry -> echo | get_time | fake_crm_lookup

Requirements

• Node.js 18+

• package manager compatible with the lockfile-free package.json in this repo

Setup

Install dependencies, optionally copy the env example file, then build TypeScript to dist/. Scripts are defined in package.json: build, start, start:http, start:stdio, dev, dev:http, test.

Run

Set MCP_TRANSPORT to http (port via MCP_PORT, default 3100) or stdio (default).

HTTP routes:

• GET /health — liveness

• GET /tools — list_tools shortcut

• POST /rpc — full JSON-RPC body

• POST /tools/call — body with name and arguments

Example tools/call body:

{"name":"echo","arguments":{"message":"hello"}}

Example JSON-RPC call_tool:

{"jsonrpc":"2.0","id":1,"method":"call_tool","params":{"name":"fake_crm_lookup","arguments":{"customerId":"cust_1001"}}}

Test

Run the package.json test script. Uses Node built-in test runner (node:test) via tsx.

Config

See .env.example.

Project layout

src/
  index.ts
  server.ts
  types.ts
  tools/ (echo, get-time, fake-crm-lookup, index)
  transports/ (stdio, http)
tests/
  tools.test.ts
  server.test.ts

Integrating into a startup agent stack

1. Discover tools at boot (GET /tools or list_tools) and cache schemas for the LLM tool-calling layer.

2. Call tools from your agent loop with structured arguments; surface content[].text to the model and data to your app layer.

3. Replace fake_crm_lookup with a real CRM client behind the same RegisteredTool interface — keep names/schemas stable for prompts.

4. Lock down HTTP with authn/authz and network policy before production; prefer stdio or private mesh for privileged tools.

5. Graduate to a full MCP SDK transport when you need resources/prompts/sampling; this skeleton stays focused on the tool plane.

License

MIT — see LICENSE.

Author: tanvir-ux