Ado Instruction MCP Server

ADO指令MCP服务器

模块化##🖼️ 图像分析：使用Azure OpenAI处理带有依赖关系箭头的工作流图✅ 新MCP（模型上下文协议）服务器，使用Azure OpenAI进行高级图像分析，将会议记录、文本输入和图像转换为结构化的Azure DevOps工作项。

🆕 新增：Azure OpenAI图像处理

该服务器现在包括由Azure OpenAI的视觉模型提供支持的高级图像分析功能：

• 🖼️ 高级图像分析 -使用Azure OpenAI o4 mini模型进行智能图像理解
• 📊 工作流图识别 -从可视化图表中识别项目结构和依赖关系箭头
• � 依赖箭头分析 -解析箭头以确定Epic→ 任务父子关系
• 🏗️ 层次结构检测 -从可视化流中创建适当的工作项层次结构

*专为分析线框、带依赖箭头的工作流程图和项目文档图像而设计。*

📝 文本分析与处理

服务器专门分析文本内容以生成需求和工作项：

• 📋 需求提取 -从文本内容中识别任务和功能
• 🔗 相关性分析 -了解工作项之间的关系
• 📝 智能处理 -从非结构化文本中提取结构化信息
• ⚡ 快速文本分析 -针对会议笔记和需求文档进行了优化

*专为处理会议记录、需求文档和项目文本而设计。*

🛠️ 可用工具

project_name: str priority_override: str |ADO指令JSON |灵活的文本到ADO转换| | 格式_操作_说明_摘要 ⭐ | instructions_json: str |格式化摘要|格式化工作项以供用户查看| | search_files_for_processing 🔍 | search_pattern: str file_types: str search_locations: str |文件搜索结果|在PC上查找文本和图像文件| | validate_ado_structure | instructions_json: str |验证报告|验证JSON结构| | get_organization_context |无|组织详细信息|获取Omar Solutions上下文| | load_image_from_file 🆕 | image_path: str |Base64图像数据|加载并转换图像以进行处理|

✨ 特性

• 📝 文本处理：将会议记录和笔记转换为结构化的ADO工作项✅ 工作中
• 🖼️ 图像分析：使用Azure OpenAI处理线框和图表✅ 新
• 🔗 结构化输出：生成适当分层的Epic→ 任务关系✅ 工作中
• 🎯 智能优先级：根据内容分析自动分配优先级✅ 工作中
• 📋 全面验证：确保工作项结构正确✅ 工作中
• ⭐ 用户确认：在继续之前格式化摘要以供审查✅ 新
• 🔍 文件发现：在PC上自动查找文本和图像文件✅ 新

🚀 快速开始

1.设置依赖关系

# Clone or navigate to project directory
cd ado_instructions

# Activate virtual environment
.venv\Scripts\Activate.ps1

# Install dependencies (already configured in pyproject.toml)
uv sync

2.配置Azure OpenAI

创建或更新 .env 使用您的Azure OpenAI凭据创建文件：

# Azure OpenAI Configuration
AZURE_OPENAI_ENDPOINT=https://omaragent.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_API_VERSION=2024-12-01-preview
AZURE_OPENAI_DEPLOYMENT=o4-mini-imagebot
AZURE_OPENAI_MODEL=o4-mini

3.运行服务器

# Start MCP server on default port 2000
python server.py

# Different port
python server.py --port 8001

# Different transport
python server.py --transport stdio

4.从VS代码连接

添加到MCP设置中：

{
  "mcpServers": {
    "ado-instructions": {
      "command": "python",
      "args": ["c:/path/to/your/ado_instructions/server.py"],
      "cwd": "c:/path/to/your/ado_instructions"
    }
  }
}

📖 使用示例

1.基本文本处理工作流程

# Step 1: Process meeting transcript
result = process_meeting_transcript(
    transcript="Team discussed new user authentication system. Need login page, password reset, user registration, and admin dashboard. High priority for login and registration. Medium priority for password reset. Low priority for admin dashboard."
)

# Step 2: Format summary for user review
summary = format_ado_instructions_summary(result)
print(summary)

# Step 3: Present to user and ask for confirmation
# User reviews the formatted output and confirms/requests changes

# Step 4: Proceed with validated work items
validated_json = result  # If user approved

2.🆕 Azure OpenAI图像处理工作流

# Step 1: Load image from file
image_data = load_image_from_file(
    image_path="c:/path/to/wireframe.png"
)

# Step 2: Process image with Azure OpenAI
result = process_feature_image(
    image_base64=image_data,
    description="Wireframe showing user authentication flow with login, registration, and dashboard components"
)

# Step 3: Format summary for user review
summary = format_ado_instructions_summary(result)
print(summary)

# Step 4: Present to user and ask for confirmation
# User reviews the formatted output and confirms/requests changes

# Step 5: Proceed with validated work items
validated_json = result  # If user approved

3.灵活的文本输入工作流程

# Step 1: Convert any text to ADO work items
result = generate_ado_workitems_from_text(
    text_input="Build a mobile app with user profiles, messaging, and notifications",
    project_name="Mobile App Development",
    priority_override="High"
)

# Step 2: Format summary for user review
summary = format_ado_instructions_summary(result)
print(summary)

# Step 3: Present to user and ask for confirmation
# User reviews the formatted output and confirms/requests changes

# Step 4: Proceed with validated work items
validated_json = result  # If user approved

🔗 工作流图的依赖箭头分析

这 进程特征图像 该工具包括高级可视化分析，可以从图表中的箭头和连接中了解工作流依赖关系：

📊 视觉模式识别

• 箭头方向分析: Parent → Child 从箭头流中识别关系
• 层次结构检测：创建合适的Epic→ 基于视觉层次结构的任务关系
• 依赖链映射：按照箭头顺序理解流程

🎯 支持的工作流模式

📝 示例：工作流图处理

Input Image: [Database] → [Website] → [Frontend/Backend]

Expected Output:
- Epic: "Database Implementation" (parent)
  - Task: "Build Website" (child of Database)
  - Task: "Develop Frontend" (child of Website)  
  - Task: "Develop Backend" (child of Website)

⚠️ 重要:

在处理工作流程图时，系统应：

1. 确定Epic的根 从最左侧/最顶部元素开始
2. 跟随箭头 确定任务依赖关系
3. 创建层次结构 其中箭头表示父级→ 儿童关系
4. 避免创建多个单独的Epic 除非图表显示并行工作流

4.文件发现和处理工作流(🔍 新

# Step 1: Search for files on the PC
search_results = search_files_for_processing(
    search_pattern="wireframe",
    file_types="images,text",
    search_locations="desktop,documents"
)

# Step 2: Process found files
# User selects files from search results
# Load content and process with appropriate tool

🏗️ 项目结构

ado_instructions/
├── server.py                 # Main MCP server (FastMCP 2.11.2)
├── pyproject.toml           # Dependencies and project config
├── uv.lock                  # Dependency lock file
├── README.md                # This documentation
├── .env                     # Environment variables (Azure OpenAI config)
├── modules/
│   ├── __init__.py          # Module initialization
│   ├── models.py            # Data classes and enums
│   ├── config.py            # Environment and organization setup
│   ├── text_processor.py    # Text analysis and feature extraction
│   ├── image_processor.py   # 🆕 Azure OpenAI image analysis
│   ├── ado_generator.py     # ADO work item generation
│   ├── file_search.py       # File discovery functionality
│   ├── error_handling.py    # Comprehensive error management
│   └── common_utils.py      # Shared utilities
└── tests/
    ├── test_optimization.py # Performance tests
    ├── test_utils.py        # Utility tests
    ├── images/              # Test image files
    └── text/                # Test text files

📊 依赖项

核心依赖关系（共5个包）

• ✅ fastmcp：MCP框架（2.11.2）
• ✅ 优维康：ASGI服务器
• ✅ 快速：Web框架
• ✅ python dotenv：环境管理
• ✅ openai：用于图像处理的Azure OpenAI SDK🆕

模块状态

• ✅ 错误处理（回退处理）
• ✅ 公用工具（共享功能）
• ✅ 模型（数据类和枚举）
• ✅ 配置（环境设置）
• ✅ 文本处理（特征提取）
• ✅ 🆕 图像处理（Azure OpenAI集成）
• ✅ ADO生成（工作项创建）

📊 MCP工具参考

project_name: str priority_override: str |ADO指令JSON |灵活的文本到ADO转换| | 格式_操作_说明_摘要 ⭐ | instructions_json: str |格式化摘要| 新：设置工作项的格式以供用户查看| | validate_ado_structure | instructions_json: str |验证报告|验证JSON结构| | get_organization_context |无|组织详细信息|获取Omar Solutions上下文| | search_files_for_processing | search_pattern: str file_types: str search_locations: str |文件搜索结果|在PC上查找文本和图像文件| | load_image_from_file 🆕 | image_path: str |Base64图像数据|加载并转换图像以进行处理|

工具特定详细信息

process_meeting_transcript

• 目的：将会议记录/抄本转换为ADO工作项
• 输入：包含会议讨论的长文本
• 输出：带Epics和任务的结构化JSON
• 用例：将非结构化会议笔记转换为有组织的工作项

🆕 process_feature_image （新增-Azure OpenAI）

• 目的：使用Azure OpenAI的高级视觉功能分析图像
• 输入：Base64图像数据+可选描述
• 输出：带Epics和任务的结构化JSON
• 用例：从线框、图表和可视化项目文档中提取需求
• 技术：具有视觉功能的Azure OpenAI o4迷你模型

generate_ado_workitems_from_text

• 目的：灵活的文本到ADO转换
• 输入：任何文本描述+可选项目名称和优先级
• 输出：带Epics和任务的结构化JSON
• 用例：将需求文本快速转换为工作项

⭐ format_ado_instructions_summary 新

• 目的：格式化工作项以供用户审查和确认
• 输入：ADO指令JSON来自任何生成工具
• 输出：用户友好的格式化摘要，带有项目结构
• 用例：在继续之前，向用户展示工作项以供批准

🔍 search_files_for_processing 新

• 目的：在PC上查找文本和图像文件进行处理
• 输入：搜索模式、文件类型、位置
• 输出：已找到的包含路径和元数据的文件列表
• 用例：在不知道确切路径的情况下发现相关文件

🆕 load_image_from_file 新

• 目的：加载本地图像并将其转换为base64格式
• 输入：图像文件的绝对路径
• 输出：Base64编码图像数据
• 用例：为Azure OpenAI处理准备本地映像

🔧 模块详细信息

📊 modules/models.py

• 工作项：单个工作项的数据类
• AdoInstructions：完整项目结构的容器
• WorkItemType：枚举（史诗、任务、用户故事、Bug）
• 优先级：枚举（低、中、高、临界）
• 组织文本：Omar Solutions配置

⚙️ modules/config.py

• setup_environment（）：加载.env变量，包括Azure OpenAI配置
• get_organization_context（）：访问组织数据
• get_azure_openai_config（）: 🆕 Azure OpenAI配置管理

📝 modules/text_processor.py

• extract_features_from_text（）：从文本中提取项目特征
• extract_requirements_from_text（）：查找具体要求
• determined_priority_from_text（）：自动分配优先级

🖼️ modules/image_processor.py 🆕 新

• process_image_with_azure_openai（）：使用Azure OpenAI分析图像
• extract_features_from_image（）：从图像中提取项目特征
• 分析工作流图（）：专业图表分析
• 格式图像分析结果（）：将AI分析格式化为ADO结构

🏗️ modules/ado_generator.py

• create_epic_from_feature（）：生成Epic工作项
• create_task_from_requirement（）：生成任务工作项
• generate_ado_指令（）：完成指令生成
• format_ado_summary（）：设置工作项的格式以供用户查看

🔍 modules/file_search.py ⭐ 新

• search_files_for_processing（）：在PC上查找文本和图像文件
• format_search_results_for_display（）：用户友好的结果格式
• get_search_usage_examples（）：使用文档和示例

🛠️ 高级配置

Azure OpenAI设置

# .env file configuration
AZURE_OPENAI_ENDPOINT=https://omaragent.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_API_VERSION=2024-12-01-preview
AZURE_OPENAI_DEPLOYMENT=o4-mini-imagebot
AZURE_OPENAI_MODEL=o4-mini

服务器选项

# Custom port
python server.py --port 8001

# Different transport
python server.py --transport stdio

Azure OpenAI配置示例

from openai import AzureOpenAI

client = AzureOpenAI(
    api_version="2024-12-01-preview",
    azure_endpoint="https://omaragent.openai.azure.com/",
    api_key=subscription_key
)

# Example image analysis call
response = client.chat.completions.create(
    messages=[
        {
            "role": "system",
            "content": "You are an expert at analyzing project diagrams and wireframes to extract requirements.",
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Analyze this wireframe and extract the project requirements"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_base64}"
                    }
                }
            ]
        }
    ],
    max_completion_tokens=40000,
    model="o4-mini-imagebot"
)

🧪 测试依赖性箭头分析

✅ 测试用例1：线性工作流

Input Diagram: [Database] → [Website] → [Frontend]
Expected Output:
- Epic: "Database Implementation" 
- Task: "Build Website" (depends on Database)
- Task: "Develop Frontend" (depends on Website)

✅ 测试用例2：并行依赖关系

Input Diagram: [API] → [Frontend]
                    ↘ [Backend]
Expected Output:
- Epic: "API Implementation"
- Task: "Develop Frontend" (depends on API)
- Task: "Develop Backend" (depends on API)

✅ 测试用例3：复杂工作流

Input Diagram: [Database] → [API Layer] → [Authentication] → [User Interface]
Expected Output:
- Epic: "Database Implementation"
- Task: "Build API Layer" (depends on Database)
- Task: "Implement Authentication" (depends on API)
- Task: "Create User Interface" (depends on Authentication)

🔍 测试您的工作流程图

1. 创建测试图像 用清晰的箭头显示依赖关系
2. 使用描述性上下文：包括解释工作流程的说明
3. 验证层次结构：检查ONE Epic的创建是否具有适当的任务依赖关系
4. 审查依赖链：确保任务引用其依赖关系

# Test workflow diagram processing
result = process_feature_image(
    image_base64=your_workflow_diagram,
    description="Website development workflow: Database → Website → Frontend/Backend dependencies"
)

# Should generate:
# - 1 Main Epic (not multiple Epics)
# - Tasks with dependency context
# - Proper workflow sequence preserved

❌ 需要避免的常见问题

• 多史诗：应从工作流根创建ONE Epic
• 缺少的依赖：任务应参考它们所依赖的内容
• 错误的层次结构：按箭头指示家长→ 儿童关系
• 丢失序列：保留箭头所示的工作流顺序

)

### Dependency Management
The server gracefully handles missing dependencies:
- **Azure OpenAI**: Falls back to text-only processing if API key unavailable
- **Image Processing**: Uses fallback methods if Azure OpenAI is unavailable
- **All modules**: Comprehensive error handling with fallbacks

## 🔍 Troubleshooting

| Issue | Solution |
|-------|----------|
| **ModuleNotFoundError** | Activate virtual environment: `.venv\Scripts\Activate.ps1` |
| **Azure OpenAI API errors** | Check API key and endpoint configuration in .env |
| **Image processing failures** | Verify Azure OpenAI deployment and model availability |
| **Port already in use** | Change port: `python server.py --port 8001` |
| **Import errors** | Check module structure and relative imports |
| **Text processing errors** | Verify input format and content |

## 🚀 Production Deployment

### Azure Container Apps Deployment

The server is designed to run in Azure Container Apps with proper containerization and dependency management.

#### 🔧 **Key Deployment Configurations**

Dockerfile - Fixed configuration for Azure Container Apps

FROM python:3.11-slim

ENV PYTHONUNBUFFERED=1 ENV PYTHONDONTWRITEBYTECODE=1 ENV CONTAINER_ENV=true

WORKDIR /app

Use uv for fast dependency management

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/ COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-cache

COPY . .

Critical: Use 0.0.0.0 for container networking

CMD ["uv", "run", "python", "server.py", "--port", "3000", "--host", "0.0.0.0"]

#### 🛠️ **Azure容器应用程序的环境变量**

Required Azure OpenAI Configuration

AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/ AZURE_OPENAI_API_KEY=your-api-key AZURE_OPENAI_API_VERSION=2024-12-01-preview AZURE_OPENAI_DEPLOYMENT=o4-mini-imagebot AZURE_OPENAI_MODEL=o4-mini

Container Environment Detection

CONTAINER_ENV=true

#### 📋 **部署步骤**

1. **构建和标记图像**

docker build -t your-registry.azurecr.io/ado-instructions-server:v1.2.0 .

1. **推送到Azure容器注册表**

az acr login --name your-registry docker push your-registry.azurecr.io/ado-instructions-server:v1.2.0

1. **更新容器应用程序**

az containerapp update \ --name ado-instructions-server \ --resource-group YourResourceGroup \ --image your-registry.azurecr.io/ado-instructions-server:v1.2.0

#### ⚠️ **已解决常见部署问题**

|问题|根本原因|解决方案|
|-------|------------|----------|
| **503服务不可用** |服务器绑定到 `localhost` 而不是 `0.0.0.0` |使用 `--host 0.0.0.0` 在CMD|
| **模块故障：openai** |容器中未加载依赖项|使用 `uv run python server.py` |
| **端口不匹配** |默认端口2000与容器端口3000 |显式设置 `--port 3000` |
| **环境检测** |本地.env与Azure环境变量| config.py中的智能环境检测|

#### ✅ **部署验证**

部署后，验证服务器是否正在运行：

Check container app status

az containerapp show --name ado-instructions-server --resource-group YourResourceGroup --query "properties.runningStatus"

Check logs for successful startup

az containerapp logs show --name ado-instructions-server --resource-group YourResourceGroup --tail 20

Expected log output:

✅ Azure OpenAI configured - Image processing available

INFO: Uvicorn running on http://0.0.0.0:3000

#### 🧩 **部署挑战已解决**

**挑战1：容器中的网络绑定**

- **问题**：服务器默认为 `localhost`，阻止Azure容器应用程序中的外部连接
- **根本原因**：容器网络需要绑定到 `0.0.0.0` 接受来自容器编排器的流量
- **解决方案**：已更改默认主机 `"localhost"` 向 `"0.0.0.0"` 在server.py参数解析中
- **影响**：修复了503服务不可用错误

**挑战2：容器中的依赖加载**

- **问题**: `ModuleNotFoundError: No module named 'openai'` 跑步时 `python server.py` 直接
- **根本原因**：容器环境需要适当的依赖隔离和加载
- **解决方案**：使用 `uv run python server.py` 而不是直接 `python server.py` 执行
- **影响**：确保容器运行时中的所有依赖项都可用

**挑战3：端口配置一致性**

- **问题**：Dockerfile使用端口3000，但服务器默认端口为2000
- **根本原因**：容器和服务器默认值之间的端口配置不匹配
- **解决方案**：明确指定 `--port 3000` 在Dockerfile CMD指令中
- **影响**：所有部署方法的端口使用一致

**挑战4：环境变量检测**

- **问题**：服务器试图在容器环境中加载.env文件
- **根本原因**：没有环境检测逻辑来区分本地部署和云部署
- **解决方案**：使用Azure特定的环境变量在config.py中添加了智能环境检测
- **影响**：本地开发和Azure部署的正确配置加载

#### 🔄 **部署前与部署后修复**

|方面|之前（失败）|之后（工作）|
|--------|------------------|-----------------|
| **主机绑定** | `localhost` （容器内部）| `0.0.0.0` （接受外部流量）|
| **依赖关系加载** | `python server.py` （缺少模块）| `uv run python server.py` （孤立环境）|
| **端口配置** |混合（默认2000，暴露3000）|一致 `3000` 自始至终|
| **环境检测** |始终尝试.env文件|智能检测：本地为.env，Azure为env变量|
| **容器状态** |503服务不可用|✅ 运行成功|

#### 🔗 **MCP配置**

更新本地MCP配置以使用部署的服务器：

{ "servers": { "ado-instruction-server": { "url": "https://your-app.azurecontainerapps.io/mcp/", "type": "http" } } }

### 地方发展与生产

|环境|主机|端口|依赖关系|环境变量|
|-------------|------|------|--------------|----------------------|
| **本地** | `localhost` 或 `0.0.0.0` | `2000` （默认）| `uv run` 推荐| `.env` 文件|
| **Azure容器应用** | `0.0.0.0` （必填）| `3000` | `uv run` （必需）|Azure容器应用程序设置|

## 🎯 最佳实践

### ⭐ 新增：文件发现工作流

- ✅ **先使用搜索工具**：在不知道确切路径的情况下查找文件
- ✅ **按类型筛选**：搜索“图像”、“文本”或“所有”文件类型
- ✅ **多个地点**：同时搜索桌面、文档和下载
- ✅ **模式匹配**：使用通配符或关键字查找特定文件
- ✅ **检查文件大小**：避免处理非常大的文件

### ⭐ 新增：用户确认工作流程

- ✅ **始终格式化并呈现** 生成后的工作项
- ✅ **询问用户确认**“这些指示正确吗？”
- ✅ **提供修改** 如果用户想要更改
- ✅ **记录任何更改** 用户请求
- ✅ **验证最终输出** 在继续之前

### 对于文本输入：

- ✅ 使用面向行动的语言（“构建”、“创建”、“实施”）
- ✅ 提及特定技术或功能
- ✅ 包括要求和验收标准
- ✅ 使用各种输入长度进行测试

### 🆕 对于图像输入：

- ✅ 使用清晰的线框或图表
- ✅ 在描述字段中提供描述性上下文
- ✅ 支持的格式：PNG、JPG、GIF、BMP、WebP
- ✅ 将图像保持在10MB以下，以实现最佳处理
- ✅ 确保图表中的文本具有良好的对比度和可读性
- ✅ 包括工作流箭头和清晰的组件关系

### 发展：

- ✅ 遵循模块化架构原则
- ✅ 添加全面的错误处理
- ✅ 包括类型提示和文档字符串
- ✅ 独立测试模块

## 🚀 后续步骤

1. **增强的Azure OpenAI集成**：提高图像分析的准确性和速度
1. **高级视觉分析**：线框中更好的UI组件检测
1. **多模态处理**：结合文本和图像输入，进行更丰富的分析
1. **ADO集成**：用于创建工作项的直接API集成
1. **AI增强**：LLM供电需求分析
1. **web界面**：可选的web UI，便于测试

## 🏆 已成功测试功能

- ✅ **文本处理**：处理复杂的项目描述
- ✅ **模块化架构**：所有模块独立工作（6个模块）
- ✅ **服务器启动**：使用8个工具在配置的端口（2000）上运行
- ✅ **错误处理**：缺少依赖项的优雅回退
- ✅ **MCP集成**：与VS Code MCP框架兼容
- ✅ **ADO生成**：生成有效的工作项结构
- ✅ ⭐ **新**: **格式化摘要**：用户友好的工作项演示
- ✅ ⭐ **新**: **用户确认工作流**：继续之前先询问
- ✅ ⭐ **新**: **优先级显示**：清晰的“高/中/低”标签
- ✅ 🔍 **新**: **文件搜索**：在PC上自动查找图像和文本文件
- ✅ 🏗️ **新**: **干净的服务器架构**：模块化文件搜索功能
- ✅ 🆕 **新**: **Azure OpenAI集成**：使用o4-mini进行高级图像分析

## 📋 当前工具计数： **8种MCP工具可用**

1. `process_meeting_transcript` -将会议笔记转换为ADO工作项
1. 🆕 `process_feature_image` - **新**：使用Azure OpenAI分析图像
1. `generate_ado_workitems_from_text` -灵活的文本到ADO转换
1. ⭐ `format_ado_instructions_summary` - **新**：设置工作项的格式以供用户查看
1. 🔍 `search_files_for_processing` - **新**：在PC上查找图像/文本文件
1. `validate_ado_structure` -验证JSON结构的正确性
1. `get_organization_context` -获取Omar Solutions上下文信息
1. 🆕 `load_image_from_file` - **新**：加载和转换图像以进行处理

______________________________________________________________________

**已准备好使用Azure OpenAI进行高级图像处理！** 🎉 🖼️ ✨