feat: implement native MCP server support with safety guardrails

[Tech-no-mad]

Description

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires documentation update
• Refactor (code structure improvements, no new functionality)
• Tests (addition or improvement of tests)
• Chore (changes to tooling, CI/CD, or metadata)

How Has This Been Tested?

Checklist

• My code follows the project's coding style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

Screenshots (if applicable)

Additional Context

[Tech-no-mad]

Hi @RafaelJohn9 , I've implemented the MCP server support as discussed in #140.
I've configured it to use fastmcp and included strict safety guardrails for production environments. The tools are also documented to instruct LLMs on how to handle M-Pesa's asynchronous callbacks.
Let me know if you need any adjustments or if this looks good to merge!

[RafaelJohn9]

Hi @Tech-no-mad , Could you kindly address the workflow errors.

Also I'm deterred from merging this since we do not have tests for this.

[RafaelJohn9]

We need to add tests, fastmcp offers recommendation of implementing tests at: https://gofastmcp.com/development/tests, ,maybe we can draw insights from here 🤝

[watersRand]

Thanks for working on this! This is an excellent blueprint for the MCP server architecture—the use of enforce_security_guard and the explicit LLM agent instructions in the docstring are brilliant safety practices.Please note a few formatting noise issues and structural fixes:

Isolate the Linting: The automated formatting sweep is creating significant diff noise, completely obscuring your functional logic updates. Could we isolate the linting and styling fixes into a separate, independent commit or PR? This lets us track the core changes cleanly.

Expand Module Scope: Please remember to account for the wider integration footprint requested in the tracking issue. The implementation needs to provide tools for the full suite of M-Pesa operations—including C2B, B2C, B2B, Transaction Status, Account Balance, Reversals, Tax Remittance, and Dynamic QR—not just STK Push.

Fix Configuration Redundancy (stk_push): There is redundant environment variable lookup and parsing happening across both get_client() and individual tool actions (confusing API access credentials with merchant bank properties). Let’s centralize the configuration values (like keys, shortcodes, and passkeys) into a single configuration loader or class rather than re-querying os.environ inside every endpoint execution loop.

Remove Redundant Casts: FastMCP automatically uses your Python type hints (amount: int) to validate inputs via Pydantic before the tool runs. The manual amount=float(amount) typecasting inside the method is redundant. Trust the type hints and pass the variable directly.

[RafaelJohn9]

We still don't have ./mcp implementation .

[RafaelJohn9]

Hello @Tech-no-mad , thanks for updating PR few changes to consider.

• mcp should live at ./mcp not ./mpesakit/mcp to have two different packaages.
• Address comments below.
• Remove the diff patch file
• I'd also recommend we split the mcp/server.py if possible. Currently it handles a lt and it maybe difficult to maintain and extend with new APIs.

[RafaelJohn9]

no need for this fix, as is not part of the PR issue 🤝 .