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

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

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:

python3 -m pos_support_mcp_server.seed --reset

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

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:

python3 -m pos_support_mcp_server.server

The installed console entry point is equivalent:

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:

{
  "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

Example Usage

Conceptual MCP calls:

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

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

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

Tools return a structured envelope:

{"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:

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:

python3 -m unittest tests.test_mcp_integration -v

Project Structure

.
├── .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.