Mhlabs MCP Tools

🚀 mhlabs-mcp-tools

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

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

✨ 主な機能

• FastMCPサーバー：複数のトランスポートプロトコルをサポートする純粋なFastMCP実装
• ファクトリパターン：サービス管理を容易にするための再利用可能なMCPツールファクトリ
• ドメインベースの組織化：ビジネスドメイン（HR、テクニカルサポートなど）ごとにサービスが組織化されています
• 認証：オプションのAzure AD認証サポート
• 複数のトランスポート：STDIO、HTTP（ストリーミング可能）、および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コンポーネント

2. テキスト前処理

このモジュールは、ユーザーに幅広いテキスト前処理ツールを提供します。

🚀 クイックスタート

開発環境のセットアップ

1. クローンして移動する：

   cd src/mhlabs_mcp_tools
   

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

   pip install -r requirements.txt
   

3. 環境を設定する：

   cp .env.example .env
   # .env を自分の設定で編集する
   

4. サーバーを起動する：

   # デフォルトのSTDIOトランスポート（ローカルのMCPクライアント用）
   python mcp_server.py
   
   # HTTPトランスポート（ウェブベースのクライアント用）
   python mcp_server.py --transport http --port 9000
   または
   mhlabs-mcp-tools をインストールした後
   python -m mhlabs_mcp_tools.mcp_server --transport http --port 9000
   
   # FastMCP CLIを使用する（推奨）
   fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
   
   # 認証を無効にしたデバッグモード
   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（ストリーミング可能）トランスポート

• 🌐 適用対象：ウェブベースのデプロイメント、マイクロサービス、リモートアクセス
• 🚀 使用方法：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の使用方法

# 標準のHTTPサーバー
fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG

# カスタムホストを使用する
fastmcp run mcp_server.py -t streamable-http --host 0.0.0.0 --port 9000 -l DEBUG

# STDIOトランスポート（ローカルクライアント用）
fastmcp run mcp_server.py -t stdio

# MCPインスペクターを使用した開発モード
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 ファイルを作成します。

# サーバー設定
MCP_HOST=0.0.0.0
MCP_PORT=9000
MCP_DEBUG=false
MCP_SERVER_NAME=MHLABS MCP Server

# 認証設定
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ベアラートークンを期待します。適切な設定で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:
               # ツールの実装
               pass
   
       @property
       def tool_count(self) -> int:
           return 1  # ツールの数
   

2. サーバーに登録する：

   # mcp_server.py で（services/ ディレクトリから自動的に登録されます）
   factory.register_service(MyService())
   

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

   # core/factory.py で
   class Domain(Enum):
       # ... 既存のドメイン
       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())

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

# サーバーが動作していることをテストする
curl http://localhost:9000/mcp/

# テスト用のFastMCP CLIを使用する
fastmcp dev mcp_server.py -t streamable-http --port 9000

クイックテスト

STDIOトランスポートをテストする：

# STDIOモードでサーバーを起動する
python mcp_server.py --debug --no-auth

# client_example.py でテストする
python client_example.py

HTTPトランスポートをテストする：

# HTTPサーバーを起動する
python mcp_server.py --transport http --port 9000 --debug --no-auth

# FastMCPクライアントでテストする
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でテストする：

# FastMCP CLIで起動する
fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG

# サーバーは以下のURLで利用可能になります：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            このヘルプメッセージを表示して終了する
  --transport, -t       トランスポートプロトコル（デフォルト: stdio）
  --host HOST           HTTPトランスポートでバインドするホスト（デフォルト: 127.0.0.1）
  --port, -p PORT       HTTPトランスポートでバインドするポート（デフォルト: 9000）
  --debug               デバッグモードを有効にする
  --no-auth             認証を無効にする

📄 ライセンス

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"}
)

Developed with ❤️ by MusaddiqueHussain Labs