mhlabs_mcp_tools

mhlabs-mcp-tools

mcp-name: io.github.MusaddiqueHussainLabs/mhlabs_mcp_tools

🧠 mhlabs-mcp-tools

mhlabs-mcp-tools は、FastMCP を使用して構築された モジュール型 MCP ツールサーバーです。
機能カテゴリ（テキスト前処理、NLP コンポーネント、ドキュメント分析など）ごとに整理された 拡張可能な AI ツールエコシステムを提供し、STDIO トランスポートを介して MCP（Model Context Protocol） 経由で動的に読み込み、提供できます。

このプロジェクトは MHLabs AI Agentic Ecosystem の一部であり、mhlabs-mcp-server、mhlabs-mcp-agents、および下流の A2A エージェントフレームワークと連携するように設計されています。

---

機能

• FastMCP サーバー：複数のトランスポートプロトコルをサポートする、純粋な FastMCP 実装
• ファクトリーパターン：サービスを簡単に管理できる、再利用可能な MCP ツールファクトリー
• ドメインベースの構成：業務ドメイン（人事、テクニカルサポートなど）ごとにサービスを整理
• 認証：Azure AD 認証をオプションでサポート
• 複数のトランスポート：STDIO、HTTP（Streamable）、SSE トランスポートをサポート
• VS Code 連携：デバッグ構成と開発設定
• 包括的なテスト：pytest を使用した単体テスト
• 柔軟な構成：環境ベースの構成管理

アーキテクチャ

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

利用可能なサービス

現在、パッケージは次の3つの主要モジュールで構成されています。

1. NLP コンポーネント

コンポーネントの種類	説明
tokenize	テキストのトークン化
pos	品詞タグ付け
lemma	単語のレンマ化
morphology	語形の研究
dep	依存構造解析
ner	固有表現認識
norm	テキストの正規化

2. テキストの前処理

このモジュールでは、幅広いテキスト前処理ツールを利用できます。

関数	説明
to_lower	テキストを小文字に変換します
to_upper	テキストを大文字に変換します
remove_number	数字を削除します
remove_itemized_bullet_and_numbering	箇条書きの番号や記号を削除します
remove_url	テキストから URL を削除します
remove_punctuation	句読点を削除します
remove_special_character	特殊文字を削除します
keep_alpha_numeric	英数字のみを保持します
remove_whitespace	余分な空白を削除します
normalize_unicode	Unicode 文字を正規化します
remove_stopword	一般的なストップワードを削除します
remove_freqwords	頻出語を削除します
remove_rarewords	まれな単語を削除します
remove_email	メールアドレスを削除します
remove_phone_number	電話番号を削除します
remove_ssn	Social Security Number（SSN）を削除します
remove_credit_card_number	クレジットカード番号を削除します
remove_emoji	絵文字を削除します
remove_emoticons	顔文字を削除します
convert_emoticons_to_words	顔文字を単語に変換します
convert_emojis_to_words	絵文字を単語に変換します
remove_html	HTML タグを削除します
chat_words_conversion	チャット表現を標準的な英語に変換します
expand_contraction	短縮形を展開します（例：「can't」を「cannot」に変換）
tokenize_word	単語をトークン化します
tokenize_sentence	文をトークン化します
stem_word	単語を語幹化します
lemmatize_word	単語を見出し語化します
preprocess_text	複数の前処理手順を1つの関数にまとめます

クイックスタート

開発環境のセットアップ

1. クローンして移動：

   cd src/mhlabs_mcp_tools
   

2. 依存関係をインストール：

   pip install -r requirements.txt
   

3. 環境を設定：

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

4. サーバーを起動：

   # Default STDIO transport (for local MCP clients)
   python mcp_server.py
   
   # HTTP transport (for web-based clients)
   python mcp_server.py --transport http --port 9000
   or
   after installed mhlabs-mcp-tools
   python -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 disabled
   python mcp_server.py --transport http --debug --no-auth
   

トランスポートオプション

1. STDIO トランスポート（デフォルト）

• 🔧 最適な用途：ローカルツール、コマンドライン統合、Claude Desktop
• 🚀 使用方法：python mcp_server.py または python mcp_server.py --transport stdio

2. HTTP（Streamable）トランスポート

• 🌐 最適な用途：Web ベースのデプロイ、マイクロサービス、リモートアクセス
• 🚀 使用方法：python mcp_server.py --transport http --port 9000
• 🌐 URL：http://127.0.0.1:9000/mcp/

3. SSE トランスポート（非推奨）

• ⚠️ レガシーサポートのみです。新しいプロジェクトでは HTTP トランスポートを使用してください
• 🚀 使用方法：python mcp_server.py --transport sse --port 9000

FastMCP CLI の使用方法

# Standard HTTP server
fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG

# With custom host
fastmcp 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 Inspector
fastmcp dev mcp_server.py -t streamable-http --port 9000

VS Code での開発

1. VS Code で開く：

   code .
   

2. デバッグ構成を使用：

   • Debug MCP Server (STDIO)：STDIO トランスポートで実行します
   • Debug MCP Server (HTTP)：HTTP トランスポートで実行します
   • Debug Tests：テストスイートを実行します

設定

環境変数

.env.example を基に .env ファイルを作成します。

# Server Settings
MCP_HOST=0.0.0.0
MCP_PORT=9000
MCP_DEBUG=false
MCP_SERVER_NAME=MHLABS MCP Server

# Authentication Settings
MCP_ENABLE_AUTH=true
AZURE_TENANT_ID=your-tenant-id-here
AZURE_CLIENT_ID=your-client-id-here
AZURE_JWKS_URI=https://login.microsoftonline.com/your-tenant-id/discovery/v2.0/keys
AZURE_ISSUER=https://sts.windows.net/your-tenant-id/
AZURE_AUDIENCE=api://your-client-id

認証

MCP_ENABLE_AUTH=true の場合、サーバーは Azure AD Bearer トークンを要求します。適切な設定で Azure アプリ登録を構成してください。

開発時は、MCP_ENABLE_AUTH=false に設定して認証を無効にします。

新しいサービスの追加

1. サービスクラスを作成します：

   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. サーバーに登録します：

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

3. ドメインを追加します（新しい場合）：

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

MCP クライアントの使用

Python クライアント

import asyncio
from 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())

コマンドラインでのテスト

# Test the server is running
curl http://localhost:9000/mcp/

# With FastMCP CLI for testing
fastmcp dev mcp_server.py -t streamable-http --port 9000

クイックテスト

STDIO トランスポートのテスト：

# Start server in STDIO mode
python mcp_server.py --debug --no-auth

# Test with client_example.py
python client_example.py

HTTP トランスポートのテスト：

# Start HTTP server
python mcp_server.py --transport http --port 9000 --debug --no-auth

# Test with FastMCP client
python -c "
from fastmcp import Client
import asyncio
async 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())
"

FastMCP CLI でのテスト：

# Start with FastMCP CLI
fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG

# Server will be available at: http://127.0.0.1:9000/mcp/

トラブルシューティング

よくある問題

1. インポートエラー：正しいディレクトリにいることと、依存関係がインストールされていることを確認してください
2. 認証エラー：Azure AD の構成とトークンを確認してください
3. ポートの競合：9000 がすでに使用されている場合は、構成でポートを変更してください
4. fastmcp が見つからない：pip install fastmcp でインストールしてください

デバッグモード

詳細なログを記録するには、デバッグモードを有効にします。

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

または、環境変数に設定します。

MCP_DEBUG=true

サーバーの引数

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

---

📄 ライセンス

MIT License © 2025 MusaddiqueHussain Labs

---

🤝 貢献

1. 既存のコード構造とパターンに従ってください
2. 新しい機能にはテストを追加してください
3. 新機能に合わせてドキュメントを更新してください
4. 開発には、提供されている VS Code 構成を使用してください

---

🧠 詳細情報

• MCP プロトコル：https://modelcontextprotocol.io
• FastMCP GitHub：https://github.com/fastmcp/fastmcp
• LangGraph 統合ガイド（近日公開）

---

💡 ヒント

mhlabs-mcp-tools を、より大規模な MCP ベースのオーケストレーターに組み込みたい場合：

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

---

MusaddiqueHussain Labs が ❤️ を込めて開発