使用说明
🤖 基于MCP服务器的人工智能任务管理系统
使用Django、FastMCP和Docker构建的全面个人助理，提供智能任务管理、笔记、电子邮件自动化、天气更新、新闻聚合和提醒功能。
✨ 特性
🎯 核心功能
- 智能笔记管理 ✅: 通过自动数据库处理创建、列出和管理笔记
- 电子邮件自动化 ✅: 通过与Gmail集成的SMTP发送电子邮件
服务API
- 新闻聚合 🔄: 按类别和国家获取最新新闻头条 （即将推出）
- 提醒系统 🔄: 设置具有后台处理功能的基于时间的提醒 （即将推出）
- 天气情报 🔄: 使用国家天气获取详细的天气预报和警报 （即将推出）
🛠️ 技术特性
- FastMCP集成：用于无缝AI工具交互的模型上下文协议
- PostgreSQL数据库：具有自动连接重试功能的强大数据持久性
- Docker Compose：具有健康检查的多服务编排
- 异步操作：无阻塞操作，性能更佳
- 错误处理：具有优雅回退功能的全面错误处理
🏗️ 建筑
系统组件
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ FastMCP │ │ Django Web │ │ PostgreSQL │
│ Assistant │◄──►│ Application │◄──►│ Database │
│ (Tools) │ │ (Notes UI) │ │ (Docker) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ External │ │ Docker │ │ Docker │
│ APIs │ │ Compose │ │ Compose │
│ (Gmail SMTP) │ │ (Orchestration)│ │ (Orchestration) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
工具生态系统
| 工具 | 功能 | 状态 | 描述 |
|---|---|---|---|
notes_tool.py |
笔记管理 | ✅ 活跃的 | 使用web UI创建、列出和管理笔记 |
email_tool.py |
电子邮件发送 | ✅ 活跃的 | 通过支持异步的SMTP发送电子邮件 |
weather_tool.py |
天气数据 | 🔄 即将推出 | 从NWS API获取预测和警报 |
news_tool.py |
新闻头条 | 🔄 即将推出 | 按类别和国家获取新闻 |
reminder_tool.py |
提醒 | 🔄 即将推出 | 设置基于时间的提醒 |
🚀 快速开始
先决条件
- 码头工人 和 Docker Compose
- Python 3.11+（用于本地开发）
- PostgreSQL（由Docker处理）
1.克隆和设置
git clone https://github.com/Burak-Akca/AI-Powered-Task-Management-System-With-MCP-Server
cd AI-Powered-Task-Management-System-With-MCP-Server
2.环境配置
创建一个 .env 项目根目录中的文件：
# Database Configuration
POSTGRES_DB=notedb
POSTGRES_USER=noter
POSTGRES_PASSWORD=noterpass
DB_NAME=notedb
DB_USER=noter
DB_PASSWORD=noterpass
DB_HOST=db
DB_PORT=5432
# Application Settings
DEBUG=True
3.开发设置
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install MCP server (required for Claude integration)
uv run mcp install assistant.py
# Run Django migrations
docker compose exec web python manage.py migrate
# Access database (optinal)
docker compose exec db psql -U noter -d notedb
# Start all services
docker compose up --build -d
4.MCP服务器安装和配置
在虚拟环境中安装依赖项后，运行MCP服务器安装命令：
uv run mcp install assistant.py
此命令执行以下操作以运行 assistant.py 以MCP兼容的方式：
- 孤立的Python环境：用途
uv在隔离的Python环境中运行MCP命令 - MCP服务器注册：应用
mcp install assistant.py在中加载或注册MCP服务器的命令assistant.py - 自动配置：自动将MCP服务器注册到您的Claude配置文件中
手动配置（如果需要）
如果遇到默认配置错误，请使用以下内容手动更新Claude Desktop配置文件：
{
"mcpServers": {
"personal_assistant": {
"command": "uv",
"args": [
"--directory",
"give project root directory path here",
"run",
"assistant.py"
]
}
}
}
备注：替换 "give project root directory path here" 使用您实际的项目根目录路径。
5.访问应用程序
- web界面: http://localhost:8001
- API助理：在默认的FastMCP端口上运行
🛠️ 工具使用
📝 票据管理 ✅ 现已上市
🛠️ 工具：add_note
📌 描述：添加带有标题和可选内容的新注释。
💬 示例提示:
Create a new note with the title "Meeting Summary" and the content "Discussed project deadlines and assigned tasks to the team."
# Add a new note
add_note(title="Meeting Notes", content="Important discussion points...")
🛠️ 工具：list_notes
📌 描述：从数据库中检索最新笔记。
💬 示例提示:
Show me the notes.
# List recent notes
list_notes(limit=10)
🛠️ 工具：start_notes_app
📌 描述：通过Docker启动Django notes应用程序，并在浏览器中打开它。
💬 示例提示:
Start the notes application and open it in the browser.
# Start the notes web application
start_notes_app()
📧 电子邮件自动化 ✅ 现已上市
🛠️ 工具：send_email
📌 描述：使用Gmail的SMTP服务发送电子邮件。
🔐 必填字段:
to_email：收件人的电子邮件地址subject：电子邮件的主题body：消息的正文内容from_email：发件人的Gmail地址password：Gmail应用程序密码（不是您的常规帐户密码）
🛡️ 重要：如果您使用的是Gmail，您必须生成一个应用程序密码，并使用该密码而不是您的正常帐户密码。启用双因素身份验证时，这是必需的。
💬 示例提示:
Send an email to example@gmail.com with the subject "Weekly Sync" and the message "Meeting starts at 10 AM sharp." Use my Gmail address example@customdomain.com and the app password I provided.
# Send an email
send_email(
to_email="recipient@example.com",
subject="Important Update",
body="This is the email content...",
from_email="your-email@gmail.com",
password="your-app-password"
)
🌤️ 天气信息 🔄 即将推出
# Get weather forecast
get_forecast(latitude=40.7128, longitude=-74.0060)
# Get weather alerts
get_alerts(state="NY")
📰 新闻标题 🔄 即将推出
# Get general news
get_news_headlines(category="general", country="us")
# Get technology news
get_news_headlines(category="technology", country="us")
⏰ 提醒系统 🔄 即将推出
# Set a reminder
set_reminder(
date="2024-01-15 14:30",
message="Team meeting at 2:30 PM"
)
服务管理
# View logs
docker compose logs -f
# Restart services
docker compose restart
# Stop all services
docker compose down
# Rebuild and start
docker compose up --build -d
📁 项目结构
personal_assistant/
├── 📄 assistant.py # Main FastMCP assistant
├── 📄 notes_tool.py # Note management tools
├── 📄 email_tool.py # Email automation
├── 📄 compose.yaml # Docker Compose configuration
├── 📄 requirements.txt # Python dependencies
├── 📄 Dockerfile # Container configuration
├── 📁 src/ # Django application
│ ├── 📁 NoteApp/ # Django project settings
│ ├── 📁 notes/ # Notes app
│ └── 📄 manage.py # Django management
├── 📁 utils/ # Utility modules
│ └── 📄 get_connection.py # Database connection with retry
└── 📄 README.md # This file
🔌 API集成
FastMCP协议
该助手使用模型上下文协议（MCP）与Claude和其他兼容MCP的客户端无缝集成AI：
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("personal_assistant")
# Register active tools
mcp.tool()(send_email)
mcp.tool()(add_note)
mcp.tool()(list_notes)
mcp.tool()(start_notes_app)
# Future tools (commented out for now)
# mcp.tool()(set_reminder)
# mcp.tool()(get_forecast)
# mcp.tool()(get_alerts)
# mcp.tool()(get_news_headlines)
外部API
- Gmail SMTP ✅: 电子邮件发送功能 （当前活动）
- 国家气象局 🔄: 免费天气数据和警报 （即将推出）
- 新闻API 🔄: 新闻标题和文章 （即将推出）
🐳 Docker配置
服务
- 网络：Django应用程序（端口8001）
- 数据库：PostgreSQL数据库（端口5432）
健康检查
healthcheck:
test: ["CMD-SHELL", "pg_isready -U noter -d notedb"]
interval: 5s
timeout: 5s
retries: 10
网络
- notenet：服务通信内部网络
🔒 安全与配置
环境变量
- 数据库凭据
- 用于外部服务的API密钥
- 调试设置
🚨 故障排除
常见问题
-
数据库连接失败
# Check if database is running docker compose ps # View database logs docker compose logs db -
端口已在使用中
# Check what's using the port (Windows) netstat -ano | findstr :8001 # Check what's using the port (Linux/macOS) sudo netstat -tuln | grep 8001 # Stop conflicting services docker compose down
📄 许可证
该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。
🙏 致谢
- FastMCP：用于模型上下文协议的实现
- 姜戈：用于web框架
- PostgreSQL：用于数据库系统
- 码头工人：用于集装箱化
📞 支持
由以下材料制成❤️ 用于智能任务管理和提高生产率。
