{
  "markdown": "# mhlabs-mcp-tools\n\nmcp-name: io.github.MusaddiqueHussainLabs/mhlabs_mcp_tools\n\n\n# 🧠 mhlabs-mcp-tools\n\n`mhlabs-mcp-tools` is a **Modular MCP Tools Server** built using [FastMCP](https://github.com/fastmcp/fastmcp).  \nIt 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**.\n\nThis project is part of the **MHLabs AI Agentic Ecosystem**, designed to work with `mhlabs-mcp-server`, `mhlabs-mcp-agents`, and downstream A2A agent frameworks.\n\n---\n\n## Features\n\n- **FastMCP Server**: Pure FastMCP implementation supporting multiple transport protocols\n- **Factory Pattern**: Reusable MCP tools factory for easy service management\n- **Domain-Based Organization**: Services organized by business domains (HR, Tech Support, etc.)\n- **Authentication**: Optional Azure AD authentication support\n- **Multiple Transports**: STDIO, HTTP (Streamable), and SSE transport support\n- **VS Code Integration**: Debug configurations and development settings\n- **Comprehensive Testing**: Unit tests with pytest\n- **Flexible Configuration**: Environment-based configuration management\n\n## Architecture\n\n```\nmhlabs_mcp_tools/\n├── .gitignore\n├── .vscode/\n│   └── settings.json\n├── CHANGELOG.md\n├── LICENSE\n├── README.md\n├── docs/\n│   └── index.md\n├── examples/\n│   ├── example_client.py\n│   └── example_client_http.py\n├── mkdocs.yml\n├── pyproject.toml\n├── requirements.txt\n├── server.json\n└── src/\n    ├── __init__.py\n    ├── main.py\n    └── mhlabs_mcp_tools/\n        ├── __init__.py\n        ├── core/\n        │   ├── __init__.py\n        │   ├── config.py\n        │   ├── constants.py\n        │   ├── factory.py\n        │   └── prompts.py\n        ├── data/\n        │   ├── __init__.py\n        │   ├── external/\n        │   │   └── __init__.py\n        │   ├── interim/\n        │   │   └── __init__.py\n        │   ├── processed/\n        │   │   └── __init__.py\n        │   └── raw/\n        │       ├── __init__.py\n        │       ├── contractions_dict.json\n        │       ├── custom_substitutions.csv\n        │       ├── leftovers_dict.json\n        │       └── slang_dict.json\n        ├── handlers/\n        │   ├── __init__.py\n        │   ├── custom_exceptions.py\n        │   └── output_generator.py\n        ├── mcp_server.py\n        ├── models/\n        │   └── __init__.py\n        ├── nlp_components/\n        │   ├── __init__.py\n        │   └── nlp_model.py\n        ├── services/\n        │   ├── __init__.py\n        │   ├── langchain_framework.py\n        │   └── spacy_extractor.py\n        └── text_preprocessing/\n            ├── __init__.py\n            ├── contractions.py\n            ├── emo_unicode.py\n            ├── slang_text.py\n            └── text_preprocessing.py\n```\n\n## Available Services\n\nCurrently the package is organized into three primary modules:\n\n### 1. NLP Components\n\n| Component Type | Description                 |\n|----------------|-----------------------------|\n| tokenize       | Text tokenization           |\n| pos            | Part-of-Speech tagging      |\n| lemma          | Word lemmatization          |\n| morphology     | Study of word forms         |\n| dep            | Dependency parsing          |\n| ner            | Named Entity Recognition    |\n| norm           | Text normalization          |\n\n### 2. Text Preprocessing\n\nThis module equips users with an extensive set of text preprocessing tools:\n\n| Function                      | Description                                          |\n|-------------------------------|------------------------------------------------------|\n| to_lower                      | Convert text to lowercase                             |\n| to_upper                      | Convert text to uppercase                             |\n| remove_number                 | Remove numerical characters                           |\n| remove_itemized_bullet_and_numbering | Eliminate itemized/bullet-point numbering |\n| remove_url                    | Remove URLs from text                                 |\n| remove_punctuation            | Remove punctuation marks                              |\n| remove_special_character      | Remove special characters                             |\n| keep_alpha_numeric            | Keep only alphanumeric characters                     |\n| remove_whitespace             | Remove excess whitespace                              |\n| normalize_unicode             | Normalize Unicode characters                          |\n| remove_stopword               | Eliminate common stopwords                            |\n| remove_freqwords              | Remove frequently occurring words                      |\n| remove_rarewords              | Remove rare words                                     |\n| remove_email                  | Remove email addresses                                |\n| remove_phone_number           | Remove phone numbers                                  |\n| remove_ssn                    | Remove Social Security Numbers (SSN)                  |\n| remove_credit_card_number     | Remove credit card numbers                            |\n| remove_emoji                  | Remove emojis                                         |\n| remove_emoticons              | Remove emoticons                                      |\n| convert_emoticons_to_words    | Convert emoticons to words                            |\n| convert_emojis_to_words       | Convert emojis to words                               |\n| remove_html                   | Remove HTML tags                                      |\n| chat_words_conversion         | Convert chat language to standard English              |\n| expand_contraction            | Expand contractions (e.g., \"can't\" to \"cannot\")        |\n| tokenize_word                 | Tokenize words                                        |\n| tokenize_sentence             | Tokenize sentences                                    |\n| stem_word                     | Stem words                                            |\n| lemmatize_word                | Lemmatize words                                       |\n| preprocess_text               | Combine multiple preprocessing steps into one function|\n\n## Quick Start\n\n### Development Setup\n\n1. **Clone and Navigate**:\n\n   ```bash\n   cd src/mhlabs_mcp_tools\n   ```\n\n2. **Install Dependencies**:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Configure Environment**:\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration\n   ```\n\n4. **Start the Server**:\n\n   ```bash\n   # Default STDIO transport (for local MCP clients)\n   python mcp_server.py\n\n   # HTTP transport (for web-based clients)\n   python mcp_server.py --transport http --port 9000\n   or\n   after installed mhlabs-mcp-tools\n   python -m mhlabs_mcp_tools.mcp_server --transport http --port 9000\n\n   # Using FastMCP CLI (recommended)\n   fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG\n\n   # Debug mode with authentication disabled\n   python mcp_server.py --transport http --debug --no-auth\n   ```\n\n### Transport Options\n\n**1. STDIO Transport (default)**\n\n- 🔧 Perfect for: Local tools, command-line integrations, Claude Desktop\n- 🚀 Usage: `python mcp_server.py` or `python mcp_server.py --transport stdio`\n\n**2. HTTP (Streamable) Transport**\n\n- 🌐 Perfect for: Web-based deployments, microservices, remote access\n- 🚀 Usage: `python mcp_server.py --transport http --port 9000`\n- 🌐 URL: `http://127.0.0.1:9000/mcp/`\n\n**3. SSE Transport (deprecated)**\n\n- ⚠️ Legacy support only - use HTTP transport for new projects\n- 🚀 Usage: `python mcp_server.py --transport sse --port 9000`\n\n### FastMCP CLI Usage\n\n```bash\n# Standard HTTP server\nfastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG\n\n# With custom host\nfastmcp run mcp_server.py -t streamable-http --host 0.0.0.0 --port 9000 -l DEBUG\n\n# STDIO transport (for local clients)\nfastmcp run mcp_server.py -t stdio\n\n# Development mode with MCP Inspector\nfastmcp dev mcp_server.py -t streamable-http --port 9000\n```\n\n### VS Code Development\n\n1. **Open in VS Code**:\n\n   ```bash\n   code .\n   ```\n\n2. **Use Debug Configurations**:\n   - `Debug MCP Server (STDIO)`: Run with STDIO transport\n   - `Debug MCP Server (HTTP)`: Run with HTTP transport\n   - `Debug Tests`: Run the test suite\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file based on `.env.example`:\n\n```env\n# Server Settings\nMCP_HOST=0.0.0.0\nMCP_PORT=9000\nMCP_DEBUG=false\nMCP_SERVER_NAME=MHLABS MCP Server\n\n# Authentication Settings\nMCP_ENABLE_AUTH=true\nAZURE_TENANT_ID=your-tenant-id-here\nAZURE_CLIENT_ID=your-client-id-here\nAZURE_JWKS_URI=https://login.microsoftonline.com/your-tenant-id/discovery/v2.0/keys\nAZURE_ISSUER=https://sts.windows.net/your-tenant-id/\nAZURE_AUDIENCE=api://your-client-id\n```\n\n### Authentication\n\nWhen `MCP_ENABLE_AUTH=true`, the server expects Azure AD Bearer tokens. Configure your Azure App Registration with the appropriate settings.\n\nFor development, set `MCP_ENABLE_AUTH=false` to disable authentication.\n\n## Adding New Services\n\n1. **Create Service Class**:\n\n   ```python\n   from core.factory import MCPToolBase, Domain\n\n   class MyService(MCPToolBase):\n       def __init__(self):\n           super().__init__(Domain.MY_DOMAIN)\n\n       def register_tools(self, mcp):\n           @mcp.tool(tags={self.domain.value})\n           async def my_tool(param: str) -> str:\n               # Tool implementation\n               pass\n\n       @property\n       def tool_count(self) -> int:\n           return 1  # Number of tools\n   ```\n\n2. **Register in Server**:\n\n   ```python\n   # In mcp_server.py (gets registered automatically from services/ directory)\n   factory.register_service(MyService())\n   ```\n\n3. **Add Domain** (if new):\n   ```python\n   # In core/factory.py\n   class Domain(Enum):\n       # ... existing domains\n       MY_DOMAIN = \"my_domain\"\n   ```\n\n## MCP Client Usage\n\n### Python Client\n\n```python\nimport asyncio\nfrom fastmcp import Client\n\nclient = Client(\"http://localhost:9000/mcp\")\n\nasync def main():\n    async with client:\n        tools = await client.list_tools()\n        # tools -> list[mcp.types.Tool]\n        # print(tools)\n        for tool in tools:\n            print(f\"Tool: {tool.name}\")\n        \n        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.\"})\n        print(\"Result:\", result)\n\nasyncio.run(main())\n```\n\n### Command Line Testing\n\n```bash\n# Test the server is running\ncurl http://localhost:9000/mcp/\n\n# With FastMCP CLI for testing\nfastmcp dev mcp_server.py -t streamable-http --port 9000\n```\n\n## Quick Test\n\n**Test STDIO Transport:**\n\n```bash\n# Start server in STDIO mode\npython mcp_server.py --debug --no-auth\n\n# Test with client_example.py\npython client_example.py\n```\n\n**Test HTTP Transport:**\n\n```bash\n# Start HTTP server\npython mcp_server.py --transport http --port 9000 --debug --no-auth\n\n# Test with FastMCP client\npython -c \"\nfrom fastmcp import Client\nimport asyncio\nasync def test():\n    async with Client('http://localhost:9000/mcp') as client:\n        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.\"})\n        print(result)\nasyncio.run(test())\n\"\n```\n\n**Test with FastMCP CLI:**\n\n```bash\n# Start with FastMCP CLI\nfastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG\n\n# Server will be available at: http://127.0.0.1:9000/mcp/\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Import Errors**: Make sure you're in the correct directory and dependencies are installed\n2. **Authentication Errors**: Check your Azure AD configuration and tokens\n3. **Port Conflicts**: Change the port in configuration if 9000 is already in use\n4. **Missing fastmcp**: Install with `pip install fastmcp`\n\n### Debug Mode\n\nEnable debug mode for detailed logging:\n\n```bash\npython mcp_server.py --debug --no-auth\n```\n\nOr set in environment:\n\n```env\nMCP_DEBUG=true\n```\n\n## Server Arguments\n\n```bash\nusage: mcp_server.py [-h] [--transport {stdio,http,streamable-http,sse}]\n                     [--host HOST] [--port PORT] [--debug] [--no-auth]\n\nMHLABS MCP Server\n\noptions:\n  -h, --help            show this help message and exit\n  --transport, -t       Transport protocol (default: stdio)\n  --host HOST           Host to bind to for HTTP transport (default: 127.0.0.1)\n  --port, -p PORT       Port to bind to for HTTP transport (default: 9000)\n  --debug               Enable debug mode\n  --no-auth             Disable authentication\n```\n\n---\n\n## 📄 License\n\nMIT License © 2025 [MusaddiqueHussain Labs](https://github.com/MusaddiqueHussainLabs)\n\n---\n\n## 🤝 Contributing\n\n1. Follow the existing code structure and patterns\n2. Add tests for new functionality\n3. Update documentation for new features\n4. Use the provided VS Code configurations for development\n\n---\n\n## 🧠 Learn More\n\n* **MCP Protocol**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)\n* **FastMCP GitHub**: [https://github.com/fastmcp/fastmcp](https://github.com/fastmcp/fastmcp)\n* **LangGraph Integration Guide** (coming soon)\n\n---\n\n### 💡 Tip\n\nIf you want to embed `mhlabs-mcp-tools` into a larger MCP-based orchestrator:\n\n```python\nfrom fastmcp import StdioServerParameters\nserver_params = StdioServerParameters(\n    command=\"python\",\n    args=[\"-m\", \"mhlabs_mcp_tools.server\"],\n    //env={\"MHLABS_MCP_CATEGORY\": \"textprep,nlp\"}\n)\n```\n\n---\n\n**Developed with ❤️ by [MusaddiqueHussain Labs](https://github.com/MusaddiqueHussainLabs)**\n",
  "bytes": 13668,
  "sha": "1a572cd282a4a682ee3a5e9e69bede7143a1fafca16adcf1025a591184138355",
  "repo_slug": "musaddiquehussainlabs/mhlabs_mcp_tools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_musaddiquehussainlabs_mhlabs_m_a938b752/readme"
}