Skip to main content
Glama
niahZheng

MCP Agent with DashScope

by niahZheng

MCP Agent with DashScope

基于阿里百炼 DashScope 平台的 Model Context Protocol (MCP) Agent 样例工程。

Web 界面截图

功能特性

  • ✅ 完整的 MCP 协议实现

  • 已集成阿里百炼 DashScope 大模型(通过 ai_chat 工具调用)

  • ✅ 支持工具调用(Tools):AI 对话工具

  • ✅ 支持资源访问(Resources)

  • ✅ TypeScript 类型安全

  • ✅ 标准化的项目结构

Related MCP server: Alibaba Cloud FC MCP Server

系统要求

  • Node.js 18.0.0 或更高版本(需要内置 fetch API 支持)

快速开始

1. 安装依赖

npm install

2. 配置环境变量

项目已包含 .env 文件,API Key 已配置。如需修改,编辑 .env 文件:

DASHSCOPE_API_KEY=your-api-key-here

3. 构建项目

npm run build

4. 启动 Web 服务器(推荐)

用户通过 Web 界面(HTML 页面)访问,无需了解底层 stdio 通信:

npm run api

然后在浏览器中访问:http://localhost:3000

Web 界面截图

其他运行方式

直接运行 MCP 服务器(用于集成到 Claude Desktop 等 MCP 客户端):

npm start

或开发模式(自动重新编译):

npm run dev

注意: npm start 启动的是纯 MCP 服务器,通过 stdio 与 MCP 客户端通信。如果要在浏览器中使用,请使用 npm run api 启动 Web 服务器。

你将看到一个美观的 Web 界面,可以直接使用所有功能!

说明: 用户通过 Web 界面(HTML 页面)与系统交互,底层 MCP 服务器通过 stdio 通信是内部实现细节,用户无需关心。

项目结构

mcp-agent/
├── src/
│   ├── index.ts              # 主入口文件
│   ├── server.ts             # MCP 服务器实现
│   ├── dashscope-client.ts   # DashScope API 客户端
│   ├── api-server.ts         # Web API 服务器
│   ├── web-client.html       # Web 界面
│   ├── tools/                # 工具定义
│   │   └── ai-chat.ts        # AI 对话工具
│   └── resources/            # 资源定义
│       └── file-system.ts
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
├── test-mcp-client.js        # 测试客户端
└── README.md

MCP 协议

本项目实现了 Model Context Protocol 的核心功能:

  • Tools: 可调用的工具函数

  • Resources: 可访问的资源

  • Prompts: 提示词模板

调用流程

当用户通过 Web 界面使用 AI 对话功能时,完整的调用流程如下:

用户 → Web 界面 → HTTP API → MCP 协议(stdio)→ MCP 服务器 → ai_chat 工具 → DashScope API

详细说明

  1. 用户操作: 在 Web 界面输入消息,点击"发送消息"按钮

  2. Web 界面: 调用 callAIChat() 函数,发送 HTTP POST 请求到 /api/mcp/tools/call

  3. HTTP API: API 服务器接收请求,通过 stdio 发送 JSON-RPC 请求到 MCP 服务器

  4. MCP 协议: 使用 JSON-RPC 2.0 协议,通过标准输入输出(stdio)通信

  5. MCP 服务器: 解析请求,路由到 ai_chat 工具处理器

  6. ai_chat 工具: 执行工具函数,调用 DashScope 客户端

  7. DashScope API: 发送 HTTP 请求到阿里百炼 DashScope API,获取 AI 回复

  8. 结果返回: 按照相反路径返回结果,最终显示在 Web 界面上

使用示例

Web 界面使用(主要方式)

启动 Web 服务器后,在浏览器中访问 http://localhost:3000,即可使用 AI 对话功能。

其他使用方式

直接运行 MCP 服务器(用于集成到其他 MCP 客户端):

npm start

注意: 直接运行 npm start 会启动纯 MCP 服务器,通过 stdio 与 MCP 客户端通信。如果要通过 Web 界面使用,请使用 npm run api 启动 Web 服务器。

开发

添加新工具

src/tools/ 目录下创建新的工具文件,然后在 src/server.ts 中注册。

添加新资源

src/resources/ 目录下创建新的资源文件,然后在 src/server.ts 中注册。

许可证

MIT

Available Tools

1 tool
ai_chatC

使用阿里百炼 DashScope 大模型进行对话(支持多轮对话)

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYes用户消息内容
system_promptNo系统提示词(可选)
modelNo使用的模型(可选,默认 qwen-turbo)qwen-turbo
temperatureNo温度参数(0-1,可选,默认 0.7)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions multi-turn conversation support, which adds some context beyond basic functionality. However, it doesn't disclose important behavioral traits like rate limits, authentication requirements, error handling, response format, or whether this is a read-only or mutating operation. For a tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that communicates the core functionality. It's appropriately sized for a tool with 4 parameters and no annotations. While it could potentially be more front-loaded with critical information, there's no wasted verbiage or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there's no output schema and no annotations, the description should provide more complete context. It doesn't explain what the tool returns, error conditions, or important behavioral constraints. For a tool that interacts with an external AI service (which typically has rate limits, costs, and specific response formats), this description leaves significant gaps in understanding how to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions multi-turn conversations generally, but doesn't explain how this relates to specific parameters. The baseline score of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '使用阿里百炼 DashScope 大模型进行对话' (using Alibaba Bailian DashScope large model for conversation). It specifies the verb ('进行对话' - conduct conversation) and resource (DashScope model), and mentions support for multi-turn conversations. However, without sibling tools, it cannot demonstrate differentiation from alternatives, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, limitations, or typical use cases. The only contextual information is the mention of multi-turn conversation support, but this doesn't constitute usage guidance for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • First observedai_chat

TDQS

B3.1/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined as using DashScope for chat conversations, so an agent cannot misselect between non-existent alternatives.

Naming Consistency5/5

The single tool name 'ai_chat' follows a clear and consistent pattern (snake_case with descriptive verb_noun structure). Since there is only one tool, there is no inconsistency to evaluate, and the naming is appropriate and readable.

Tool Count2/5

The server has only one tool, which feels thin and limited for a general-purpose 'MCP Agent with DashScope'. A single chat tool lacks the breadth expected for an agent interface, such as tools for different model types, configurations, or related AI tasks, making it under-scoped for its apparent purpose.

Completeness2/5

The tool surface is severely incomplete for an AI agent domain. While 'ai_chat' covers basic conversation, there are obvious gaps: no tools for model selection, parameter tuning, batch processing, or other common AI operations. This limits agents to only chat interactions, missing core functionalities expected from such a server.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that enables agent applications like Cursor and Cline to integrate with Alibaba Cloud Function Compute, allowing them to deploy and manage serverless functions through natural language interactions.
    12
    13 npm
    9
    MIT
  • F
    license
    B
    quality
    D
    maintenance
    A demonstration TypeScript MCP server that showcases basic MCP concepts with simple tools (greeting, calculator), text resources, and prompt templates for learning the Model Context Protocol.
    2
    -