evotraders/modelstudio_demos/mcp_server_with_chat/README_en.md

FastMCP Server Development Template

MCP Server development template based on FastMCP framework, quickly develop and deploy to Alibaba Cloud Bailian high-code platform

🎉 Features

Core features of this project:

• 🔧 Modular Architecture: MCP Server code separated into mcp_server.py, main program main.py handles routing integration
• 💬 Chat API Integration: New /process endpoint supporting Alibaba Cloud Bailian LLM calls and streaming responses
• 🤖 Intelligent Tool Calling: LLM can automatically identify and call MCP tools (Function Calling)
• 📡 Unified Service Architecture: FastAPI + FastMCP integration, one service providing both MCP and Chat functionality
• 🔄 Standardized Responses: Structured streaming responses based on AgentScope ResponseBuilder
• 🌐 CORS Support: Cross-origin requests supported for frontend integration
• 🎯 Route Optimization: MCP Server mounted at /mcp path, main app provides more endpoints

⚡ Quick Start Locally

1. Install Dependencies

pip install -r requirements.txt

2. Start Service

python -m deploy_starter.main

3. Verify Running

Health Check:

curl http://localhost:8080/health

Test Chat Endpoint:

curl -X POST http://localhost:8080/process \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "Hello"}]
      }
    ],
    "session_id": "test-session-001",
    "stream": true
  }'

4. Recommended: Use MCP Inspector to Verify MCP Server Locally

npx @modelcontextprotocol/inspector

Connect to: http://localhost:8080/mcp


---

🛠️ Develop Your First MCP Tool

Define tools in deploy_starter/mcp_server.py using the @mcp.tool() decorator:

Note

: After refactoring, all MCP tool definitions are in mcp_server.py, while main.py handles integration and routing

Example 1: Synchronous Tool (Simple call, average IO performance)

from typing import Annotated
from pydantic import Field

@mcp.tool(
    name="add Tool",
    description="A simple addition tool example"
)
def add_numbers(
    a: Annotated[int, Field(description="add a")],
    b: Annotated[int, Field(description="add b")]
) -> int:
    return a + b

Example 2: Asynchronous Tool (Async call, high IO performance)

@mcp.tool(
    name="Alibaba Cloud Bailian search",
    description="Search via Alibaba Cloud Bailian API"
)
async def search_by_modelStudio(
    query: Annotated[str, Field(description="Search query statement")],
    count: Annotated[int, Field(description="Number of search results returned")] = 5
) -> SearchLiteOutput:
    input_data = SearchLiteInput(query=query, count=count)
    search_component = ModelstudioSearchLite()
    result = await search_component.arun(input_data)
    return result

Note: Async tools require setting the environment variable DASHSCOPE_API_KEY to call Bailian services

export DASHSCOPE_API_KEY='sk-xxxxxx'

---

📝 Parameter Description Specification

Use Annotated + Field to add descriptions for each parameter:

from typing import Annotated, Optional
from pydantic import Field

@mcp.tool(
    name="your_tool_name",           # Tool name (what AI sees)
    description="Detailed tool description"      # Tool purpose description
)
def your_tool(
    param1: Annotated[str, Field(description="Description of parameter 1")],
    param2: Annotated[int, Field(description="Description of parameter 2")] = 10
) -> dict:
    # Your business logic
    return {"result": "success"}

---

Alibaba Cloud Bailian High-Code Cloud Deployment

Priority option: Upload code package directly through Alibaba Cloud Bailian high-code console

Create Application - High-Code Application

Command line console method for code upload and deployment - Better for quick code modifications and update deployments

1. Install Dependencies

pip install agentscope-runtime==1.0.0
pip install "agentscope-runtime[deployment]==1.0.0"

2. Set Environment Variables

export ALIBABA_CLOUD_ACCESS_KEY_ID=...            # Your Alibaba Cloud AccessKey (required)
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=...        # Your Alibaba Cloud SecurityKey (required)

# Optional: If you want to use separate OSS AK/SK, you can set the following (if not set, the above account AK/SK will be used), please ensure the account has OSS read/write permissions
export MODELSTUDIO_WORKSPACE_ID=...               # Your Bailian workspace ID
export OSS_ACCESS_KEY_ID=...
export OSS_ACCESS_KEY_SECRET=...
export OSS_REGION=cn-beijing

3. Package and Deploy

Method A: Manually Build Wheel File

Ensure your project can be built as a wheel file. You can use setup.py, setup.cfg, or pyproject.toml.

Build wheel file:

python setup.py bdist_wheel

Deploy:

runtime-fc-deploy \
  --deploy-name [Your application name] \
  --whl-path [Relative path to your wheel file e.g. "/dist/your_app.whl"]

For details, please refer to the Alibaba Cloud Bailian high-code deployment documentation: Alibaba Cloud Bailian High-Code Deployment Documentation

---

📋 Project Structure

.
├── deploy_starter/
│   ├── main.py          # Main program - FastAPI app entry, integrates Chat and MCP routing
│   ├── mcp_server.py    # MCP Server definition - Define your MCP tools here
│   └── config.yml       # Configuration file
├── requirements.txt     # Dependency list
├── setup.py            # Package configuration (for cloud deployment)
├── README_zh.md        # Chinese documentation
└── README_en.md        # English documentation

Core Files Description:

• main.py: FastAPI main app, provides /process endpoint and lifecycle management, mounts MCP Server at /mcp path
• mcp_server.py: FastMCP server instance, defines all MCP tools, provides tool list and call functions

---

🔧 Configuration

Edit deploy_starter/config.yml:

# MCP Server Configuration
MCP_SERVER_NAME: "my-mcp-server"
MCP_SERVER_VERSION: "1.0.0"

# Server Configuration
FC_START_HOST: "0.0.0.0"  # For cloud deployment
PORT: 8080
HOST: "127.0.0.1"  # For local development

# Alibaba Cloud Bailian API Key (optional, can also use environment variable)
# DASHSCOPE_API_KEY: "sk-xxx"
DASHSCOPE_MODEL_NAME: "qwen-plus"  # LLM model name

DashScope API Configuration

To use Chat and LLM features, you need to configure the Alibaba Cloud Bailian DashScope API KEY:

1. Set DASHSCOPE_API_KEY in deploy_starter/config.yml:

   DASHSCOPE_API_KEY: "sk-xxx"
   

2. Or set it as an environment variable:

   export DASHSCOPE_API_KEY="sk-xxx"
   

---

💡 Development Suggestions

Synchronous vs Asynchronous Tools

• Synchronous Tools: Suitable for simple calculations, local operations

  @mcp.tool()
  def sync_tool(param: str) -> str:
      return f"processed: {param}"
  

• Asynchronous Tools: Suitable for API calls, database queries, I/O operations

  @mcp.tool()
  async def async_tool(param: str) -> str:
      result = await some_api_call(param)
      return result
  

Tool Naming Conventions

• name: Tool name visible to AI (supports Chinese)
• description: Detailed explanation of tool purpose, helps AI understand when to call

---

🎯 Using in AI Clients

Claude Desktop

Edit the configuration file ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "deploy_starter.main"],
      "env": {}
    }
  }
}

Cursor / Cline

Connect to MCP Server URL:

http://localhost:8080/mcp

Bailian High-Code Agent Integration

If your application is deployed to Bailian high-code platform, you can directly use the /process endpoint for Agent conversations, supporting:

• Natural language interaction
• Automatic tool calling
• Streaming responses
• Complete conversation context management

---

📚 API Endpoints

Endpoint	Method	Description
/	GET	Server information
/health	GET	Health check (do not modify)
/process	POST	Chat endpoint, supports LLM conversation and tool calling (requires DASHSCOPE_API_KEY)
/mcp	GET/POST	MCP Server endpoint (Streamable HTTP transport)

Chat Endpoint Details

Request Format:

{
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "User message"}
      ]
    }
  ],
  "session_id": "Session ID",
  "stream": true
}

Response Format:

• Streaming response (SSE), complies with AgentScope ResponseBuilder standard
• Supports multiple message types: message (normal answer), reasoning (thinking process), plugin_call (tool call), plugin_call_output (tool output)

Core Features:

• ✅ Automatically identify and call MCP tools
• ✅ Support multi-turn conversation context
• ✅ Streaming response, real-time results
• ✅ Transparent tool calling process