# mcp-support-tools

An **MCP server** (Model Context Protocol) that gives any MCP client, such as Claude Desktop, Cursor, or a
LangGraph agent, the tools a customer-support agent needs: customer lookup, transaction history,
knowledge-base search, and ticket escalation. Built on the official `mcp` Python SDK (2.x).

It packages the "business systems" side of the support bot I ran in production for two online gaming
brands as a standalone, protocol-native server, on a fictional brand ("Astra Play") with fixture data.
The agent side lives in [support-agent-langgraph](https://github.com/stepbystepautomatization-jpg/support-agent-langgraph).

## What it exposes

| Kind     | Name                                                         | Purpose                                                                                                      |
| -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| tool     | `get_customer(customer_id)`                                  | verification status, VIP tier, balance, active bonus                                                         |
| tool     | `get_transactions(customer_id, limit)`                       | recent deposits and withdrawals, newest first                                                                |
| tool     | `search_knowledge(query, category?, top_k)`                  | ranked knowledge-base sections with scores; falls back to unfiltered search when the category guess is wrong |
| tool     | `create_ticket(customer_id, category, summary, transcript?)` | escalation with priority rules: VIP → urgent, withdrawals / responsible gaming → high                        |
| tool     | `list_tickets()`                                             | tickets created in the session                                                                               |
| resource | `kb://docs`, `kb://docs/{doc_id}`                            | the knowledge base as browsable documents                                                                    |
| prompt   | `triage(customer_id?)`                                       | a system prompt that tells the model when to call which tool                                                 |

The server `instructions` field and the `triage` prompt encode the rules that mattered in production:
look the customer up before talking about their money, state policies only from search results,
escalate only on explicit request or when tools cannot resolve the issue.

## Use it from Claude Desktop or Cursor

```bash
pip install git+https://github.com/stepbystepautomatization-jpg/mcp-support-tools
```

`claude_desktop_config.json` / `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "support-tools": {
      "command": "mcp-support-tools"
    }
  }
}
```

Then ask: _"Customer cust_2002 says their withdrawal was rejected. Why, and what should they do?"_
The model calls `get_customer` (unverified, active bonus), `get_transactions` (rejected, reason
`account_not_verified`), `search_knowledge("withdrawal rejected verification")`, and answers from the data.

Streamable HTTP instead of stdio: `mcp-support-tools --http` (serves on `:8000`).

## Use it from code

```python
from mcp.client.client import Client
from mcp_support_tools.server import server

async with Client(server) as client:            # in-process, no subprocess
    tools = await client.list_tools()
    hits = await client.call_tool("search_knowledge", {"query": "minimum withdrawal"})
```

The same `Client` works with `StdioServerParameters` or an HTTP URL for a remote server.

## Tests

```bash
pip install -e ".[dev]"
pytest          # 9 tests: tools, ranking, category fallback, ticket priorities, resources, prompt, path traversal
```

Tests drive a real MCP client connected in-process to the server, so the protocol layer (schemas,
serialization, error mapping) is exercised, not just the Python functions.

## Design notes

- **Structured errors, not exceptions.** A missing customer returns `{"error": "customer_not_found"}`
  so the model can recover in the same turn instead of the tool call failing.
- **Search returns scores.** The client can decide its own threshold; a score of 0 never comes back.
- **Fixtures are in-memory** so the repo runs anywhere. Swapping them for the real back office is
  three functions.
- **Path safety** on `kb://docs/{doc_id}` is enforced twice: by the SDK's resource security and by
  a parent-directory check in the handler.

## License

MIT