Mhlabs MCP Tools

🚀 mhlabs-mcp-tools

mhlabs-mcp-tools 是一個基於 FastMCP 構建的模塊化 MCP 工具服務器。它提供了一個可擴展的 AI 工具生態系統，這些工具按功能類別（文本預處理、NLP 組件、文檔分析等）組織，可以通過 MCP（模型上下文協議） 經由 STDIO 傳輸 進行動態加載和服務。

本項目是 MHLabs AI 代理生態系統 的一部分，旨在與 mhlabs-mcp-server、mhlabs-mcp-agents 以及下游 A2A 代理框架協同工作。

🚀 快速開始

開發環境搭建

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 傳輸（適用於基於 Web 的客戶端）
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（可流式傳輸）傳輸

• 🌐 適用場景：基於 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 使用方法

# 標準 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：運行測試套件

✨ 主要特性

• FastMCP 服務器：純 FastMCP 實現，支持多種傳輸協議
• 工廠模式：可複用的 MCP 工具工廠，便於服務管理
• 基於領域的組織方式：服務按業務領域（人力資源、技術支持等）組織
• 認證功能：可選的 Azure AD 認證支持
• 多種傳輸方式：支持 STDIO、HTTP（可流式傳輸）和 SSE 傳輸
• VS Code 集成：提供調試配置和開發設置
• 全面測試：使用 pytest 進行單元測試
• 靈活配置：基於環境的配置管理

📦 安裝指南

環境變量

基於 .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 設置為禁用認證。

💻 使用示例

基礎用法

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

# 服務器地址：http://127.0.0.1:9000/mcp/

📚 詳細文檔

可用服務

目前，該軟件包主要分為三個模塊：

1. NLP 組件

2. 文本預處理

該模塊為用戶提供了豐富的文本預處理工具：

添加新服務

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

🔧 技術細節

架構

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

服務器參數

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 許可證 © 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 用心開發 ❤️