Swit MCP Server

Instructions

Implementation Reference

• src/handlers/oauth.handlers.ts:17-45 (handler)

  The core handler function that implements the logic for the 'swit-oauth-start' tool. It checks if OAuth is initialized and not already authenticated, then generates an authorization URL, web server URL, and provides step-by-step instructions.

  export const handleOAuthStart = async (oauthWebServer: OAuthWebServer | null) => {
    if (!oauthWebServer) {
      return {
        error:
          'OAuth web server is not initialized. Please check SWIT_CLIENT_ID and SWIT_CLIENT_SECRET environment variables.',
      };
    }
  
    if (oauthWebServer.isAuthenticated()) {
      return {
        error: 'OAuth authentication already completed.',
        note: 'To re-authenticate, please logout first.',
      };
    }
  
    const authUrl = oauthWebServer.getAuthorizationUrl();
    const port = process.env.OAUTH_PORT || '3000';
  
    return {
      authorizationUrl: authUrl,
      webServerUrl: `http://localhost:${port}`,
      instructions: [
        '1. Open the authorizationUrl above in your browser.',
        '2. Login with your Swit account and authorize the application.',
        '3. The token will be automatically saved upon completion.',
        '4. Use swit-oauth-status to check authentication status.',
      ],
    };
  };

• src/tools/oauth.tools.ts:12-16 (schema)

  Defines the tool schema including name, description, and empty input schema (no parameters required).

  {
    name: 'swit-oauth-start',
    description: 'Start OAuth authentication. Returns authentication URL that can be opened in browser.',
    inputSchema: zodToJsonSchema(EmptySchema),
  },

• src/handlers/oauth.handlers.ts:62-66 (registration)

  Registers the 'swit-oauth-start' tool handler by mapping the tool name to the handleOAuthStart function.

  export const oauthHandlers = (oauthWebServer: OAuthWebServer | null) => ({
    'swit-oauth-status': () => handleOAuthStatus(oauthWebServer),
    'swit-oauth-start': () => handleOAuthStart(oauthWebServer),
    'swit-oauth-logout': () => handleOAuthLogout(oauthWebServer),
  });

• src/index.ts:61-63 (registration)

  Registers the tool list handler which includes 'swit-oauth-start' from oauthTools for the MCP ListTools request.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools: [...oauthTools, ...coreTools] };
  });

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

  Dynamically sets up the toolHandlers object which includes the 'swit-oauth-start' handler from oauthHandlers for tool execution.

  toolHandlers = { ...oauthHandlers(oauthWebServer), ...coreHandlers(switClient) };