MCP 服务器

MCP Server

app-appplayer

开发者工具

访问服务器

README

MCP 服务器

一个用于实现模型上下文协议 (MCP) 服务器的 Dart 插件。该插件允许 Flutter 应用程序以标准化方式向大型语言模型 (LLM) 应用程序公开数据、功能和交互模式。

特性

创建具有标准化协议支持的 MCP 服务器
通过 资源 (Resources) 公开数据
通过 工具 (Tools) 提供功能
通过 提示 (Prompts) 定义交互模式
多种传输层：
- 用于本地进程通信的标准 I/O
- 用于基于 HTTP 通信的服务器发送事件 (SSE)
跨平台支持：Android、iOS、Web、Linux、Windows、macOS

协议版本

此软件包实现了模型上下文协议 (MCP) 规范版本 2024-11-05 和 2025-03-26。

协议版本对于确保 MCP 客户端和服务器之间的兼容性至关重要。此软件包的每个版本可能支持不同的协议版本，因此请务必：

检查 CHANGELOG.md 以获取协议版本更新
确保客户端和服务器协议版本兼容
及时了解最新的 MCP 规范

入门指南

安装

将软件包添加到您的 pubspec.yaml：

dependencies:
  mcp_server: ^0.1.7

或者通过命令行安装：

dart pub add mcp_server

基本用法

import 'package:mcp_server/mcp_server.dart';

void main() {
  // 创建一个服务器
  final server = McpServer.createServer(
    name: 'Example Server',
    version: '1.0.0',
    capabilities: ServerCapabilities(
      tools: true,
      resources: true,
      prompts: true,
    ),
  );

  // 添加一个简单的计算器工具
  server.addTool(
    name: 'calculator',
    description: '执行基本计算',
    inputSchema: {
      'type': 'object',
      'properties': {
        'operation': {
          'type': 'string',
          'enum': ['add', 'subtract', 'multiply', 'divide'],
          'description': '要执行的数学运算'
        },
        'a': {
          'type': 'number',
          'description': '第一个操作数'
        },
        'b': {
          'type': 'number',
          'description': '第二个操作数'
        }
      },
      'required': ['operation', 'a', 'b']
    },
    handler: (arguments) async {
      final operation = arguments['operation'] as String;
      final a = (arguments['a'] is int) ? (arguments['a'] as int).toDouble() : arguments['a'] as double;
      final b = (arguments['b'] is int) ? (arguments['b'] as int).toDouble() : arguments['b'] as double;
      
      double result;
      switch (operation) {
        case 'add':
          result = a + b;
          break;
        case 'subtract':
          result = a - b;
          break;
        case 'multiply':
          result = a * b;
          break;
        case 'divide':
          if (b == 0) {
            return CallToolResult(
              [TextContent(text: '除以零错误')],
              isError: true,
            );
          }
          result = a / b;
          break;
        default:
          return CallToolResult(
            [TextContent(text: '未知操作: $operation')],
            isError: true,
          );
      }
      
      return CallToolResult([TextContent(text: '结果: $result')]);
    },
  );

  // 添加一个资源
  server.addResource(
    uri: 'time://current',
    name: '当前时间',
    description: '获取当前日期和时间',
    mimeType: 'text/plain',
    handler: (uri, params) async {
      final now = DateTime.now().toString();
      
      return ReadResourceResult(
        content: now,
        mimeType: 'text/plain',
        contents: [
          ResourceContent(
            uri: uri,
            text: now,
          ),
        ],
      );
    },
  );

  // 添加一个模板提示
  server.addPrompt(
    name: 'greeting',
    description: '生成自定义问候语',
    arguments: [
      PromptArgument(
        name: 'name',
        description: '要问候的名字',
        required: true,
      ),
      PromptArgument(
        name: 'formal',
        description: '是否使用正式的问候语风格',
        required: false,
      ),
    ],
    handler: (arguments) async {
      final name = arguments['name'] as String;
      final formal = arguments['formal'] as bool? ?? false;

      final String systemPrompt = formal
          ? '你是一个正式的助手。以尊重和正式的方式称呼用户。'
          : '你是一个友好的助手。语气要热情和随意。';

      final messages = [
        Message(
          role: MessageRole.system.toString().split('.').last,
          content: TextContent(text: systemPrompt),
        ),
        Message(
          role: MessageRole.user.toString().split('.').last,
          content: TextContent(text: '请问候 $name'),
        ),
      ];

      return GetPromptResult(
        description: '为 $name 提供的 ${formal ? '正式' : '随意'} 问候语',
        messages: messages,
      );
    },
  );

  // 连接到传输
  final transport = McpServer.createStdioTransport();
  server.connect(transport);
}

核心概念

服务器

Server 类是您与 MCP 协议的核心接口。它处理连接管理、协议合规性和消息路由：

final server = McpServer.createServer(
  name: 'My App',
  version: '1.0.0',
  capabilities: ServerCapabilities(
    tools: true,
    resources: true,
    prompts: true,
  ),
);

资源

资源是您向 LLM 公开数据的方式。它们类似于 REST API 中的 GET 端点 - 它们提供数据，但不应执行重要的计算或产生副作用：

// 静态资源
server.addResource(
  uri: 'config://app',
  name: '应用配置',
  description: '应用程序配置数据',
  mimeType: 'text/plain',
  handler: (uri, params) async {
    final configData = "app_name=MyApp\nversion=1.0.0\ndebug=false";
    
    return ReadResourceResult(
      content: configData,
      mimeType: 'text/plain',
      contents: [
        ResourceContent(
          uri: uri,
          text: configData,
        ),
      ],
    );
  },
);

// 带有 URI 模板的资源
server.addResource(
  uri: 'file://{path}',
  name: '文件资源',
  description: '访问系统上的文件',
  mimeType: 'application/octet-stream',
  uriTemplate: {
    'type': 'object',
    'properties': {
      'path': {
        'type': 'string',
        'description': '文件路径'
      }
    }
  },
  handler: (uri, params) async {
    // 提取路径并读取文件内容
    final path = params['path'] ?? uri.substring('file://'.length);
    final content = await File(path).readAsString();
    
    return ReadResourceResult(
      content: content,
      mimeType: 'text/plain',
      contents: [
        ResourceContent(
          uri: uri,
          text: content,
        ),
      ],
    );
  },
);

工具

工具允许 LLM 通过您的服务器执行操作。与资源不同，工具需要执行计算并产生副作用：

server.addTool(
  name: 'currentDateTime',
  description: '获取当前日期和时间',
  inputSchema: {
    'type': 'object',
    'properties': {
      'format': {
        'type': 'string',
        'description': '输出格式 (full, date, time)',
        'default': 'full'
      }
    },
    'required': []
  },
  handler: (args) async {
    final format = args['format'] as String? ?? 'full';
    final now = DateTime.now();
    
    String result;
    switch (format) {
      case 'date':
        result = '${now.year}-${now.month.toString().padLeft(2, '0')}-${now.day.toString().padLeft(2, '0')}';
        break;
      case 'time':
        result = '${now.hour.toString().padLeft(2, '0')}:${now.minute.toString().padLeft(2, '0')}:${now.second.toString().padLeft(2, '0')}';
        break;
      case 'full':
      default:
        result = now.toIso8601String();
        break;
    }
    
    return CallToolResult([TextContent(text: result)]);
  },
);

提示

提示是可重用的模板，可帮助 LLM 有效地与您的服务器交互：

server.addPrompt(
  name: 'codeReview',
  description: '为代码片段生成代码审查',
  arguments: [
    PromptArgument(
      name: 'code',
      description: '要审查的代码',
      required: true,
    ),
    PromptArgument(
      name: 'language',
      description: '代码的编程语言',
      required: true,
    ),
  ],
  handler: (args) async {
    final code = args['code'] as String;
    final language = args['language'] as String;

    final systemPrompt = '''
你是一位专业的代码审查员。按照以下准则审查提供的代码：
1. 识别潜在的错误或问题
2. 建议优化性能或可读性
3. 突出显示代码中使用的良好实践
4. 提供建设性的反馈以进行改进
在您的反馈中要具体，并在建议更改时提供代码示例。
''';

    final messages = [
      Message(
        role: MessageRole.system.toString().split('.').last,
        content: TextContent(text: systemPrompt),
      ),
      Message(
        role: MessageRole.user.toString().split('.').last,
        content: TextContent(text: '请审查这段 $language 代码:\n\n```$language\n$code\n```'),
      ),
    ];

    return GetPromptResult(
      description: '为 $language 代码提供的代码审查',
      messages: messages,
    );
  },
);

传输层

标准 I/O

对于命令行工具和直接集成：

final transport = McpServer.createStdioTransport();
await server.connect(transport);

服务器发送事件 (SSE)

对于基于 HTTP 的通信：

final transport = McpServer.createSseTransport(
  endpoint: '/sse',
  messagesEndpoint: '/messages',
  port: 8080,
);
await server.connect(transport);

日志记录

该软件包包含一个内置的日志记录实用程序：

/// 日志记录
final Logger _logger = Logger.getLogger('mcp_server.test');
_logger.setLevel(LogLevel.debug);

// 配置日志记录
_logger.configure(level: LogLevel.debug, includeTimestamp: true, useColor: true);

// 以不同的级别记录消息
_logger.debug('调试信息');
_logger.info('重要信息');
_logger.warning('警告消息');
_logger.error('错误消息');

MCP 原语

MCP 协议定义了服务器可以实现的三个核心原语：

原语	控制	描述	示例用途
提示	用户控制	由用户选择调用的交互式模板	斜杠命令、菜单选项
资源	应用控制	由客户端应用程序管理的上下文数据	文件内容、API 响应
工具	模型控制	公开给 LLM 以执行操作的函数	API 调用、数据更新

附加功能

资源缓存

服务器包含内置的资源缓存，以提高性能：

// 使用内置的缓存机制
final cached = server.getCachedResource(uri);
if (cached != null) {
  return cached.content;
}

// 缓存资源以供将来使用
server.cacheResource(uri, result, Duration(minutes: 10));

// 使缓存失效
server.invalidateCache(uri);

进度跟踪

对于长时间运行的操作，您可以向客户端报告进度：

server.addTool(
  name: 'longRunningOperation',
  description: '执行具有进度报告的长时间运行的操作',
  inputSchema: { /* ... */ },
  handler: (args) async {
    // 注册操作以进行进度跟踪
    final operationId = server.registerOperation(sessionId, 'longRunningOperation');
    
    // 随着操作的进行更新进度
    for (int i = 0; i < 10; i++) {
      // 检查操作是否已取消
      if (server.isOperationCancelled(operationId)) {
        return CallToolResult([TextContent(text: '操作已取消')], isError: true);
      }
      
      // 更新进度 (0.0 到 1.0)
      server.notifyProgress(operationId, i / 10, '正在处理步骤 $i，共 10 步...');
      
      // 执行工作...
      await Future.delayed(Duration(seconds: 1));
    }
    
    return CallToolResult([TextContent(text: '操作已成功完成')]);
  },
);

健康监控

服务器提供内置的健康指标：

// 获取服务器健康信息
final health = server.getHealth();
_logger.debug('服务器运行时间：${health.uptime.inSeconds} 秒');
_logger.debug('已连接的会话：${health.connectedSessions}');
_logger.debug('已注册的工具：${health.registeredTools}');

// 跟踪自定义指标
server.incrementMetric('api_calls');
final timer = server.startTimer('operation_duration');
// ... 执行操作
server.stopTimer('operation_duration');

示例

查看 example 目录以获取完整的示例应用程序。

资源

问题和反馈

请在我们的问题跟踪器中提交任何问题、错误或功能请求。

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。