mhlabs_mcp_tools

mhlabs-mcp-tools

mcp-name: io.github.MusaddiqueHussainLabs/mhlabs_mcp_tools

🧠 mhlabs-mcp-tools

mhlabs-mcp-tools 是一个使用 FastMCP 构建的模块化 MCP 工具服务。
它提供了一个可扩展的 AI 工具生态系统，按功能类别（文本预处理、NLP 组件、文档分析等）组织，可通过 STDIO 传输动态加载并通过 **MCP（模型上下文协议）**提供服务。

本项目是 MHLabs AI Agentic Ecosystem 的一部分，旨在与 mhlabs-mcp-server、mhlabs-mcp-agents 以及下游 A2A Agent 框架协同工作。

---

功能

• FastMCP 服务：纯 FastMCP 实现，支持多种传输协议
• 工厂模式：可复用的 MCP 工具工厂，便于服务管理
• 基于领域的组织方式：按业务领域组织服务（人力资源、技术支持等）
• 身份验证：可选的 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

可用服务

目前，该软件包分为三个主要模块：

1. NLP 组件

组件类型	描述
tokenize	文本分词
pos	词性标注
lemma	词形还原
morphology	词形研究
dep	依存句法分析
ner	命名实体识别
norm	文本规范化

2. 文本预处理

该模块为用户提供一套丰富的文本预处理工具：

Function	Description
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	移除社会安全号码（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. 克隆并进入目录：

   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 许可证 © 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 倾情打造 ❤️