Tidewave Python MCP服务器旨在将您的Python Web应用程序转化为一个功能强大的LLM上下文提供者。它通过标准化的Model Context Protocol (MCP) 与LLM客户端通信，允许LLM深入理解、操作和调试您的项目。

项目简介

Tidewave可作为全栈Web应用开发的编码代理，与Python主流Web框架（Django, Flask, FastAPI）深度集成，覆盖从数据库到用户界面的各个层面。它也可作为一个独立的MCP服务器，为您的开发环境提供丰富的上下文服务。

主要功能点

上下文提供: 向LLM提供关于项目结构、代码、日志、文档和数据库模型等丰富的上下文信息。
工具执行: 允许LLM调用预定义的工具，例如：
- Python代码评估 ('project_eval'): 在项目环境中执行Python代码，获取结果和输出。
- SQL查询执行 ('execute_sql_query'): 对连接的数据库执行SQL查询，方便LLM理解和操作数据。
- 模型发现 ('get_models'): 列出Django或SQLAlchemy中的所有数据库模型及其文件路径。
- 日志访问 ('get_logs'): 获取应用程序的运行时日志，帮助LLM诊断问题。
- 代码源定位 ('get_source_location'): 查找任何Python模块、类或函数的源代码位置。
- 文档获取 ('get_docs'): 获取任何Python模块、类或函数的文档字符串。
模板调试: 为Django和Jinja2模板渲染添加HTML注释，帮助LLM理解UI组件的来源和继承关系。
JSON-RPC通信: 通过标准JSON-RPC协议与LLM客户端进行高效、结构化的交互。
会话管理与安全: 支持会话管理、能力声明，并提供IP和来源（Origin）验证等安全机制。

安装步骤

Tidewave作为您现有Python Web应用程序的插件运行。

安装依赖: 首先，确保您的项目已配置'uv'或'pip'。然后，根据您使用的Web框架添加Tidewave依赖。

Django: 在您的'pyproject.toml'中添加依赖：

"tidewave[django] @ git+https://github.com/tidewave-ai/tidewave_python.git",

在'settings.py'的'INSTALLED_APPS'和'MIDDLEWARE'定义之后（通常在'DEBUG'模式下）：

if DEBUG:
    INSTALLED_APPS.insert(0, "tidewave.django.apps.TidewaveConfig")
    MIDDLEWARE.insert(0, 'tidewave.django.Middleware')

如果使用Jinja2，也需添加扩展：

JINJA2_ENVIRONMENT_OPTIONS = {
    "extensions": [
        "tidewave.jinja2.Extension"
    ],
}

Flask: 在您的'pyproject.toml'中添加依赖：

"tidewave[flask] @ git+https://github.com/tidewave-ai/tidewave_python.git",

在您的Flask应用中（确保'app.debug'为'True'）：

if app.debug:
    from tidewave.flask import Tidewave
    tidewave = Tidewave()
    tidewave.init_app(app)

FastAPI: 在您的'pyproject.toml'中添加依赖：

"tidewave[fastapi] @ git+https://github.com/tidewave-ai/tidewave_python.git",

在您的FastAPI应用中（确保在开发模式下）：

is_dev = os.environ.get("RUN_MODE", None) == "development" # 或您自定义的判断方式

if is_dev:
    from tidewave.fastapi import Tidewave
    tidewave = Tidewave()
    tidewave.install(app)

如果使用Jinja2，也需添加扩展：

if is_dev:
    # ...
    from tidewave.jinja2 import Extension
    templates.env.add_extension(Extension)

如果使用SQLAlchemy，请传递'sqlalchemy_base'和'sqlalchemy_engine'参数：

tidewave.install(app, sqlalchemy_base=Base, sqlalchemy_engine=engine)

服务器配置 (面向MCP客户端)

Tidewave作为您现有Python Web应用程序的一部分运行。MCP客户端需要知道如何启动您的Web应用，并连接到Tidewave暴露的MCP端点。以下是一个示例JSON配置，用于指导MCP客户端如何连接到Tidewave服务器：

{
  "server_name": "我的Python Web项目", // MCP客户端中服务器的显示名称，您可以自定义
  "command": "uv",                   // 用于启动Python应用的命令，例如 'uv' 或 'python'
  "args": [                          // 启动命令的参数列表
    "run",                           // 'uv run' 的第一个参数
    "python",                        // 'uv run python' 的第二个参数
    "examples/fastapi_app.py",       // 您的应用程序入口文件路径，例如 'my_project/app.py'
    "--host", "localhost",           // 指定应用监听的主机
    "--port", "8000",                // 指定应用监听的端口
    "--reload"                       // （可选）开发模式下的热重载参数
  ],
  "url": "http://localhost:8000/tidewave/mcp", // Tidewave MCP服务器的完整URL端点
  "capabilities": {
    "protocolVersion": "2025-03-26"  // MCP协议版本，用于兼容性检查
  }
}

说明:

'server_name': 在MCP客户端界面中显示的服务器名称。
'command': 您的Python Web应用程序的启动命令（例如，'uv' 或 'python'）。
'args': 传递给'command'的命令行参数列表。请根据您的实际应用程序启动方式进行调整。例如，如果您的应用通过'python manage.py runserver'启动，'command'可能是'python'，'args'可能是'["manage.py", "runserver"]'。
'url': Tidewave服务器的MCP端点URL。默认情况下，它通常是'http://<您的应用主机>:<您的应用端口>/tidewave/mcp'。请确保您的Web应用以调试/开发模式运行，并在'localhost'上可访问，或者根据您的'allow_remote_access'和'allowed_origins'配置允许远程访问。

基本使用方法 (面向LLM客户端)

一旦MCP服务器成功运行，LLM客户端即可通过发送JSON-RPC请求与Tidewave交互：

初始化连接: 发送'initialize'请求以协商协议版本和获取服务器能力。
获取可用工具: 发送'tools/list'请求以获取所有可用工具的列表及其Schema定义。
调用工具: LLM根据需要，使用'tools/call'请求调用特定工具，并提供相应的参数。
接收通知: Tidewave可能发送'notifications/initialized'或'notifications/cancelled'等通知。
ping测试: LLM可发送'ping'请求以测试服务器的连接状态。

注意事项

Tidewave通常仅在应用程序的调试/开发模式下运行（例如，Django的'DEBUG=True'，Flask的'app.debug=True'，FastAPI的开发模式）。
默认情况下，Tidewave限制为仅接受来自'localhost'的连接。若需远程访问，请配置'allow_remote_access: true'。

关键词