From f8bf38052dbe75f1d9b511abd18a9459b538a6d7 Mon Sep 17 00:00:00 2001 From: Chrislearn Young Date: Tue, 5 Aug 2025 08:21:52 +0800 Subject: [PATCH] update example doc --- examples/mcp-host/README.md | 139 +++++++++++++++++++++++++-- examples/mcp-host/nodes/local.py | 6 +- examples/mcp-host/nodes/telepathy.py | 2 +- 3 files changed, 137 insertions(+), 10 deletions(-) diff --git a/examples/mcp-host/README.md b/examples/mcp-host/README.md index d7825770..8145e9d5 100644 --- a/examples/mcp-host/README.md +++ b/examples/mcp-host/README.md @@ -1,18 +1,145 @@ -# Dora Openai MCP Host Example +# Dora MCP Host Example -This is a quick example to showcase how use the `dora-openai-server` to receive and send back data. +This is a comprehensive example demonstrating how to use the Dora Model Context Protocol (MCP) Host to create a multi-node dataflow system that integrates with various AI providers and local services. -Dora Openai Server is still experimental and may change in the future. +## Overview -Make sure to have, dora, uv and cargo installed. +This example showcases a complete MCP (Model Context Protocol) implementation using Dora's dataflow architecture. It includes: +- **MCP Host**: A server that exposes OpenAI-compatible API endpoints +- **MCP Server**: A backend service that handles tool calls and routing +- **Local Services**: Python nodes that provide specific functionalities +- **Multi-provider Support**: Integration with various AI providers (Moonshot, Gemini, etc.) + +## Architecture + +The system consists of the following components: + +### Core Components + +1. **dora-mcp-host** (`dora-mcp-host`) + - Acts as an OpenAI-compatible API server + - Listens on `0.0.0.0:8118` with `/v1` endpoint + - Routes requests to appropriate providers and tools + - Handles chat completions, model listings, and tool calls + +2. **mcp-server** (`mcp-server`) + - Central routing hub for MCP tool calls + - Manages communication between host and local services + - Configured via `mcp_server.toml` + +3. **Local Service Nodes**: + - **local.py**: Provides local information services + - **telepathy.py**: Demonstrates "telepathic" capabilities + +4. **dora-echo** (`dora-echo`) + - Echo service for testing and debugging + +### Configuration Files + +#### mcp_host.toml +Configures the MCP host with: +- **Listen Address**: `0.0.0.0:8118` +- **API Endpoint**: `v1` +- **Providers**: + - Moonshot (Kimi) API integration + - Gemini API integration + - Local Dora provider +- **Models**: + - `kimi-latest` (Moonshot) + - `gemini-2.0-flash` (Gemini) +- **MCP Servers**: + - Amap Maps server (external) + - Local streamable server + +#### mcp_server.toml +Defines available tools: +- **signature_dish**: Returns signature dishes from restaurants +- **happiest_kindergarten**: Provides kindergarten information +- **telepathy**: Demonstrates user preference detection + + +### Data Flow + +The system follows this data flow: +1. Client sends request to MCP Host (`127.0.0.1:8118/v1`) +2. MCP Host processes the request and determines routing +3. For tool calls, requests are sent to MCP Server +4. MCP Server routes to appropriate local services (local.py or telepathy.py) +5. Local services process and return responses +6. Responses flow back through the chain to the client + +## Prerequisites + +Make sure you have the following installed: +- **dora**: Dora framework +- **uv**: Python package manager +- **cargo**: Rust package manager +- **Python 3.11+**: For Python nodes + +## Setup and Running + +### 1. Environment Setup ```bash +# Create and activate Python virtual environment uv venv -p 3.11 --seed +source .venv/bin/activate # On Linux/macOS +# or .venv\Scripts\activate # On Windows + +# Install Python dependencies uv pip install -e ../../apis/python/node --reinstall +``` + +### 2. Build the System +```bash +# Build all components dora build dataflow.yml --uv +``` + +### 3. Run the System +```bash +# Start the dataflow dora run dataflow.yml --uv +``` -# In a separate terminal +### 4. Test the System +In a separate terminal: +```bash +# Run the test client uv run test_client.py -dora stop ``` + +## API Endpoints + +### Available Endpoints +- `GET /v1/models` - List available models +- `POST /v1/chat/completions` - Chat completions with tool support + +### Tool Functions +- `signature_dish` - Get random signature dish +- `happiest_kindergarten` - Get kindergarten information +- `telepathy` - Get favorite star and movie + +## Provider Configuration + +### Moonshot (Kimi) +- Requires `MOONSHOT_API_KEY` environment variable +- Model: `kimi-latest` + +### Gemini +- Requires `GEMINI_API_KEY` environment variable +- Model: `gemini-2.0-flash` + +### Dora Local +- Uses local Dora dataflow for processing +- No external API key required + +## Troubleshooting + +### Common Issues +1. **Port Conflicts**: Ensure ports 8118 and 8228 are available +2. **Environment Variables**: Set required API keys for external providers +3. **Dependencies**: Ensure all Python and Rust dependencies are installed +4. **Virtual Environment**: Activate the correct Python environment + +This example demonstrates the power and flexibility of Dora's MCP integration for building sophisticated AI-powered applications with multiple providers and local processing capabilities. diff --git a/examples/mcp-host/nodes/local.py b/examples/mcp-host/nodes/local.py index 5fa0f02c..55ebc4ce 100644 --- a/examples/mcp-host/nodes/local.py +++ b/examples/mcp-host/nodes/local.py @@ -1,8 +1,8 @@ """ -This is just a simple demonstration of an MCP server. +This is just a simple demonstration of MCP server. -The example returns some local information about the user's request, such as the tallest building, -the happiest kindergarten, the best restaurant, etc. +The example returns some local information about the user's request, such as +the happiest kindergarten, each restaurant's signature dish, etc. """ import pyarrow as pa diff --git a/examples/mcp-host/nodes/telepathy.py b/examples/mcp-host/nodes/telepathy.py index 669cfdbe..8dece99d 100644 --- a/examples/mcp-host/nodes/telepathy.py +++ b/examples/mcp-host/nodes/telepathy.py @@ -1,5 +1,5 @@ """ -This is just a simple demonstration of an MCP server. +This is just a simple demonstration of MCP server. This MCP server has the ability of telepathy and can know who the current user's favorite star is and what their favorite movie is.