# POS Support MCP Server

## Overview

POS Support MCP Server is a standalone local Model Context Protocol server for
a fictitious point-of-sale technical-support domain. It exposes eleven focused
tools for branches, terminals, incidents, historical solutions, and incident
management. It is designed for a university networking demonstration and uses
only local simulated data.

## Features

- Four related entities: branches, terminals, incidents, and incident history.
- Eight read-only and three mutating business tools.
- Deterministic similar-incident search without AI or external services.
- Atomic incident creation, update, resolution, and history writes.
- Stable seed IDs for reproducible demonstrations.
- Consistent structured success and business-error responses.

## Architecture

```text
MCP Client
    ↓ stdio
POS Support MCP Server
    ↓
Validation / Service Layer
    ↓
Repository Layer
    ↓
SQLite
```

Protocol registration, business rules, and parameterized SQL are kept in
separate modules. The package does not depend on the parent chatbot project.

## Requirements

- Python 3.10 or newer
- `mcp>=2,<3`
- SQLite support from the Python standard library

No database server, web framework, ORM, or external service is required.

## Installation

```bash
git clone https://github.com/Nery2004/pos-support-mcp-server.git
cd pos-support-mcp-server
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
```

## Database Initialization

Create or reset the default database and load deterministic seed data:

```bash
python3 -m pos_support_mcp_server.seed --reset
```

The default file is `data/pos_support.db`. Override it for an isolated run:

```bash
POS_SUPPORT_DB_PATH=/absolute/path/support.db \
python3 -m pos_support_mcp_server.seed --reset
```

`--reset` removes only the configured database file and its SQLite sidecars.
Runtime database files are ignored by Git.

## Running the Server

After installation and seeding:

```bash
python3 -m pos_support_mcp_server.server
```

The installed console entry point is equivalent:

```bash
pos-support-mcp
```

## MCP Transport

The server uses the high-level `MCPServer` API from MCP Python SDK 2.x and runs
only over stdio. It opens no network port and writes no debug output to stdout.

Example client configuration after installing the package into the selected
Python environment:

```json
{
  "transport": "stdio",
  "command": "/absolute/path/to/.venv/bin/python",
  "args": ["-m", "pos_support_mcp_server.server"],
  "env": {
    "POS_SUPPORT_DB_PATH": "/absolute/path/to/pos_support.db"
  }
}
```

Replace both absolute paths with paths on the client machine. The interpreter
must be the environment where this project was installed.

## Available Tools

Read-only:

- `list_branches`
- `get_branch`
- `list_terminals`
- `get_terminal`
- `list_incidents`
- `get_incident`
- `search_similar_incidents`
- `get_critical_incidents`

Mutating:

- `create_incident`
- `update_incident`
- `resolve_incident`

## Tool Parameters

| Tool | Parameters |
| --- | --- |
| `list_branches` | optional `status` |
| `get_branch` | `branch_code` |
| `list_terminals` | optional `branch_code`, `status` |
| `get_terminal` | `branch_code`, `terminal_code` |
| `list_incidents` | optional `branch_code`, `terminal_code`, `status`, `priority` |
| `get_incident` | `incident_id` |
| `search_similar_incidents` | `query`, optional branch/terminal, `limit=5` |
| `create_incident` | branch, optional terminal, title, description, priority |
| `update_incident` | incident ID and at least one editable field or note |
| `resolve_incident` | incident ID, solution, optional note |
| `get_critical_incidents` | optional `branch_code` |

## Example Usage

Conceptual MCP calls:

```json
{"name": "get_terminal", "arguments": {"branch_code": "001", "terminal_code": "03"}}
```

```json
{"name": "create_incident", "arguments": {"branch_code": "003", "terminal_code": "04", "title": "Connection drops", "description": "Checkout loses the POS server connection.", "priority": "high"}}
```

```json
{"name": "resolve_incident", "arguments": {"incident_id": 21, "solution": "Restarted the local POS service."}}
```

Tools return a structured envelope:

```json
{"success": true, "data": {}}
```

## Seed Data

The deterministic seed contains 4 branches, 16 terminals, 20 incidents, and 35
history records. It covers online/offline terminals, printers, scanners,
network timeouts, payments, stopped POS services, and synchronization issues.
All names, addresses, incidents, and solutions are fictitious.

## Similar Incident Search

Search normalizes English and Spanish text, removes punctuation and a small
stop-word set, then computes Jaccard similarity over unique terms from title,
description, and solution. Only positive scores are returned. Results are
ordered by score descending and incident ID ascending, rounded to four decimal
places, and limited to 1–20 entries.

## Error Handling

Business failures use `success: false` with stable codes such as
`BRANCH_NOT_FOUND`, `TERMINAL_NOT_FOUND`, `INCIDENT_NOT_FOUND`,
`INVALID_ARGUMENT`, and `INVALID_STATUS_TRANSITION`. Unexpected SQLite errors
become a sanitized `DATABASE_ERROR`; SQL, paths, and stack traces are omitted.

## Security

- Local stdio only; no HTTP server or external requests.
- Parameterized SQL and constrained business inputs.
- No arbitrary SQL, shell, Python, filesystem, or command tool.
- No subprocess execution.
- Fictitious seed data only.
- Mutating tools must not be automatically retried by a host.
- Runtime databases and credentials are excluded from publication.

## Testing

Run the standalone tests with a temporary SQLite database per test:

```bash
python3 -m unittest discover -s tests -v
```

The test suite includes a real MCP stdio integration test that starts the
server as a subprocess, discovers exactly eleven tools, calls `get_branch`,
and verifies a clean shutdown:

```bash
python3 -m unittest tests.test_mcp_integration -v
```

## Project Structure

```text
.
├── .gitignore
├── README.md
├── pyproject.toml
├── data/.gitkeep
├── src/pos_support_mcp_server/
│   ├── __init__.py
│   ├── database.py
│   ├── repository.py
│   ├── responses.py
│   ├── seed.py
│   ├── server.py
│   ├── service.py
│   ├── similarity.py
│   └── validation.py
└── tests/
```

This repository intentionally contains only the standalone POS Support MCP
Server. It excludes chatbot integrations, external services, runtime
databases, and environment files.