# MCP order tools

A local MCP server with account-scoped order tools, versioned proposals and application-owned approval.

[![Tests](https://github.com/abdulrehman-net/mcp-order-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/abdulrehman-net/mcp-order-tools/actions/workflows/ci.yml)

[Technical series](https://abdulrehmanconsulting.com/series) · [Architecture](docs/architecture.md)

[Beginner setup and debugging](docs/getting-started.md)

## Run locally

Requires Python 3.12+. Uses the official MCP Python SDK 2.2.0.

```sh
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python server.py
```

The server uses **stdio**: no browser page or listening network port. A compatible
MCP host should launch the virtual environment's Python with the absolute path to
`server.py` and the repository as its working directory. No API key is required.

## Try the tools

1. `get_order_status(order_id="ORDER-100")` returns status and version, not customer data.
2. `get_order_status(order_id="ORDER-200")` returns the same safe not-found shape as an unknown ID.
3. `prepare_address_change` validates and returns a version-bound proposal.
4. `apply_approved_change` returns `approval_required` until the trusted application approves it.

There is deliberately **no approve tool**. The handler tests demonstrate the
trusted review path, repeated application and stale proposals. The standalone
MCP server does not provide a human approval UI, so its write tool cannot succeed
through model calls alone.

## Design and limits

- Account context is fixed to a fictional demo account at launch; tool arguments cannot choose it.
- Every handler checks ownership again, including applying a stored proposal.
- Proposals pin the normalized address and version; changing either needs a new review.
- Completed proposal IDs return the existing local outcome.

This in-memory, single-process exercise has no production authentication,
concurrent transaction store, provider API or persistent audit trail. Local
deduplication does not make a remote provider write idempotent. A real deployment
needs authenticated context, durable operations and reconciliation for uncertain
external results, as described in the guide and diagram. Do not expose this
teaching server as an authenticated production service.

## Further reading

- [Official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP architecture](https://modelcontextprotocol.io/docs/learn/architecture)


## Provenance and license

Original educational examples by Abdul Rehman. All scenarios are fictional;
no customer records, credentials or private product source are included.
Released under the [MIT license](LICENSE).