MCP Workitem Server

Dependency Installation

This project recommends using uv for dependency management and running.

Install uv

bash
pip install uv # or refer to the official uv documentation

Install Dependencies

bash
uv pip install -r requirements.txt

Environment Variables and Configuration

• It is recommended to use a .env file or environment variables to inject sensitive information.
• Required:
  • organizationId: Alibaba Cloud Organization ID
  • x-yunxiao-token: Alibaba Cloud API Token

.env Auto-loading Explanation

• fastmcp and uv support auto-loading of the .env file located in the root directory of the project, without requiring additional code.
• When starting the service (e.g., uv run mcp run mcp_server.py), it will automatically read the variables from the .env file.
• You can also manually load with python-dotenv if you have special needs.

.env Example File

Create a .env file in the root directory of the project with the following content:

organizationId=your_org_id
x-yunxiao-token=your_token

• The .env file is used for local development and testing. Do not commit sensitive information to the code repository.

• It is recommended to add .env to your .gitignore file to prevent leaks:

  .gitignore

  .env

Docker Deployment and Environment Variable Injection

Build Image

bash
docker build -t yx-mcp .

Run Container (Recommended Method)

1. Mount .env File via --env-file

   • Prepare the .env file in the root directory of the project (with the same content as above)
   • Start the container:
     bash
     docker run --env-file .env -p 9000:9000 yx-mcp

2. Pass Environment Variables via -e

   • Directly pass sensitive information on the command line:
     bash
     docker run -e organizationId=your_org_id -e x-yunxiao-token=your_token -p 9000:9000 yx-mcp

3. Mount .env File via Volume

   • Mount the local .env file into the container:
     bash
     docker run -v $(pwd)/.env:/app/.env -p 9000:9000 yx-mcp

Security Tip: Do not COPY the .env file into the image to avoid leaking sensitive information. It is recommended to pass them using --env-file or -e.

Starting the Service

bash

Method One: Use environment variables directly

export organizationId=your_org_id
export x-yunxiao-token=your_token
uv run mcp run mcp_server.py

Method Two: Auto-load .env file (recommended)

uv run mcp run mcp_server.py

Tool Description

This service exposes the get_workitem_description tool via the MCP protocol, which takes a requirement ID (e.g., YEPPPP-154) as a parameter and returns a structured JSON containing:

• text: Plain text description
• images: List of image URLs
• html: Original HTML content

Example Response

json
{
"id": "YEPPPP-154",
"text": "需求描述文本...",
"images": ["https://...jpg"],
"html": "..."
}

Error Handling

• If an external API request fails, it returns { "error": "错误信息" }, allowing the agent to make a judgment based on this.

Agent Invocation Recommendations

• Automatically discover and invoke the get_workitem_description tool through the MCP protocol.
• Only need to pass the id parameter; no need to worry about org_id/token.

Development and Debugging

• It is recommended to use uv run fastmcp dev mcp_server.py for local development, supporting hot-reloading and interactive testing.
• Supports the standard MCP agent ecosystem.

References

• uv Official Documentation
• fastmcp Official Documentation
• MCP Protocol Introduction
• python-dotenv