Acmezone Data MCP

Acmezone Data MCP is a read-only MCP service for internal company Amazon business data. It encapsulates sales volume, inventory, inventory value, and financial data into 19 Tools, available for WorkBuddy, MCP Inspector, and other MCP-compatible clients.

The two-phase modular refactoring has been completed: both the Tool interface layer and the Repository data access layer are in place, with full regression testing before and after the refactoring. For implementation records, refer to the Refactoring Plan.

Current Status

• Python 3.12

• MCP Streamable HTTP

• Container listening: 0.0.0.0:8000

• No environment variable configuration; data paths, worksheet names, and ports are currently hardcoded in settings.py

• 19 Tools have been split into 8 modules by business domain, with existing interfaces remaining compatible

• Direct reading of Excel and SQLite has been centralized in the Repository layer

• All 19 Tools publish structured output schemas, parameter enums/ranges, and read-only markers

• Excel Snapshots are cached by file size and nanosecond-level modification time, automatically invalidated when the source file changes

• Excel is opened with read_only=True and data_only=True

• SQLite financial database is connected in read-only mode via mode=ro

Current directory:

mcp/
├─ mcp_server.py
├─ settings.py
├─ core/
├─ tools/
├─ repositories/              # Excel、销售、库存和财务数据访问
├─ tests/
├─ scripts/
├─ docs/
├─ requirements.txt
└─ Dockerfile

Data Sources

Source file modification time is only used to determine data freshness, no longer to distinguish actual from forecast. The actual/forecast boundary uniformly uses the current month in the company timezone Asia/Shanghai. Financial data additionally uses the report month and upload time in the database to indicate the data cutoff.

Docker Deployment

The current NAS container uses the following storage mounts:

Container execution:

python /app/mcp_server.py

The current Dockerfile only installs dependencies, not copying the source code, because at runtime the entire MCP project directory is mounted to /app. Therefore, if this image runs independently without the /app mount, it will not find mcp_server.py; this is a known prerequisite of the current deployment method.

The service inside the container listens on port 8000. The NAS external port is determined by the "port mapping" configuration in the container management interface.

Tool Overview

Products

• search_product

• get_product_catalog_summary

• get_parent_children

• get_product_overview

• compare_product_overviews

Sales

• get_sales_history

• get_current_sales

• get_sales_ranking

• get_sales_trend_ranking

Inventory

• get_inventory

• get_inventory_value

• get_inventory_ranking

Finance, Forecast, and System

• get_finance_history

• get_finance_ranking

• get_replenishment_forecast

• get_product_batch

• filter_products

• get_data_source_status

• get_data_quality_report

For parameters and usage of each Tool, refer to the Tool Interface Reference.

Install Dependencies

pip install -r requirements.txt

Current dependencies:

• mcp[cli]==2.0.0

• openpyxl==3.1.5

• pydantic==2.13.4

Core runtime dependencies are version-locked. Before upgrading dependencies or rebuilding the image, a full regression test should still be run.

Startup

Execute within a container that has /storage and /finance data mounts:

python /app/mcp_server.py

Running locally can start the service, but if the corresponding absolute data paths do not exist, data query Tools will return that the data file does not exist or is inaccessible.

Maintenance Principles

• Do not modify the original Excel or financial database.

• Tools only read and organize real business data; they do not replace AI for business judgment.

• When modifying a Tool, maintain backward compatibility of names, parameters, and return structures.

• During refactoring, after migrating each module, recheck the Tool registration count and representative responses.

• When modifying a Tool, the interface reference, architecture documentation, and employee usage documentation must be updated simultaneously.

Documentation consistency check:

python scripts/check_documentation_consistency.py

Project Documentation

• Tool Interface Reference

• Modular Refactoring Plan

• Current Architecture Description

• Employee Quick Start Guide

• Employee User Manual - Full Reference

• Documentation Synchronization Maintenance Rules