[Akaliup]

Summary

Adds a read-only stdio MCP Server on top of the existing Tool Registry. RAG was already implemented and merged on master; this PR does not duplicate it. The MCP server exposes the same knowledge retrieval as search_knowledge and the same chunk_id contract as the HTTP API.

Exposed tools:

• get_profit_analysis
• get_sku_breakdown
• search_knowledge
• get_approval_status

Not exposed: create_recommendation, simulate_execute_approved_action, and any approval, rejection, execution, user or tenant management tool. Calls to them return unknown_tool.

Security and contract boundaries

• Server-side role only: PROFITOPS_MCP_ROLE (analyst default, approver optional). Client role headers and tool-argument role fields are rejected.
• The allowlist is validated against registry effect=read|pure and policy=safe at startup.
• The MCP process does not create tables, seed data, or build an LLM provider.
• MCP reads do not write business tables; tests compare analyses, recommendations, executions, and audit_logs counts before and after.
• RAG content is returned as untrusted data, not instructions. Default hashing embeddings are offline; remote embeddings are only used when explicitly configured.
• HTTP approval and simulation execution remain unchanged and still require an HTTP approver.

Verification (actually executed)

Check	Command	Result
Backend full suite	python -m pytest backend/tests -q	272 passed, 6 skipped (Postgres env tests; 172.52s)
MCP protocol tests	python -m pytest backend/tests/test_mcp_server.py -q	9 passed (6.18s)
Real stdio subprocess	python scripts/mcp_check.py	ok=true; 4 tools; net profit -570300 cents; bridge_verified=true; 8 evidence items; 3 SKU rows; 3 RAG hits; embedding_model=hashing-v1; write/ask tools unknown_tool
Frontend tests	npm --prefix frontend test -- --run	17 passed (39.58s)
Frontend build	npm --prefix frontend run build	passed; Vite 6.4.5, 2252 modules, 18.79s
Dependency sanity	python -m pip check	No broken requirements found
Patch sanity	git diff --check	exit 0

Not verified in this branch:

• Real LLM call: not run. MCP uses LLM_PROVIDER=disabled and an empty LLM_API_KEY; no paid model call is part of this change.
• HTTP smoke and browser E2E: not rerun. No HTTP route, database schema, or frontend page changed in this PR. Previous RAG HTTP/browser evidence remains in docs/TEST_REPORT.md.
• CI: pending. This PR description does not claim CI passed; the PR checks will run after creation.

Files

• backend/app/mcp_server.py
• backend/tests/test_mcp_server.py
• scripts/mcp_check.py
• docs/MCP.md
• backend/app/config.py, dependency locks, CI workflow, README and contract/architecture/handoff/test docs

No database migration and no change to the HTTP API contract.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-02T07:44:12.887994Z	9607f93	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.