MCP server · TypeScript · LangChain

Minimal Model Context Protocol server in TypeScript with a LangChain / OpenAI assistant behind an MCP entrypoint (assist), plus thin tools for deterministic JSON (getWeather, addNumbers) and a TTS helper (textToSpeech). Exposes MCP over stdio (stdin/stdout JSON-RPC)—not Express/HTTP—for hosts like Cursor, Claude Desktop, or custom clients.

Why this repo

Demonstrates integrating external LLM tooling with a narrow MCP surface:

• MCP stdio transport + Zod-typed tool inputs

• Server-side routing: one NL entrypoint (assist) runs an internal agent; no extra “routing” tools on the wire

• LangChain createAgent with small domain tools (weather via Open-Meteo, math helpers)

• TypeScript strict mode, tsc build to dist/, demo scripts via tsx

Related MCP server: FastMCP Demo

Quick start

git clone <your-fork-url>
cd mcp-server
nvm use   # optional; reads .nvmrc (Node 20)
npm install
cp .env.example .env   # set OPENAI_API_KEY for assist
npm run build
npm start              # MCP on stdio (after pre-build)

Try the bundled demos (they build first, then spawn dist/mcp/index.js):

npm run chat -- "What is the weather in London? One short sentence."
npm run mcp:demo-client -- assist '{"message":"What is the weather in London? One short sentence."}'

Architecture

flowchart LR
  Host[MCP host] -->|stdio JSON-RPC| MCP[MCP server]
  MCP --> assist["tool: assist"]
  MCP --> getWeather["tool: getWeather"]
  MCP --> addNumbers["tool: addNumbers"]
  MCP --> textToSpeech["tool: textToSpeech (optional)"]
  assist --> Agent[LangChain agent + OpenAI]
  Agent --> W[Weather tool]
  Agent --> M[Math tools]
  getWeather --> API[Open-Meteo / geocoding]

Design choices

Hosts should send natural language through assist so prompts, tool boundaries, and model config stay on your machine. Structured integrations can call getWeather or addNumbers directly when inputs are already known (no NL).

OPENAI_API_KEY must be visible to the MCP server process for assist (e.g. .env loaded from dotenv, or env vars in your host’s MCP config—never commit secrets).

Layout

npm run build emits dist/ (listed in .gitignore).

Commands

Examples: run everything vs tools only

Run the whole agent system (natural language → assist → internal LangChain agent → final text):

npm run chat -- "What is the weather in London? How is 34+7?"

Same flow, but calling assist explicitly with an object payload:

npm run mcp:demo-client -- assist '{"message":"What is the weather in London? How is 34+7?"}'

Testing individual MCP tools (not required for the full agent):

npm run mcp:demo-client -- getWeather '{"city":"London"}'
npm run mcp:demo-client -- addNumbers '{"a":34,"b":7}'
npm run mcp:demo-client -- textToSpeech '{"text":"Hello from the server"}'

Cursor & Inspector

After npm run build, point the host at node /absolute/path/to/dist/mcp/index.js.

MCP Inspector: npx -y @modelcontextprotocol/inspector node dist/mcp/index.js from the repo root. Pass assist secrets with -e OPENAI_API_KEY=$OPENAI_API_KEY where needed.

FFmpeg and ffplay (optional)

The npm run speak script can play MP3 in the terminal using ffplay, which ships with FFmpeg. If ffplay is not on your PATH, the script still works by saving a short MP3 under your temp folder and opening it with the OS default app; install FFmpeg when you want in-terminal playback without that fallback.

Windows

1. winget (built into Windows 10/11):

   winget install --id Gyan.FFmpeg --source winget --accept-package-agreements --accept-source-agreements

2. Close and reopen your terminal (or Cursor’s integrated terminal) so the updated PATH includes the FFmpeg bin directory.

3. Confirm ffplay is visible:

   ffplay -version

If ffplay is still not found, add the folder that contains ffplay.exe manually: Settings → System → About → Advanced system settings → Environment Variables → Path → Edit → New (typical install paths look like C:\ffmpeg\bin or under %LOCALAPPDATA%\Microsoft\WinGet\Packages\…).

Manual download: gyan.dev FFmpeg builds (full or essentials build), unzip, then add the bin folder to PATH as above.

macOS

brew install ffmpeg
ffplay -version

Linux (Debian / Ubuntu example)

sudo apt update && sudo apt install -y ffmpeg
ffplay -version

Other distributions: install the ffmpeg package from your package manager; ffplay is included in the same package.

Contributing

Issues and PRs welcome. Extend internal agents via src/agents/ and assist.ts routing if you split personas.

Checklist before you promote the repo

• Set author and (optionally) repository / homepage / bugs in package.json so npm and GitHub link correctly.

• Replace OWNER/REPO in the commented CI badge when the remote exists, then uncomment the line.

• Add a GitHub profile README or link this repo from your CV/LinkedIn—recruiters land here first from the link.

• Set the repo About description and topics (e.g. mcp, langchain, typescript, ai-agents).

License

ISC — see LICENSE.