# MCP Support Agent

This repo started as a small Express ticket API. I used it to learn how an existing API can be exposed through MCP, then added an Ollama-based agent and document search with local embeddings and LanceDB.

The code covers two use cases:

- ticket tools backed by a REST API
- support-document search backed by a local vector database

## How it works

```text
User question
    ↓
Ollama model
    ↓ requests a tool
TypeScript MCP client
    ↓ stdio
MCP server
    ├── ticket tools → Express REST API
    └── document search → EmbeddingGemma → LanceDB
```

The model sees the available tools through MCP `listTools()`. When it requests a tool, the TypeScript client calls the MCP server and sends the result back to the model.

## MCP tools

| Tool | Description |
| --- | --- |
| `get_tickets` | Get all tickets from the REST API |
| `get_ticket` | Get one ticket by ID |
| `create_ticket` | Create a ticket after user approval |
| `search_documents` | Search support articles by meaning and optional category |

## Document search

Support articles are split into sentences and embedded with `embeddinggemma:300m-qat-q4_0`. The indexing script stores the chunks and their vectors in LanceDB.

At query time, only the question is embedded. LanceDB applies the tenant and category filters, performs a cosine-distance search, and returns up to two matches within the configured distance threshold.

Indexing and querying use the same embedding model. If the model or source articles change, rebuild the index.

## Setup

Requirements:

- Node.js 20 or newer
- Ollama running locally

Install the project and download the local models:

```bash
npm install
ollama pull embeddinggemma:300m-qat-q4_0
ollama pull qwen3:1.7b
```

Build the vector database:

```bash
npm run index:documents
```

LanceDB writes its files to `data/`, which is ignored by Git.

## Run the local agent

```bash
npm run agent:local
```

The included prompt asks for printer help. The agent calls `search_documents` and prints the sources collected from the MCP result below the model's answer.

## Run the ticket API

```bash
npm run dev
```

Available routes:

```text
GET  /tickets
GET  /tickets/:id
POST /tickets
```

Tickets are kept in memory, so created tickets are cleared when the server restarts.

## Run the cloud agent

The cloud example needs an Ollama API key. Copy `.env.example` to `.env` and set the key, then run the API and agent in separate terminals:

```bash
npm run start
```

```bash
npm run agent:cloud
```

The example prompt creates a ticket and fetches another one. Write tools require confirmation before they run.

## Retrieval checks

```bash
npm run evaluate:retrieval
```

The current test set contains three queries with expected articles and one query that should return no result:

```text
Evaluation accuracy: 4/4 (100%)
```

This is only a check against the small set of articles in this repo, not a general embedding benchmark.

## Tenant filtering

Documents for two sample companies are stored in the same LanceDB table. The MCP server uses a fixed `company-a` tenant to stand in for an authenticated session.

The tool schema does not accept `tenantId`. A client can send that extra field, but it cannot override the tenant used by the server. A real application would take this value from a verified session or token instead of a constant.

## Commands

| Command | Description |
| --- | --- |
| `npm run typecheck` | Check TypeScript |
| `npm run build` | Compile the project |
| `npm run index:documents` | Rebuild the LanceDB table |
| `npm run evaluate:retrieval` | Run retrieval checks |
| `npm run test:mcp` | List MCP tools and call document search directly |
| `npm run agent:local` | Run the local Ollama example |
| `npm run agent:cloud` | Run the Ollama Cloud example |
| `npm run documents:upsert` | Insert or replace the sample Wi-Fi article |
| `npm run documents:delete` | Delete the sample Wi-Fi article |

## Project layout

```text
src/        API, MCP server, agents, and document search
scripts/    Indexing, document updates, and retrieval checks
examples/   Small examples built while learning each piece
```