MCP Database Tools

MCP数据库工具服务器

📋 目录

• 概述
• 建筑
• 项目结构
• 组件流程
• 安装和设置
• 用法
• 配置
• 故障排除

______________________________________________________________________

🎯 概述

这个项目是 模型上下文协议（MCP）服务器 它自动化了Django数据库的设置和管理任务。它提供了以下工具：

• 创建PostgreSQL数据库
• 启用PostgreSQL扩展（hstore）
• 更新Django.env配置文件
• 执行Django管理命令

服务器与VS Code Copilot集成，可以通过以下方式访问：

• VS代码MCP集成
• 自动化工作流脚本

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client Layer                          │
│  ┌──────────────┐  ┌──────────────┐                           │
│  │  VS Code     │  │   Workflow   │                           │
│  │  Copilot     │  │   Scripts    │                           │
│  └──────┬───────┘  └──────┬───────┘                           │
└─────────┼──────────────────┼──────────────────┼──────────────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
                    ┌────────▼────────┐
                    │   MCP Server    │
                    │   (server.py)   │
                    │                 │
                    │  - list_tools() │
                    │  - call_tool()  │
                    └────────┬────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
    ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
    │PostgreSQL │     │  Django   │     │   .env    │
    │ Database  │     │  Backend  │     │   File    │
    └───────────┘     └───────────┘     └───────────┘

______________________________________________________________________

📁 项目结构

MCP_project/
│
├── server.py                  # Main MCP server implementation
├── mcp.json                   # MCP server metadata
├── requirements.txt           # Python dependencies
│
* Web and CLI clients removed: The project no longer includes web_client.py or test_client.py files.
├── run_workflow.py           # Automated workflow executor
│
├── tools/                    # Utility modules (legacy/reference)
│   ├── __init__.py
│   ├── db_tools.py          # PostgreSQL database operations
│   ├── env_tools.py         # Environment file management
│   └── django_tools.py      # Django command execution
│
├── templates/               # Web UI templates
│   └── index.html          # Main web interface
│
└── venv/                   # Python virtual environment

______________________________________________________________________

🔄 组件流程

1. 核心服务器（Server.py）

系统的核心，实现MCP协议：

┌─────────────────────────────────────────────────────────┐
│                    server.py                             │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Configuration:                                          │
│  ├─ PG_USER, PG_PASSWORD, PG_HOST                       │
│  ├─ DB_NAME (default: sample_project_db)                │
│  ├─ ENV_PATH (Django .env location)                     │
│  ├─ MANAGE_PY (Django manage.py location)               │
│  └─ PYTHON_EXEC (Virtual environment Python)            │
│                                                          │
│  MCP Server Decorators:                                 │
│  ├─ @server.list_tools() → Returns available tools      │
│  └─ @server.call_tool() → Executes tool operations      │
│                                                          │
│  Tools Implemented:                                      │
│  ├─ create_database(db_name)                            │
│  ├─ enable_hstore(db_name)                              │
│  ├─ update_env(db_name)                                 │
│  └─ django(cmd)                                          │
└─────────────────────────────────────────────────────────┘

主要特点：

• 异步/等待架构 符合MCP协议
• stdio通信 （非HTTP）用于MCP客户端集成
• 自动小写转换 PostgreSQL数据库名称
• 环境变量加载 Django命令的.env文件
• 虚拟环境Python 执行以确保依赖关系

______________________________________________________________________

2. 工具：create_database

Input: { db_name: "mydb" }
│
├─ Converts db_name to lowercase ("mydb")
│
├─ Connects to PostgreSQL server (postgres database)
│  └─ Uses: PG_USER, PG_PASSWORD, PG_HOST
│
├─ Executes: CREATE DATABASE mydb;
│
└─ Returns: "Database mydb created."

PostgreSQL连接：

psycopg2.connect(
    dbname="postgres",
    user=PG_USER, 
    password=PG_PASSWORD,
    host=PG_HOST
)

______________________________________________________________________

3. 工具：enable_hstore

Input: { db_name: "mydb" }
│
├─ Converts db_name to lowercase
│
├─ Connects to the specified database
│
├─ Executes: CREATE EXTENSION IF NOT EXISTS hstore;
│
└─ Returns: "hstore extension enabled in mydb."

目的： 启用PostgreSQL的hstore扩展用于键值对存储。

______________________________________________________________________

4. 工具：update_env

Input: { db_name: "mydb" }
│
├─ Converts db_name to lowercase
│
├─ Reads ENV_PATH file
│
├─ Finds line: POSTGRES_DB_NAME=old_value
│  └─ Skips commented lines (#)
│
├─ Replaces with: POSTGRES_DB_NAME=mydb
│
└─ Returns: ".env updated: POSTGRES_DB_NAME=mydb"

文件操作：

• 保留所有其他.env内容
• 仅更新未注释的POSTGRES_DB_NAME行
• 维护文件结构和格式

______________________________________________________________________

5. 工具：django

Input: { cmd: "migrate" }
│
├─ Loads environment from ENV_PATH using dotenv
│  └─ Merges with os.environ
│
├─ Executes: PYTHON_EXEC MANAGE_PY migrate
│  └─ In working directory: dirname(MANAGE_PY)
│  └─ With loaded environment variables
│
├─ Captures stdout and stderr
│
└─ Returns: Command output with exit code

执行流程：

subprocess.run(
    [PYTHON_EXEC, MANAGE_PY] + cmd.split(),
    cwd=workdir,
    env=env,  # Loaded from .env
    capture_output=True,
    text=True
)

为什么选择虚拟环境Python？

• 虚拟环境中安装的Django和依赖项
• 系统Python缺少必需的包
• 确保一致的执行环境

______________________________________________________________________

客户端接口

访问服务器主要是通过VS Code MCP集成和自动化工作流脚本。

C 工作流自动化（run_Workflow.py）

Complete Database Setup Workflow
┌─────────────────────────────────────────┐
│  Step 1: Create database                 │
│  Step 2: Enable hstore extension         │
│  Step 3: Update .env file                │
│  Step 4: Run create_text_search_config   │
│  Step 5: Run migrations                  │
│  Step 6: Run update_fixtures             │
└─────────────────────────────────────────┘

用途：

python run_workflow.py mydb

它的作用：

1. 创建PostgreSQL数据库“mydb”
2. 启用hstore扩展
3. 使用POSTGRES_DB_NAME=mydb更新.env
4. 按顺序运行Django设置命令
5. 报告每个步骤的成功/失败

______________________________________________________________________

🛠️ 安装和设置

先决条件

• Python 3.12+
• PostgreSQL服务器正在运行
• Django项目（可选，用于Django命令）

步骤1：克隆/设置项目

cd /home/chaitanyaphani/MCP_project

第二步：创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

步骤3：安装依赖项

pip install -r requirements.txt

依赖关系：

• mcp -模型上下文协议SDK
• Flask -Web UI框架
• psycopg2-binary -PostgreSQL适配器
• python-dotenv -环境文件支持

步骤4：配置PostgreSQL

编辑 server.py:

PG_USER = "postgres"
PG_PASSWORD = "your_password"  # Update this!
PG_HOST = "localhost"

步骤5：配置Django路径

编辑 server.py:

ENV_PATH = "/path/to/your/django/.env"
MANAGE_PY = "/path/to/your/django/manage.py"
PYTHON_EXEC = "/path/to/your/django/venv/bin/python"

步骤6：配置VS代码（可选）

编辑VS代码设置(settings.json):

{
  "mcpServers": {
    "dbtools": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/home/chaitanyaphani/MCP_project"
    }
  }
}

______________________________________________________________________

🚀 用法

方法1：自动化工作流程

python run_workflow.py database_name

方法2:VS代码复制

配置后，只需询问： 配置后，只需询问：

"Create a database named myproject, enable hstore, 
update the .env file, and run migrations"

______________________________________________________________________

⚙️ 配置

环境变量

服务器使用这些配置常量：

Django.env文件格式

预期格式：

POSTGRES_DB_HOST=localhost
POSTGRES_DB_PORT=5432
POSTGRES_DB_NAME=mydb
POSTGRES_DB_USER=postgres
POSTGRES_DB_PASSWORD=password

______________________________________________________________________

🔍 故障排除

问题1:“AttributeError:'服务器'对象没有属性'define_tool'”

原因： 使用不正确的MCP装饰器语法。\ 解决方案： 使用 @server.list_tools() 和 @server.call_tool() 而不是 @server.define_tool.

问题2：“用户'postgres'的密码验证失败”

原因： PostgreSQL密码不正确。\ 解决方案： 更新 PG_PASSWORD 在 server.py 使用您的实际PostgreSQL密码。

问题3：“ModuleNotFoundError:没有名为'django'的模块”

原因： 使用系统Python而不是虚拟环境Python。\ 解决方案： 确保 PYTHON_EXEC 指向Django项目的虚拟环境Python。

问题4：“数据库'XX'不存在”（大写名称）

原因： PostgreSQL将未加引号的标识符转换为小写。\ 解决方案： 服务器现在自动将数据库名称转换为小写。

问题5：“.env已更新，但数据库名称未更改”

原因： 在.env文件中查找错误的变量名。\ 解决方案： 确保您的.env使用 POSTGRES_DB_NAME= （不是 POSTGRES_DB=).

问题6：“迁移后未创建表”

原因： 未加载环境变量，或Python可执行文件错误。\ 解决：

• 验证 PYTHON_EXEC 指向正确的虚拟环境
• 检查 .env 文件已加载并包含正确的数据库名称
• 手动运行migrate以查看详细错误

______________________________________________________________________

📊 数据流图

完整工作流示例

User Request: "Create database 'myapp'"
│
├─ VS Code Copilot/Web UI/CLI
│  └─ Sends MCP request to server.py
│
├─ server.py receives call_tool("create_database", {"db_name": "myapp"})
│  │
│  ├─ Step 1: create_database
│  │  ├─ Convert "myapp" → "myapp" (lowercase)
│  │  ├─ Connect to PostgreSQL
│  │  ├─ Execute: CREATE DATABASE myapp;
│  │  └─ Return: "Database myapp created."
│  │
│  ├─ Step 2: enable_hstore
│  │  ├─ Connect to "myapp" database
│  │  ├─ Execute: CREATE EXTENSION IF NOT EXISTS hstore;
│  │  └─ Return: "hstore extension enabled in myapp."
│  │
│  ├─ Step 3: update_env
│  │  ├─ Read /path/to/.env
│  │  ├─ Find: POSTGRES_DB_NAME=olddb
│  │  ├─ Replace with: POSTGRES_DB_NAME=myapp
│  │  ├─ Write back to file
│  │  └─ Return: ".env updated: POSTGRES_DB_NAME=myapp"
│  │
│  └─ Step 4: django("migrate")
│     ├─ Load .env into environment
│     ├─ Execute: /venv/bin/python manage.py migrate
│     │  └─ Django reads POSTGRES_DB_NAME=myapp from env
│     │  └─ Connects to "myapp" database
│     │  └─ Applies migrations
│     └─ Return: Migration output
│
└─ Result returned to user

______________________________________________________________________

🎓 关键概念

模型上下文协议（MCP）

• 协议 让AI助手与工具进行交互
• 基于stdio 通信（非HTTP）
• 异步/等待 需要图案
• 工具注册 通过 list_tools()
• 工具执行 通过 call_tool()

为什么是这种架构？

1. 关注点分离：服务器逻辑与客户端接口分开
2. 多个接口：相同的服务器，不同的访问方法
3. 类型安全：带模式验证的MCP协议
4. 错误处理：全面的错误报告
5. 环境隔离：使用虚拟环境Python

PostgreSQL命名规则

• 转换为小写的无引号标识符
• CREATE DATABASE MyDB 创造 mydb
• 服务器自动处理此转换

______________________________________________________________________

📝 工具参考

create_database

{
  "name": "create_database",
  "arguments": {
    "db_name": "string (optional, default: sample_project_db)"
  },
  "returns": "Database {db_name} created."
}

enable_hstore

{
  "name": "enable_hstore",
  "arguments": {
    "db_name": "string (optional, default: sample_project_db)"
  },
  "returns": "hstore extension enabled in {db_name}."
}

update_env

{
  "name": "update_env",
  "arguments": {
    "db_name": "string (optional, default: sample_project_db)"
  },
  "returns": ".env updated: POSTGRES_DB_NAME={db_name}"
}

姜戈

{
  "name": "django",
  "arguments": {
    "cmd": "string (required) - Django management command"
  },
  "returns": "Command output (stdout/stderr)"
}

常见的Django命令：

• migrate -应用数据库迁移
• makemigrations -创建新的迁移
• create_text_search_config -自定义命令
• update_fixtures -定制夹具管理
• runserver -启动开发服务器

______________________________________________________________________

🤝 贡献

要使用新工具扩展此服务器，请执行以下操作：

1. 在中添加工具定义 list_tools():

Tool(
    name="my_new_tool",
    description="What it does",
    inputSchema={
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "..."}
        },
        "required": ["param1"]
    }
)

1. 在中添加工具实现 call_tool():

elif name == "my_new_tool":
    param1 = arguments.get("param1")
    # Your logic here
    return [TextContent(type="text", text="Result")]

______________________________________________________________________

📞 支持

对于问题或疑问：

1. 检查故障排除部分
2. 验证中的配置 server.py
3. 测试用 run_workflow.py 用于调试/自动化
4. 检查PostgreSQL日志中的数据库问题
5. 检查Django日志中的Django命令问题

______________________________________________________________________

📄 许可证

该项目是Altiushub后端基础设施的一部分。

______________________________________________________________________

最后更新时间： 2025年12月12日\ 版本： 1.0.0\ MCP协议版本： 与MCP SDK最新版本兼容