MCP Server with OpenAI Integration

A production-ready Model Context Protocol server implemented in TypeScript. The server provides:

1. OpenAI connectivity demo – prove the API key works end-to-end via npm run demo:openai.
2. MCP tool demo – spawn the server and call tools through an MCP client using npm run demo:tool.
3. Extensibility demo – hot-load third-party tools from disk via npm run demo:ext or MCP_TOOL_MODULES.
4. Browser UI demo – launch an interactive web page that exercises the OpenAI call and knowledge-search tool with npm run demo:ui.

The codebase focuses on clean abstractions, schema validation, and commercial readiness (logging, config safety, tests).

Requirements

• Node.js 18+ (Node 20 recommended to avoid optional engine warnings).
• npm 9+.
• A valid OPENAI_API_KEY with access to the desired models.

Quick start

npm install
cp .env.example .env   # fill in OPENAI_API_KEY
npm run build
npm start               # runs the compiled MCP server on stdio

To run the TypeScript entry directly during development:

npm run dev

Environment variables

Variable	Description
OPENAI_API_KEY	Required. API key for OpenAI.
OPENAI_BASE_URL	Override base URL for Azure/OpenAI proxies.
OPENAI_TIMEOUT_MS	Timeout (ms) applied to OpenAI API calls. Defaults to 20000.
MCP_SERVER_NAME	Name advertised to MCP clients.
LOG_LEVEL	fatal → trace. Defaults to info.
MCP_TOOL_MODULES	Comma-separated absolute paths to extra tool modules (see extensibility demo).
MCP_PORT	Reserved for future transports; defaults to 7337.
UI_DEMO_PORT	Optional port for the browser UI demo. Defaults to 4399.

Demo workflows

1. OpenAI connectivity

Verifies credentials and model access:

npm run demo:openai

Outputs the model reply plus token usage metrics via Pino logs.

2. MCP tool invocation

Spawns the compiled MCP server (node dist/index.js) and connects with the official MCP client SDK:

npm run build
npm run demo:tool

Set MCP_DEMO_SERVER_COMMAND / MCP_DEMO_SERVER_ARGS if you want the client to launch a different command (for example npx tsx src/index.ts). The script lists tools and invokes knowledge_search end-to-end.

3. Extensibility via plugins

Ships with src/examples/plugins/stockQuoteTool.ts. After npm run build the compiled module lives at dist/examples/plugins/stockQuoteTool.js.

Load it either through the demo script:

npm run build
npm run demo:ext

or by setting an environment variable before starting the server:

export MCP_TOOL_MODULES=$(pwd)/dist/examples/plugins/stockQuoteTool.js
npm start

The server automatically registers every tool exported from the referenced module(s).

4. Browser UI walkthrough

Launch a lightweight HTTP server that serves public/ui-demo.html:

npm run demo:ui

Visit http://localhost:4399 (or UI_DEMO_PORT) to:

• Send prompts directly to OpenAI using the configured API key.
• Call the built-in knowledge_search tool through a REST façade.

Responses render inline so you can validate both flows without leaving the browser.

Tooling

• TypeScript strict mode with tsc for builds.
• Vitest for unit testing (npm test).
• ESLint + Prettier for linting/formatting (npm run lint, npm run format).
• Pino structured logging with pretty printing in development.

Test & quality gates

npm run lint
npm test

Coverage reports are emitted under coverage/ via V8 instrumentation.

Project structure

• src/config/env.ts – centralized, validated environment loading.
• src/clients/openaiClient.ts – resilient OpenAI wrapper implementing the LLMProvider contract.
• src/mcp/registry.ts – tool lifecycle management + dynamic module loading.
• src/mcp/server.ts – MCP server wiring, tool adapters, and plugin APIs.
• src/demos/* – runnable scripts covering the three required scenarios.
• src/examples/plugins/* – sample plugin(s) for extensibility demos.
• tests/* – Vitest coverage for critical units.

For a deeper architectural overview, read docs/architecture.md.