Fluent MCP

Fluent MCP

一个用于构建具备智能推理能力的 Model Context Protocol（MCP）服务的现代框架。

概述

Fluent MCP 是一套用于搭建和管理 MCP 服务的工具包，专注于 AI 集成。它提供了一种结构化的方法，用于构建能够借助大模型进行嵌入式推理、注册和执行工具，以及管理提示词和配置的服务。

该框架旨在支持扩展，让大模型能够构建并注册自己的工具，从而支持开发可自我改进的 AI 系统。

核心架构模式

Fluent MCP 实现了一种强大的架构模式，从根本上改变了 AI 系统的交互方式：

双层大模型架构

• 嵌入式大模型：用于执行复杂推理和多步骤任务的内部大模型
• 调用方大模型：与 MCP 服务交互的外部大模型（例如 Claude）

工具分离

• 嵌入式工具：仅供嵌入式大模型使用的内部工具，不对外公开
• 外部工具：通过 MCP 协议向调用方大模型公开的工具

推理卸载

• 将复杂的多步骤推理从调用方大模型卸载到嵌入式大模型
• 外部工具可在内部利用嵌入式推理，同时提供简单的接口
• 这形成了一个“推理三明治”，复杂逻辑在中间层完成

优势

• 提高令牌效率：调用方大模型将推理卸载到嵌入式大模型，从而减少令牌用量
• 降低成本：规模较小的专用模型可以低成本地处理特定推理任务
• 隐藏复杂性：复杂的多步骤流程隐藏在简单接口之后
• 关注点分离：清晰划分对外公开的内容与内部功能

功能

• 推理卸载：将复杂推理从调用方大模型卸载到嵌入式大模型，从而提高令牌效率并降低成本
• 工具分离：清晰区分嵌入式工具（内部使用）和外部工具（对外公开）
• 服务搭建：生成结构规范的新 MCP 服务项目
• 大模型集成：轻松连接不同提供商的大模型
• 工具注册表：注册嵌入式工具（内部使用）和外部工具（向调用方大模型公开）
• 嵌入式推理：使用大模型进行推理并执行其工具调用
• 提示词管理：从文件加载和管理提示词，并支持在 frontmatter 中定义工具
• 错误处理：为大模型集成和工具执行提供健壮的错误处理

安装

pip install fluent_mcp

用于开发：

# Clone the repository
git clone https://github.com/yourusername/fluent_mcp.git
cd fluent_mcp

# Install in development mode with extra dependencies
pip install -e ".[dev]"

快速开始

创建新服务

使用 CLI 搭建新服务：

fluent-mcp new my_server

也可以通过编程方式创建服务：

from fluent_mcp import scaffold_server

scaffold_server(
    output_dir=".",
    server_name="my_server",
    description="My MCP server with AI capabilities"
)

实现核心架构模式

from fluent_mcp.core.tool_registry import register_embedded_tool, register_external_tool
from fluent_mcp.core.llm_client import run_embedded_reasoning
import asyncio

# 1. Define embedded tools (ONLY available to the embedded LLM)
@register_embedded_tool()
def search_database(query: str) -> list:
    """Search the database for information (only used internally)."""
    # Implementation...
    return ["result1", "result2"]

@register_embedded_tool()
def analyze_data(data: list) -> dict:
    """Analyze data and extract insights (only used internally)."""
    # Implementation...
    return {"key_insight": "finding", "confidence": 0.95}

# 2. Define an external tool that leverages embedded reasoning
@register_external_tool()
async def research_question(question: str) -> dict:
    """
    Research a question and provide a comprehensive answer.
    
    This external tool is exposed to consuming LLMs but internally
    uses embedded reasoning with access to embedded tools.
    """
    # Define system prompt for embedded reasoning
    system_prompt = """
    You are a research assistant with access to internal tools:
    - search_database: Search for information
    - analyze_data: Analyze and extract insights
    
    Use these tools to thoroughly research the question.
    """
    
    # Run embedded reasoning (this is where the magic happens)
    result = await run_embedded_reasoning(
        system_prompt=system_prompt,
        user_prompt=f"Research this question: {question}"
    )
    
    # Return a clean, structured response to the consuming LLM
    return {
        "answer": result["content"],
        "confidence": 0.9,
        "sources": ["source1", "source2"]
    }

使用架构模式运行服务

from fluent_mcp import create_mcp_server
from my_tools import search_database, analyze_data, research_question

# Create and run MCP server
server = create_mcp_server(
    server_name="my_server",
    # Embedded tools (ONLY available to the embedded LLM)
    embedded_tools=[search_database, analyze_data],
    # External tools (exposed to consuming LLMs)
    external_tools=[research_question],
    config={
        "provider": "ollama",
        "model": "llama2",
        "base_url": "http://localhost:11434",
        "api_key": "ollama"
    }
)

server.run()

使用带工具定义的提示词

Fluent MCP 支持直接在提示词的 frontmatter 中定义该提示词可用的工具：

---
name: math_tools
description: A prompt that uses math-related tools
model: gpt-4
temperature: 0.3
tools:
  - add_numbers
  - multiply_numbers
---
You are a math assistant that can perform calculations.
Use the available tools to help solve math problems.

将此提示词用于嵌入式推理时，仅指定的工具可用：

from fluent_mcp.core.llm_client import run_embedded_reasoning

# Get a prompt with tool definitions
math_prompt = server.get_prompt("math_tools")

# Run embedded reasoning with only the tools defined in the prompt
result = await run_embedded_reasoning(
    system_prompt=math_prompt["template"],
    user_prompt="What is 5 + 3?",
    prompt=math_prompt  # Pass the prompt to use its tool definitions
)

这种方法可以更精确地控制不同提示词可使用的工具，从而提升安全性并降低意外使用工具的可能性。

文档

如需更详细的文档，请参阅 文档目录：

• 入门指南
• 创建工具
• 运行服务
• 嵌入式推理
• 速率限制
• 自我改进系统
• 故障排除
• API 参考

示例

请查看示例目录，了解完整的可运行示例：

• 工具注册表示例
• 嵌入式推理示例
• 外部工具示例
• 推理外部工具示例
• 提示词加载器示例
• 提示词工具示例

开发

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
flake8
black .
isort .

许可证

MIT