Userful Mcps

🚀 有用的模型库

这是一个用于构建和使用有用模型的库，它提供了多种工具和服务，能帮助用户轻松完成各种任务。

🚀 快速开始

本库旨在助力用户构建和运用实用模型，提供了丰富工具与服务，可满足多样化任务需求。

✨ 主要特性

• 提供多种工具和服务，满足不同任务需求。
• 具备清晰的项目结构，便于开发和维护。
• 提供详细的使用示例，方便用户快速上手。

📦 安装指南

你可以通过以下命令安装该库：

pip install useful-models

💻 使用示例

基础用法

以下代码展示了如何创建一个简单的服务器：

from mcp import Server, Tool, TextContent, stdio_server
import logging

class MyService:
    def __init__(self):
        # 初始化服务时的资源准备
        pass

    def my_function(self, param1: str, param2: int) -> dict:
        # 实现具体的业务逻辑
        logging.info(f"执行 my_function，参数为 {param1=}, {param2=}")
        result_content = f"结果：成功处理了 {param1} 和 {param2}"
        return {"content": result_content}

async def serve() -> None:
    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
    server = Server("mcp-my-service")
    service = MyService()

    @server.list_tools()
    async def list_tools() -> list[Tool]:
        logging.info("list_tools 被调用")
        return [
            Tool(
                name="my.tool",
                description="我的工具描述",
                inputSchema={"type": "object", "properties": {"param1": {"type": "string"}, "param2": {"type": "integer"}}, "required": ["param1", "param2"]}
            ),
        ]

    @server.call_tool()
    async def call_tool(name: str, arguments: dict) -> list[TextContent]:
        logging.info(f"call_tool 被调用，工具名称为 {name=}, 参数为 {arguments=}")
        try:
            if name == "my.tool":
                param1 = arguments.get("param1")
                param2 = arguments.get("param2")
                if not (param1 and param2):
                    raise ValueError("缺少必需的参数")

                result = service.my_function(param1, int(param2))
                logging.info(f"工具执行成功，结果为 {result=}")
                return [TextContent(type="text", text=json.dumps(result))]
            else:
                logging.warning(f"请求了未知的工具：{name}")
                raise ValueError(f"未知工具：{name}")
        except Exception as e:
            logging.error(f"执行工具 {name} 时出错，错误信息为：{e}", exc_info=True)
            error_payload = json.dumps({"error": str(e)})
            return [TextContent(type="text", text=error_payload)]

    options = server.create_initialization_options()
    logging.info("开始启动 MCP 服务器...")
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, options)
    logging.info("MCP 服务器已停止。")

def main():
    try:
        asyncio.run(serve())
    except KeyboardInterrupt:
        logging.info("服务器已被用户中断。")

if __name__ == "__main__":
    # 允许通过直接运行脚本进行调试
    main()

项目结构

• useful-models/: 包含所有模型和工具的实现。
• tests/: 存放测试文件，确保代码质量。

📚 详细文档

测试方法

从根目录运行以下命令即可执行测试：

pytest tests/

⚠️ 重要提示

请确保已安装 pytest。

📄 许可证

本项目遵循 MIT 许可证，具体条款如下：

• 允许任何人自由使用、复制、修改和分发此软件。
• 修改后的版本必须在文档中明确标注。
• 无需支付任何费用。

🤝 贡献指南

欢迎各位贡献代码！请按照以下步骤操作：

1. Fork 项目仓库。
2. 在自己的分支上进行开发。
3. 提交代码并创建 Pull Request。

让我们一起将这个模型库变得更加有用！