add modelstudio_demos package with 2 demos (#76)
This commit is contained in:
Attan
336
modelstudio_demos/mcp_server_with_chat/README_en.md
Normal file
336
modelstudio_demos/mcp_server_with_chat/README_en.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. Start Service
|
||||
|
||||
```bash
|
||||
python -m deploy_starter.main
|
||||
```
|
||||
|
||||
### 3. Verify Running
|
||||
|
||||
**Health Check:**
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
**Test Chat Endpoint:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```python
|
||||
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)
|
||||
|
||||
```python
|
||||
@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
|
||||
```bash
|
||||
export DASHSCOPE_API_KEY='sk-xxxxxx'
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 Parameter Description Specification
|
||||
|
||||
Use `Annotated` + `Field` to add descriptions for each parameter:
|
||||
|
||||
```python
|
||||
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](https://bailian.console.aliyun.com//app-center?tab=app#/app-center)
|
||||
|
||||
|
||||
|
||||
### Command line console method for code upload and deployment - Better for quick code modifications and update deployments
|
||||
#### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
pip install agentscope-runtime==1.0.0
|
||||
pip install "agentscope-runtime[deployment]==1.0.0"
|
||||
```
|
||||
|
||||
#### 2. Set Environment Variables
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
python setup.py bdist_wheel
|
||||
```
|
||||
|
||||
Deploy:
|
||||
```bash
|
||||
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](https://bailian.console.aliyun.com/?tab=api#/api/?type=app&url=2983030)
|
||||
|
||||
---
|
||||
|
||||
## 📋 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`:
|
||||
|
||||
```yaml
|
||||
# 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`:
|
||||
```yaml
|
||||
DASHSCOPE_API_KEY: "sk-xxx"
|
||||
```
|
||||
|
||||
2. Or set it as an environment variable:
|
||||
```bash
|
||||
export DASHSCOPE_API_KEY="sk-xxx"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Development Suggestions
|
||||
|
||||
### Synchronous vs Asynchronous Tools
|
||||
|
||||
- **Synchronous Tools**: Suitable for simple calculations, local operations
|
||||
```python
|
||||
@mcp.tool()
|
||||
def sync_tool(param: str) -> str:
|
||||
return f"processed: {param}"
|
||||
```
|
||||
|
||||
- **Asynchronous Tools**: Suitable for API calls, database queries, I/O operations
|
||||
```python
|
||||
@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):
|
||||
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user