Use when: Service has REST API, no webhooks
Examples: GitHub, Linear, Todoist
Structure: index.ts, account-create.ts, schedule.ts, mcp/

Use when: Service provides webhook events
Examples: Slack, Discord, Linear webhooks
Structure: index.ts, account-create.ts, create-activity.ts, identify.ts, mcp/

# Fork and clone CORE repository
git clone https://github.com/YOUR-USERNAME/core.git
cd core/integrations

# Create your integration directory
mkdir your-service
cd your-service

# Copy structure from similar integration
cp -r ../linear/* .  # For schedule-based
# OR
cp -r ../slack/* .   # For webhook-based

# Install dependencies
npm install

// src/account-create.ts
export async function integrationCreate(data: any) {
  const { oauthResponse } = data;

  // Get user info from service API
  const user = await getUser(oauthResponse.access_token);

  return [{
    type: 'account',
    data: {
      accountId: user.id,
      config: {
        access_token: oauthResponse.access_token,
        refresh_token: oauthResponse.refresh_token,
      },
      settings: {
        username: user.username,
        // Add service-specific settings
      }
    }
  }];
}

export async function handleSchedule(config: any, state: any) {
  const lastSync = state?.lastSyncTime || getDefault24HoursAgo();
  const activities = [];

  // Fetch new data since last sync
  const items = await fetchItems(config.access_token, lastSync);

  // Create activity messages
  for (const item of items) {
    activities.push({
      type: 'activity',
      data: {
        text: `${item.user} created issue #${item.number}: ${item.title}`,
        sourceURL: item.url
      }
    });
  }

  // Save state for next sync
  activities.push({
    type: 'state',
    data: { lastSyncTime: new Date().toISOString() }
  });

  return activities;
}

// identify.ts - Extract user ID for routing
export async function identify(integration: any, eventBody: any) {
  return [{
    type: 'identifier',
    data: eventBody.event.user
  }];
}

// create-activity.ts - Process webhook event
export async function createActivityEvent(eventData: any, config: any) {
  const event = eventData.event;

  const text = `${event.user} mentioned you: ${event.message}`;
  const url = await getPermalink(config.access_token, event.id);

  return [{
    type: 'activity',
    data: { text, sourceURL: url }
  }];
}

// src/mcp/index.ts
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

// Define tool schemas
const CreateIssueSchema = z.object({
  title: z.string().describe('Issue title'),
  description: z.string().optional().describe('Issue description'),
  assignee: z.string().optional().describe('User to assign'),
});

const SearchIssuesSchema = z.object({
  query: z.string().describe('Search query'),
  status: z.string().optional().describe('Filter by status'),
});

// Export tools list
export async function getTools() {
  return [
    {
      name: 'create_issue',
      description: 'Create a new issue in the project',
      inputSchema: zodToJsonSchema(CreateIssueSchema),
    },
    {
      name: 'search_issues',
      description: 'Search for issues',
      inputSchema: zodToJsonSchema(SearchIssuesSchema),
    },
  ];
}

// Implement tool execution
export async function callTool(name: string, args: any, apiKey: string) {
  switch (name) {
    case 'create_issue':
      const issue = await createIssue(apiKey, args);
      return { content: [{ type: 'text', text: `Created issue #${issue.id}` }] };

    case 'search_issues':
      const results = await searchIssues(apiKey, args);
      return { content: [{ type: 'text', text: JSON.stringify(results) }] };

    default:
      throw new Error(`Unknown tool: ${name}`);
  }
}

// src/index.ts
import { IntegrationCLI, IntegrationEventPayload, IntegrationEventType, Spec } from '@redplanethq/sdk';
import { integrationCreate } from './account-create';
import { handleSchedule } from './schedule'; // or createActivityEvent + identify
import { getTools, callTool } from './mcp';

export async function run(eventPayload: IntegrationEventPayload) {
  switch (eventPayload.event) {
    case IntegrationEventType.SETUP:
      return await integrationCreate(eventPayload.eventBody);

    case IntegrationEventType.SYNC:
      return await handleSchedule(eventPayload.config, eventPayload.state);

    case IntegrationEventType.GET_TOOLS:
      return await getTools();

    case IntegrationEventType.CALL_TOOL:
      const { name, arguments: args } = eventPayload.eventBody;
      return await callTool(name, args, eventPayload.config.apiKey);

    default:
      return { message: `Unknown event: ${eventPayload.event}` };
  }
}

class YourServiceCLI extends IntegrationCLI {
  constructor() {
    super('your-service', '1.0.0');
  }

  protected async handleEvent(eventPayload: IntegrationEventPayload) {
    return await run(eventPayload);
  }

  protected async getSpec(): Promise<Spec> {
    return {
      name: 'Your Service',
      key: 'your-service',
      description: 'Integration description',
      icon: 'your-service',
      schedule: { frequency: '*/5 * * * *' }, // For schedule-based
      auth: {
        OAuth2: {
          token_url: 'https://api.service.com/oauth/token',
          authorization_url: 'https://api.service.com/oauth/authorize',
          scopes: ['read', 'write'],
          scope_separator: ',',
        },
      },
      mcp: { type: 'cli' },
    };
  }
}

function main() {
  const cli = new YourServiceCLI();
  cli.parse();
}

main();

git checkout -b add-your-service-integration
git add integrations/your-service
git commit -m "Add Your Service integration"
git push origin add-your-service-integration