MCP Dart Server

// file: lib/src/note_repository.dart
/// Thrown when a note violates a business rule.
class NoteRejected implements Exception {
  NoteRejected(this.message);

  final String message;
}

/// Domain service; it knows nothing about MCP.
class NoteRepository {
  final Map<String, String> _notes = {};

  Iterable<String> get ids => _notes.keys;

  String? read(String id) => _notes[id];

  void save(String id, String text) {
    if (!RegExp(r'^[a-z0-9-]+$').hasMatch(id)) {
      throw NoteRejected('id must be lowercase letters, digits or hyphens.');
    }
    _notes[id] = text;
  }
}

// file: lib/mcp/tools/base_tool.dart
import 'package:mcp_dart/mcp_dart.dart';

abstract class BaseTool {
  String get name;
  String get description;
  ToolInputSchema get inputSchema;
  ToolOutputSchema? get outputSchema => null;
  ToolAnnotations? get annotations => null;

  Future<CallToolResult> execute(
    Map<String, dynamic> args,
    RequestHandlerExtra extra,
  );
}

extension ToolRegistration on McpServer {
  void registerBaseTool(BaseTool tool) {
    registerTool(
      tool.name,
      description: tool.description,
      inputSchema: tool.inputSchema,
      outputSchema: tool.outputSchema,
      annotations: tool.annotations,
      callback: tool.execute,
    );
  }
}

// file: lib/mcp/tools/add_note_tool.dart
import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/mcp/tools/base_tool.dart';
import 'package:my_server/src/note_repository.dart';

class AddNoteTool extends BaseTool {
  AddNoteTool(this._notes);

  final NoteRepository _notes;

  @override
  String get name => 'add_note';

  @override
  String get description => 'Store a note under an id.';

  @override
  ToolInputSchema get inputSchema => JsonSchema.object(
        properties: {
          'id': JsonSchema.string(description: 'Lowercase note id'),
          'text': JsonSchema.string(description: 'Note body'),
        },
        required: ['id', 'text'],
      );

  @override
  ToolAnnotations get annotations =>
      const ToolAnnotations(idempotentHint: true);

  @override
  Future<CallToolResult> execute(
    Map<String, dynamic> args,
    RequestHandlerExtra extra,
  ) async {
    final id = args['id'] as String;
    try {
      _notes.save(id, args['text'] as String);
    } on NoteRejected catch (error) {
      return CallToolResult(
        isError: true,
        content: [TextContent(text: error.message)],
      );
    }
    return CallToolResult(content: [TextContent(text: 'Saved $id.')]);
  }
}

// file: lib/mcp/tools/count_notes_tool.dart
import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/mcp/tools/base_tool.dart';
import 'package:my_server/src/note_repository.dart';

class CountNotesTool extends BaseTool {
  CountNotesTool(this._notes);

  final NoteRepository _notes;

  @override
  String get name => 'count_notes';

  @override
  String get description => 'Return how many notes are stored.';

  @override
  ToolInputSchema get inputSchema => JsonSchema.object(properties: {});

  @override
  ToolOutputSchema get outputSchema => JsonSchema.object(
        properties: {'count': JsonSchema.integer()},
        required: ['count'],
      );

  @override
  ToolAnnotations get annotations => const ToolAnnotations(readOnlyHint: true);

  @override
  Future<CallToolResult> execute(
    Map<String, dynamic> args,
    RequestHandlerExtra extra,
  ) async =>
      CallToolResult.fromStructuredContent({'count': _notes.ids.length});
}

// file: lib/mcp/resources/note_resources.dart
import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/src/note_repository.dart';

void registerNoteResources(McpServer server, NoteRepository notes) {
  server.registerResource(
    'Note index',
    'notes://index',
    (description: 'All note ids', mimeType: 'text/plain'),
    (uri, extra) => ReadResourceResult(
      contents: [
        TextResourceContents(
          uri: uri.toString(),
          mimeType: 'text/plain',
          text: notes.ids.join('\n'),
        ),
      ],
    ),
  );

  server.registerResourceTemplate(
    'Note',
    ResourceTemplateRegistration('notes://{id}', listCallback: null),
    (description: 'One note by id', mimeType: 'text/plain'),
    (uri, variables, extra) {
      final id = variables['id'];
      final text = id is String ? notes.read(id) : null;
      if (text == null) {
        final version = extra.protocolVersion;
        throw McpError(
          version != null && isStatelessProtocolVersion(version)
              ? ErrorCode.invalidParams.value
              : ErrorCode.resourceNotFound.value,
          'Resource not found',
          {'uri': uri.toString()},
        );
      }
      return ReadResourceResult(
        contents: [
          TextResourceContents(
            uri: uri.toString(),
            mimeType: 'text/plain',
            text: text,
          ),
        ],
      );
    },
  );
}

// file: lib/mcp/prompts/note_prompts.dart
import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/src/note_repository.dart';

void registerNotePrompts(McpServer server, NoteRepository notes) {
  server.registerPrompt(
    'summarize_note',
    description: 'Ask the model to summarize a note.',
    argsSchema: const {
      'id': PromptArgumentDefinition(description: 'Note id', required: true),
    },
    callback: (args, extra) {
      final id = args?['id'] as String? ?? '';
      return GetPromptResult(
        messages: [
          PromptMessage(
            role: PromptMessageRole.user,
            content: TextContent(
              text: 'Summarize this note:\n${notes.read(id) ?? '(missing)'}',
            ),
          ),
        ],
      );
    },
  );
}

// file: lib/mcp/mcp.dart
import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/mcp/prompts/note_prompts.dart';
import 'package:my_server/mcp/resources/note_resources.dart';
import 'package:my_server/mcp/tools/add_note_tool.dart';
import 'package:my_server/mcp/tools/base_tool.dart';
import 'package:my_server/mcp/tools/count_notes_tool.dart';
import 'package:my_server/src/note_repository.dart';

List<BaseTool> createAllTools(NoteRepository notes) => [
      AddNoteTool(notes),
      CountNotesTool(notes),
    ];

McpServer createMcpServer(NoteRepository notes) {
  final server = McpServer(
    const Implementation(name: 'my_server', version: '1.0.0'),
    options: const McpServerOptions(
      instructions: 'Stores short notes. Use add_note, then read notes://.',
    ),
  );
  for (final tool in createAllTools(notes)) {
    server.registerBaseTool(tool);
  }
  registerNoteResources(server, notes);
  registerNotePrompts(server, notes);
  return server;
}

// file: bin/server.dart
import 'dart:io';

import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/mcp/mcp.dart';
import 'package:my_server/src/note_repository.dart';

Future<void> main(List<String> args) async {
  final notes = NoteRepository();

  if (!args.contains('--http')) {
    await createMcpServer(notes).connect(StdioServerTransport());
    stderr.writeln('my_server ready on stdio');
    return;
  }

  final server = StreamableMcpServer(
    serverFactory: (sessionId) => createMcpServer(notes),
    host: '127.0.0.1',
    port: 3000,
  );
  await server.start();
  stderr.writeln('my_server listening on http://127.0.0.1:3000/mcp');
  await ProcessSignal.sigint.watch().first;
  await server.stop();
}

// file: test/add_note_tool_test.dart
import 'dart:async';

import 'package:mcp_dart/mcp_dart.dart';
import 'package:my_server/mcp/mcp.dart';
import 'package:my_server/src/note_repository.dart';
import 'package:test/test.dart';

void main() {
  late NoteRepository notes;
  late McpServer server;
  late McpClient client;
  late List<StreamController<List<int>>> pipes;

  setUp(() async {
    notes = NoteRepository();
    server = createMcpServer(notes);
    final toServer = StreamController<List<int>>();
    final toClient = StreamController<List<int>>();
    pipes = [toServer, toClient];
    await server.connect(
      IOStreamTransport(stream: toServer.stream, sink: toClient.sink),
    );
    client = McpClient(const Implementation(name: 'test', version: '1.0.0'));
    await client.connect(
      IOStreamTransport(stream: toClient.stream, sink: toServer.sink),
    );
  });

  tearDown(() async {
    await client.close();
    await server.close();
    for (final pipe in pipes) {
      await pipe.close();
    }
  });

  test('add_note stores the note', () async {
    final result = await client.callTool(
      const CallToolRequest(
        name: 'add_note',
        arguments: {'id': 'todo', 'text': 'Ship it'},
      ),
    );
    expect(result.isError, isFalse);
    expect(notes.read('todo'), 'Ship it');
  });

  test('add_note returns rejected input as a tool error', () async {
    final result = await client.callTool(
      const CallToolRequest(
        name: 'add_note',
        arguments: {'id': 'Bad Id', 'text': 'x'},
      ),
    );
    expect(result.isError, isTrue);
    expect(notes.ids, isEmpty);
  });
}

import 'package:mcp_dart/mcp_dart.dart';

Future<CallToolResult> exportRows(
  Map<String, dynamic> args,
  RequestHandlerExtra extra,
) async {
  final rows = args['rows'] as int;
  for (var done = 0; done < rows; done += 100) {
    if (extra.signal.aborted) {
      return const CallToolResult(
        isError: true,
        content: [TextContent(text: 'Export cancelled.')],
      );
    }
    await Future<void>.delayed(const Duration(milliseconds: 10));
    await extra.sendProgress(
      done.toDouble(),
      total: rows.toDouble(),
      message: 'Exported $done of $rows rows',
    );
  }
  return CallToolResult(content: [TextContent(text: 'Exported $rows rows.')]);
}