Dart MCP Server

Instructions

Implementation Reference

• src/index.ts:1017-1104 (handler)

  Handler for the create_space tool. Generates and executes embedded Python code using the Dart SDK to create a SpaceCreate operation and transact it.

                      case 'create_space': {
                          console.error('[Debug] Handling create_space request');
                          const pythonCode = `
  import sys
  import json
  from dart import Dart, Operation, OperationKind, OperationModelKind, SpaceCreate, TransactionKind
  from dart.dart import _Session, UserBundle, _make_duid
  from dart.generated.models.icon_kind import IconKind
  
  print("[Debug] Starting Python execution", file=sys.stderr)
  
  # Parse arguments from JSON
  args_json = '''${JSON.stringify(args)}'''
  args = json.loads(args_json)
  print(f"[Debug] Parsed args: {args}", file=sys.stderr)
  
  # Initialize session and client
  session = _Session()
  print("[Debug] Session created", file=sys.stderr)
  bundle = UserBundle(session)
  print("[Debug] UserBundle created", file=sys.stderr)
  client = Dart()
  print("[Debug] Dart client created", file=sys.stderr)
  
  # Get the user's DUID
  user_duid = bundle.user["duid"]
  print(f"[Debug] User DUID: {user_duid}", file=sys.stderr)
  
  # Generate a unique DUID for the space
  space_duid = _make_duid()
  print(f"[Debug] Generated space DUID: {space_duid}", file=sys.stderr)
  
  # Create the space object with required fields
  space = SpaceCreate(
      duid=space_duid,
      order="0",
      title=args.get("title"),
      description=args.get("description", ""),
      drafter_duid=user_duid,  # Set drafter_duid explicitly
      accessible_by_team=args.get("accessible_by_team", True),
      accessible_by_user_duids=args.get("accessible_by_user_duids", []),
      icon_kind=IconKind(args.get("icon_kind", "None")),
      icon_name_or_emoji=args.get("icon_name_or_emoji", "")
  )
  print(f"[Debug] Created space object: {space}", file=sys.stderr)
  
  # Create the operation
  space_op = Operation(
      model=OperationModelKind.SPACE,
      kind=OperationKind.CREATE,
      data=space  # Pass the SpaceCreate object
  )
  
  print(f"[Debug] Created operation: {space_op}", file=sys.stderr)
  
  # Execute the transaction
  result = client.transact([space_op], TransactionKind.SPACE_CREATE)
  print(f"[Debug] Transaction completed", file=sys.stderr)
  
  if result.results and result.results[0].success:
      space = result.results[0].models.spaces[0]
      print(f"Space created successfully")
      print(f"Title: {space.title}")
      print(f"DUID: {space.duid}")
      print(f"[Debug] Space DUID: {space.duid}", file=sys.stderr)
  else:
      print("[Debug] Space creation failed", file=sys.stderr)
      if result.results:
          print(f"[Debug] Result: {result.results[0]}", file=sys.stderr)
      sys.exit(1)`;
  
                          // Add proper indentation to the Python code
                          const command = pythonCode.split('\n').map(line => {
                              if (line.trim().length === 0) return line;
                              return '    ' + line;
                          }).join('\n');
  
                          console.error('[Debug] Running Python command for space creation');
                          const output = await this.runDartCommand(command);
                          console.error('[Debug] Space creation output:', output);
                          const response = {
                              content: [{
                                  type: 'text',
                                  text: output,
                              }],
                          };
                          return response;
                      }

• src/index.ts:433-495 (registration)

  Registration of the create_space tool in the ListTools response, defining its name, description, and input schema.

  {
      name: 'create_space',
      description: 'Create a new space',
      inputSchema: {
          type: 'object',
          properties: {
              title: {
                  type: 'string',
                  description: 'Title of the space'
              },
              description: {
                  type: 'string',
                  description: 'Description of the space'
              },
              abrev: {
                  type: 'string',
                  description: 'Short abbreviation for the space'
              },
              accessible_by_team: {
                  type: 'boolean',
                  description: 'Whether the space is accessible by the whole team',
                  default: true
              },
              accessible_by_user_duids: {
                  type: 'array',
                  items: {
                      type: 'string'
                  },
                  description: 'List of user DUIDs who can access the space'
              },
              icon_kind: {
                  type: 'string',
                  enum: ['None', 'Icon', 'Emoji'],
                  description: 'Kind of icon to use',
                  default: 'None'
              },
              icon_name_or_emoji: {
                  type: 'string',
                  description: 'Icon name or emoji character'
              },
              color_hex: {
                  type: 'string',
                  description: 'Color in hex format (e.g. #FF0000)'
              },
              sprint_mode: {
                  type: 'string',
                  enum: ['None', 'ANBA'],
                  description: 'Sprint mode for the space',
                  default: 'None'
              },
              sprint_replicate_on_rollover: {
                  type: 'boolean',
                  description: 'Whether to replicate sprints on rollover',
                  default: false
              },
              sprint_name_fmt: {
                  type: 'string',
                  description: 'Sprint name format'
              }
          },
          required: ['title']
      }
  },

• src/index.ts:123-227 (helper)

  Helper method that dynamically embeds Python code into a template, spawns a Python process using child_process.spawn, and executes Dart API calls via the dart library.

      async runDartCommand(args) {
          return new Promise((resolve, reject) => {
              // Use pyenv Python
              const pythonPath = '/Users/speed/.pyenv/shims/python';
              console.error('[Debug] Running Python command with:', pythonPath);
              
              const command = `import sys
  import os
  import traceback
  import json
  from dart import Dart, Operation, OperationKind, OperationModelKind, TaskCreate, TaskUpdate, TransactionKind, TaskSourceType, SpaceCreate
  from dart.generated.types import UNSET
  from dart.dart import _Session, UserBundle, _make_duid
  from dart.generated.models.icon_kind import IconKind
  from dart.generated.models.sprint_mode import SprintMode
  from dart.generated.models.validation_error_response import ValidationErrorResponse
  
  def initialize():
      print("[Debug] Starting Python execution", file=sys.stderr)
      print("[Debug] Current directory:", os.getcwd(), file=sys.stderr)
      print("[Debug] PYTHONPATH:", os.environ.get('PYTHONPATH'), file=sys.stderr)
      print("[Debug] DART_TOKEN:", os.environ.get('DART_TOKEN'), file=sys.stderr)
      
      session = _Session()
      print("[Debug] Session created", file=sys.stderr)
      bundle = UserBundle(session)
      print("[Debug] UserBundle created", file=sys.stderr)
      dartboard_duid = bundle.default_dartboard["duid"]
      print(f"[Debug] Got dartboard DUID: {dartboard_duid}", file=sys.stderr)
      client = Dart()
      print("[Debug] Dart client created", file=sys.stderr)
      
      return client, bundle, dartboard_duid
  
  def run_command(client, bundle, dartboard_duid):
      ${args}
  
  def main():
      client, bundle, dartboard_duid = initialize()
      run_command(client, bundle, dartboard_duid)
  
  try:
      main()
  except Exception as e:
      print(f"Error: {str(e)}", file=sys.stderr)
      traceback.print_exc(file=sys.stderr)
      sys.exit(1)`;
              
              console.error('[Debug] Python command:', command);
  
              // Create a clean environment without virtual env variables
              const env = { ...process.env };
              delete env.VIRTUAL_ENV;
              delete env.CONDA_PREFIX;
              delete env.CONDA_DEFAULT_ENV;
              delete env.CONDA_PYTHON_EXE;
  
              const childProcess = spawn(pythonPath, ['-c', command], {
                  env: {
                      ...env,
                      PYTHONUNBUFFERED: '1',
                      PYTHONPATH: process.env.PYTHONPATH || process.cwd(),
                      DART_TOKEN: process.env.DART_TOKEN,
                  },
                  stdio: ['pipe', 'pipe', 'pipe'],
              });
  
              let output = '';
              let errorOutput = '';
  
              childProcess.stdout?.on('data', (data) => {
                  const str = data.toString();
                  console.error('[Debug] Python stdout:', str);
                  output += str;
              });
  
              childProcess.stderr?.on('data', (data) => {
                  const str = data.toString();
                  console.error('[Debug] Python stderr:', str);
                  errorOutput += str;
              });
  
              childProcess.on('error', (error) => {
                  console.error('[Debug] Python process error:', error);
                  reject(new Error(`Failed to start Python process: ${error.message}`));
              });
  
              // Add timeout
              const timeout = setTimeout(() => {
                  console.error('[Debug] Python command timed out');
                  childProcess.kill();
                  reject(new Error('Command timed out'));
              }, 30000); // 30 second timeout
  
              childProcess.on('close', (code) => {
                  clearTimeout(timeout);
                  console.error(`[Debug] Python process exited with code ${code}`);
                  if (code === 0) {
                      resolve(output.trim());
                  } else {
                      reject(new Error(errorOutput || `Command failed with exit code ${code}`));
                  }
              });
          });
      }