Skip to main content
Glama
MCP Business Tools

MCP Business Tools

by danielpdev
README.md
# MCP Business Tools

Typed inventory tools with capability checks and order approval.

[![verification](https://github.com/danielpdev/mcp-business-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/danielpdev/mcp-business-tools/actions/workflows/ci.yml)

**Role focus:** MCP / Agent Integration / Python. **Status:** working local portfolio implementation, with synthetic data.

## Demo

![How MCP Business Tools works](docs/demo.gif)

Edited replay of captured CLI outputs in deterministic fixture mode. This is not live model inference. [Full recording](docs/demo.mp4). Rebuild with `./scripts/render_gif.sh` (FFmpeg required).

## The engineering decision

The MCP server exposes inventory reads and order preparation. Capability scopes come from the server process, never from tool arguments. Stock is committed only through a separate operator approval surface.

```mermaid
flowchart LR
  MCP_client --> Typed_tools; Typed_tools --> Capability_check; Capability_check --> Order_proposal; Operator --> Approval; Approval --> Atomic_stock_update
```

## Run locally

Requirements: Python 3.12, [uv](https://docs.astral.sh/uv/getting-started/installation/) and Make.

```bash
git clone https://github.com/danielpdev/mcp-business-tools.git
cd mcp-business-tools
make setup
make demo
make test
make eval
```

`make demo` uses an isolated temporary database where relevant, so it is safe to repeat. `make eval` writes a timestamped report to `reports/evaluation-fixture.json`. Fixture mode is deterministic and does not represent model inference. There is no recurring hosting or API subscription cost.

`make serve` opens the local API on `http://127.0.0.1:8105/docs`.

### MCP transport

```bash
uv run --frozen python -m app.server
```

This starts the official Python SDK 2.3.0 stdio server. Configure your MCP client to launch that command from this repository directory. The default capability is inventory read. Set `MCP_SCOPES=inventory:read,orders:prepare` in the **server operator environment** to permit proposals. Approval is deliberately absent from MCP tools.

[Watch the recorded demo](docs/demo.mp4) · [Reproduce the walkthrough](docs/DEMO.md)

## Verification and evidence

Real stdio client/server initialization, tool discovery, forbidden capabilities, invalid quantities, expiry, action fingerprints and approval replay.

- [Evaluation report](reports/evaluation-fixture.json) — measured during an actual run; inspect the mode and dataset size.
- [Development and authorship](docs/DEVELOPMENT.md).
- [Romanian interview preparation](docs/INTERVIEW_RO.md).
- [Design notes](docs/DESIGN.md).
- [Demo walkthrough](docs/DEMO.md).

CI uses standard GitHub-hosted runners and deterministic tests without downloading LLM weights. The lockfiles record exact package versions. Local-model results, when present, live in `reports/evaluation-local.json`; hardware/model identities are in `reports/environment.json`.

## Limits and next iteration

Stdio deployment trusts the machine operator. The separate local approval API is not a production authenticated operator console. Preparing an order does not reserve stock.

Next: Add per-user authentication and reservation expiry without letting the model grant itself scopes.

The local demonstration does not include production authentication, secret management or operational service guarantees. Bind it to localhost and use synthetic data. These projects demonstrate engineering decisions; they do not claim real customers, paid production deployments or guaranteed interviews.

## Project ownership

Implemented with Codex assistance for Daniel Popa. The owner should review the code, run it, make an independent change and rehearse the tradeoffs before presenting it at interview. That human understanding check is pending and cannot be verified automatically. See [development notes](docs/DEVELOPMENT.md).

MIT for original source; dependencies/models retain their own licenses. See [third-party notices](THIRD_PARTY.md).

## Complete portfolio source bundle

[All 20 project sources and demos](https://github.com/danielpdev/mcp-business-tools/releases/tag/portfolio-v0.1.0) · [Project index and publication status](docs/PORTFOLIO.md).

This repository also hosts the delivery archive for the full portfolio. All twenty projects now have separate public repositories, each with an animated GIF in its README. Each project in the archive is independently runnable.

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one searches inventory and the other prepares an order proposal. There is no meaningful overlap or ambiguity in selecting between them.

Naming Consistency5/5

Both names follow a consistent snake_case verb_noun pattern: search_inventory and prepare_order. The convention is predictable and easy to extend.

Tool Count3/5

Two tools is quite thin for a server framed broadly as MCP Business Tools. For a narrow inventory/order-preparation scope it is defensible, but the surface feels underdeveloped.

Completeness2/5

The surface covers search and order proposal preparation only. It lacks order commitment, inventory detail retrieval, stock mutation, order lifecycle operations, and other basic business workflow tools, creating significant dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues