# MCP Server with OpenAI Integration

A production-ready [Model Context Protocol](https://modelcontextprotocol.io/) 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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
npm run build
npm run demo:ext
```

or by setting an environment variable before starting the server:

```bash
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`:

```bash
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

```bash
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`.