DriftOS MCP Server

Instructions

Implementation Reference

• src/tools/route.ts:47-75 (handler)

  The tool handler that routes the message using driftClient and returns a text content response with the result or an error.

  async (params) => {
    try {
      const result = await driftClient.route(
        params.conversation_id,
        params.content,
        params.role
      );
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      return {
        content: [
          {
            type: 'text' as const,
            text: `Error routing message: ${message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/route.ts:35-39 (schema)

  Input schema using Zod for validating tool parameters: conversation_id (string), content (string), role (enum).

  inputSchema: z.object({
    conversation_id: z.string().min(1).describe('Unique identifier for the conversation'),
    content: z.string().min(1).describe('The message content to route'),
    role: z.enum(['user', 'assistant']).default('user').describe('Who sent the message'),
  }).strict(),

• src/tools/route.ts:5-77 (registration)

  Function that registers the 'driftos_route_message' tool with the MCP server, providing title, description, input schema, annotations, and the handler function.

  export function registerRouteTools(server: McpServer): void {
    server.registerTool(
      'driftos_route_message',
      {
        title: 'Route Message',
        description: `Route a message to the appropriate conversation branch using semantic drift detection.
  
  Returns one of three actions:
  - BRANCH: New topic detected, creates a new branch
  - STAY: Message continues the current topic
  - ROUTE: Returns to a previously discussed topic
  
  Args:
    - conversation_id (string): Unique identifier for the conversation
    - content (string): The message content to route
    - role ('user' | 'assistant'): Who sent the message (default: 'user')
  
  Returns:
    {
      "action": "BRANCH" | "STAY" | "ROUTE",
      "branchId": string,
      "branchTopic": string,
      "confidence": number,
      "isNewBranch": boolean
    }
  
  Example:
    - "I want to buy a house in London" -> BRANCH (new topic)
    - "What areas have good schools?" -> STAY (same topic)
    - "Back to houses - what about mortgage rates?" -> ROUTE (returns to previous branch)`,
        inputSchema: z.object({
          conversation_id: z.string().min(1).describe('Unique identifier for the conversation'),
          content: z.string().min(1).describe('The message content to route'),
          role: z.enum(['user', 'assistant']).default('user').describe('Who sent the message'),
        }).strict(),
        annotations: {
          readOnlyHint: false,
          destructiveHint: false,
          idempotentHint: false,
          openWorldHint: false,
        },
      },
      async (params) => {
        try {
          const result = await driftClient.route(
            params.conversation_id,
            params.content,
            params.role
          );
  
          return {
            content: [
              {
                type: 'text' as const,
                text: JSON.stringify(result, null, 2),
              },
            ],
          };
        } catch (error) {
          const message = error instanceof Error ? error.message : 'Unknown error';
          return {
            content: [
              {
                type: 'text' as const,
                text: `Error routing message: ${message}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/index.ts:17-17 (registration)

  Calls registerRouteTools to register the tool on the main McpServer instance.

  registerRouteTools(server);

• src/services/drift-client.ts:1-4 (helper)

  Exports the driftClient instance created from external library, used in the tool handler for routing messages.

  import { createDriftClient } from '@driftos/client';
  import { DRIFTOS_API_URL } from '../constants.js';
  
  export const driftClient = createDriftClient(DRIFTOS_API_URL);