Mhlabs Mcp Tools

mhlabs-mcp-tools

mcp-name: io.github.MusaddiqueHussainLabs/mhlabs_mcp_tools

🧠 mhlabs-mcp-tools

mhlabs-mcp-tools is a Modular MCP Tools Server built using FastMCP.
It provides an extendable AI tool ecosystem organized into functional categories (Text Preprocessing, NLP Components, Document Analysis, etc.) that can be dynamically loaded and served through MCP (Model Context Protocol) via STDIO transport.

This project is part of the MHLabs AI Agentic Ecosystem, designed to work with mhlabs-mcp-server, mhlabs-mcp-agents, and downstream A2A agent frameworks.

Features

• FastMCP Server: Pure FastMCP implementation supporting multiple transport protocols
• Factory Pattern: Reusable MCP tools factory for easy service management
• Domain-Based Organization: Services organized by business domains (HR, Tech Support, etc.)
• Authentication: Optional Azure AD authentication support
• Multiple Transports: STDIO, HTTP (Streamable), and SSE transport support
• VS Code Integration: Debug configurations and development settings
• Comprehensive Testing: Unit tests with pytest
• Flexible Configuration: Environment-based configuration management

Architecture

mhlabs_mcp_tools/├── .gitignore├── .vscode/│   └── settings.json├── CHANGELOG.md├── LICENSE├── README.md├── docs/│   └── index.md├── examples/│   ├── example_client.py│   └── example_client_http.py├── mkdocs.yml├── pyproject.toml├── requirements.txt├── server.json└── src/    ├── __init__.py    ├── main.py    └── mhlabs_mcp_tools/        ├── __init__.py        ├── core/        │   ├── __init__.py        │   ├── config.py        │   ├── constants.py        │   ├── factory.py        │   └── prompts.py        ├── data/        │   ├── __init__.py        │   ├── external/        │   │   └── __init__.py        │   ├── interim/        │   │   └── __init__.py        │   ├── processed/        │   │   └── __init__.py        │   └── raw/        │       ├── __init__.py        │       ├── contractions_dict.json        │       ├── custom_substitutions.csv        │       ├── leftovers_dict.json        │       └── slang_dict.json        ├── handlers/        │   ├── __init__.py        │   ├── custom_exceptions.py        │   └── output_generator.py        ├── mcp_server.py        ├── models/        │   └── __init__.py        ├── nlp_components/        │   ├── __init__.py        │   └── nlp_model.py        ├── services/        │   ├── __init__.py        │   ├── langchain_framework.py        │   └── spacy_extractor.py        └── text_preprocessing/            ├── __init__.py            ├── contractions.py            ├── emo_unicode.py            ├── slang_text.py            └── text_preprocessing.py

Available Services

Currently the package is organized into three primary modules:

1. NLP Components

2. Text Preprocessing

This module equips users with an extensive set of text preprocessing tools:

Quick Start

Development Setup

1. Clone and Navigate:

   bash

   cd src/mhlabs_mcp_tools

2. Install Dependencies:

   bash

   pip install -r requirements.txt

3. Configure Environment:

   bash

   cp .env.example .env# Edit .env with your configuration

4. Start the Server:

   bash

   # Default STDIO transport (for local MCP clients)python mcp_server.py
   # HTTP transport (for web-based clients)python mcp_server.py --transport http --port 9000orafter installed mhlabs-mcp-toolspython -m mhlabs_mcp_tools.mcp_server --transport http --port 9000
   # Using FastMCP CLI (recommended)fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
   # Debug mode with authentication disabledpython mcp_server.py --transport http --debug --no-auth

Transport Options

1. STDIO Transport (default)

• 🔧 Perfect for: Local tools, command-line integrations, Claude Desktop
• 🚀 Usage: python mcp_server.py or python mcp_server.py --transport stdio

2. HTTP (Streamable) Transport

• 🌐 Perfect for: Web-based deployments, microservices, remote access
• 🚀 Usage: python mcp_server.py --transport http --port 9000
• 🌐 URL: http://127.0.0.1:9000/mcp/

3. SSE Transport (deprecated)

• ⚠️ Legacy support only - use HTTP transport for new projects
• 🚀 Usage: python mcp_server.py --transport sse --port 9000

FastMCP CLI Usage

# Standard HTTP serverfastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
# With custom hostfastmcp run mcp_server.py -t streamable-http --host 0.0.0.0 --port 9000 -l DEBUG
# STDIO transport (for local clients)fastmcp run mcp_server.py -t stdio
# Development mode with MCP Inspectorfastmcp dev mcp_server.py -t streamable-http --port 9000

VS Code Development

1. Open in VS Code:

   bash

   code .

2. Use Debug Configurations:

   • Debug MCP Server (STDIO): Run with STDIO transport
   • Debug MCP Server (HTTP): Run with HTTP transport
   • Debug Tests: Run the test suite

Configuration

Environment Variables

Create a .env file based on .env.example:

# Server SettingsMCP_HOST=0.0.0.0MCP_PORT=9000MCP_DEBUG=falseMCP_SERVER_NAME=MHLABS MCP Server
# Authentication SettingsMCP_ENABLE_AUTH=trueAZURE_TENANT_ID=your-tenant-id-hereAZURE_CLIENT_ID=your-client-id-hereAZURE_JWKS_URI=https://login.microsoftonline.com/your-tenant-id/discovery/v2.0/keysAZURE_ISSUER=https://sts.windows.net/your-tenant-id/AZURE_AUDIENCE=api://your-client-id

Authentication

When MCP_ENABLE_AUTH=true, the server expects Azure AD Bearer tokens. Configure your Azure App Registration with the appropriate settings.

For development, set MCP_ENABLE_AUTH=false to disable authentication.

Adding New Services

1. Create Service Class:

   python

   from core.factory import MCPToolBase, Domain
   class MyService(MCPToolBase):    def __init__(self):        super().__init__(Domain.MY_DOMAIN)
       def register_tools(self, mcp):        @mcp.tool(tags={self.domain.value})        async def my_tool(param: str) -> str:            # Tool implementation            pass
       @property    def tool_count(self) -> int:        return 1  # Number of tools

2. Register in Server:

   python

   # In mcp_server.py (gets registered automatically from services/ directory)factory.register_service(MyService())

3. Add Domain (if new):

   python

   # In core/factory.pyclass Domain(Enum):    # ... existing domains    MY_DOMAIN = "my_domain"

MCP Client Usage

Python Client

import asynciofrom fastmcp import Client
client = Client("http://localhost:9000/mcp")
async def main():    async with client:        tools = await client.list_tools()        # tools -> list[mcp.types.Tool]        # print(tools)        for tool in tools:            print(f"Tool: {tool.name}")                result = await client.call_tool("textprep.expand_contraction", {"input_text": "The must've SSN is 859-98-0987. The employee's phone number is 555-555-5555."})        print("Result:", result)
asyncio.run(main())

Command Line Testing

# Test the server is runningcurl http://localhost:9000/mcp/
# With FastMCP CLI for testingfastmcp dev mcp_server.py -t streamable-http --port 9000

Quick Test

Test STDIO Transport:

# Start server in STDIO modepython mcp_server.py --debug --no-auth
# Test with client_example.pypython client_example.py

Test HTTP Transport:

# Start HTTP serverpython mcp_server.py --transport http --port 9000 --debug --no-auth
# Test with FastMCP clientpython -c "from fastmcp import Clientimport asyncioasync def test():    async with Client('http://localhost:9000/mcp') as client:        result = await client.call_tool("textprep.expand_contraction", {"input_text": "The must've SSN is 859-98-0987. The employee's phone number is 555-555-5555."})        print(result)asyncio.run(test())"

Test with FastMCP CLI:

# Start with FastMCP CLIfastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
# Server will be available at: http://127.0.0.1:9000/mcp/

Troubleshooting

Common Issues

1. Import Errors: Make sure you're in the correct directory and dependencies are installed
2. Authentication Errors: Check your Azure AD configuration and tokens
3. Port Conflicts: Change the port in configuration if 9000 is already in use
4. Missing fastmcp: Install with pip install fastmcp

Debug Mode

Enable debug mode for detailed logging:

python mcp_server.py --debug --no-auth

Or set in environment:

MCP_DEBUG=true

Server Arguments

usage: mcp_server.py [-h] [--transport {stdio,http,streamable-http,sse}]                     [--host HOST] [--port PORT] [--debug] [--no-auth]
MHLABS MCP Server
options:  -h, --help            show this help message and exit  --transport, -t       Transport protocol (default: stdio)  --host HOST           Host to bind to for HTTP transport (default: 127.0.0.1)  --port, -p PORT       Port to bind to for HTTP transport (default: 9000)  --debug               Enable debug mode  --no-auth             Disable authentication

📄 License

MIT License © 2025 MusaddiqueHussain Labs

🤝 Contributing

1. Follow the existing code structure and patterns
2. Add tests for new functionality
3. Update documentation for new features
4. Use the provided VS Code configurations for development

🧠 Learn More

• MCP Protocol: https://modelcontextprotocol.io
• FastMCP GitHub: https://github.com/fastmcp/fastmcp
• LangGraph Integration Guide (coming soon)

💡 Tip

If you want to embed mhlabs-mcp-tools into a larger MCP-based orchestrator:

from fastmcp import StdioServerParametersserver_params = StdioServerParameters(    command="python",    args=["-m", "mhlabs_mcp_tools.server"],    //env={"MHLABS_MCP_CATEGORY": "textprep,nlp"})

Developed with ❤️ by MusaddiqueHussain Labs