npm package: @osiris-ai/slack-sdk
Description: Osiris Slack SDK
Latest version: 0.1.1

# @osiris-ai/slack-sdk

OAuth 2.0 Slack authenticator for building authenticated MCPs with Slack workspace integration.

[![npm version](https://badge.fury.io/js/@osiris-ai%2Fslack-sdk.svg)](https://badge.fury.io/js/@osiris-ai%2Fslack-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

The Slack SDK provides seamless OAuth 2.0 authentication for Slack in the [Osiris](https://docs.osirislabs.xyz) ecosystem. Build powerful MCPs (Model Context Protocol) that can interact with Slack workspaces, channels, and users with enterprise-grade security and zero-configuration authentication.

**Key Features:**
- 🔐 **Zero-config OAuth** - No client credentials or setup required
- 🏢 **Workspace Integration** - Full access to Slack workspaces and teams
- 👥 **User & Bot Scopes** - Support for both workspace and user permissions
- 🔄 **OAuth v2** - Latest Slack OAuth implementation
- 🛡️ **Enterprise Security** - Built on Osiris Hub authentication
- 📝 **Full TypeScript** - Complete type safety and IDE support

## Installation

```bash
npm install @osiris-ai/slack-sdk @osiris-ai/sdk
```

## Quick Start

### Hub Authentication (Recommended)

The Slack authenticator works automatically through the Osiris Hub - no Slack OAuth app setup required.

```typescript
import { createMcpServer, getAuthContext } from '@osiris-ai/sdk';
import { createSuccessResponse, createErrorResponse } from '../utils/types.js';
import { z } from 'zod';

await createMcpServer({
  name: 'slack-mcp',
  version: '1.0.0',
  auth: {
    useHub: true,
    hubConfig: {
      baseUrl: process.env.HUB_BASE_URL!,
      clientId: process.env.OAUTH_CLIENT_ID!,
      clientSecret: process.env.OAUTH_CLIENT_SECRET!,
    }
  },
  configure: (server) => {
    // Send Slack message
    server.tool(
      'send_slack_message',
      'Send a message to a Slack channel',
      {
        channel: z.string(),
        text: z.string(),
        username: z.string().optional()
      },
      async ({ channel, text, username }) => {
        try {
          const { token, context } = getAuthContext("osiris");
          if (!token || !context) {
            return createErrorResponse("User not authenticated");
          }

          const response = await fetch(`https://api.osirislabs.xyz/v1/hub/action/${context.deploymentId}/slack/chat.postMessage`, {
            method: 'POST',
            headers: {
              'Authorization': `Bearer ${token.access_token}`,
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              channel,
              text,
              username
            })
          });

          const result = await response.json();
          return createSuccessResponse('Message sent successfully', {
            timestamp: result.ts,
            channel: result.channel
          });
        } catch (error) {
          return createErrorResponse(error);
        }
      }
    );
  }
});
```

### Available Slack Scopes

Configure your MCP to request specific Slack permissions:

All slack scopes are supported and they all need to prefixed with `slack:`

## Local Authentication (Advanced)

For custom authentication flows or enterprise requirements:

```typescript
import { SlackAuthenticator } from '@osiris-ai/slack-sdk';
import { createMcpServer } from '@osiris-ai/sdk';

const slackAuth = new SlackAuthenticator(
  ['channels:read', 'chat:write', 'users:read'],
  {
    clientId: process.env.SLACK_CLIENT_ID!,
    clientSecret: process.env.SLACK_CLIENT_SECRET!,
    redirectUri: 'http://localhost:3000/slack/callback'
  }
);

await createMcpServer({
  name: 'slack-mcp',
  version: '1.0.0',
  auth: {
    useHub: false,
    directAuth: {
      slack: slackAuth
    }
  },
  configure: (server) => {
    // Your Slack tools here
  }
});
```

## API Reference

### SlackAuthenticator

The main authenticator class for Slack OAuth integration.

```typescript
class SlackAuthenticator extends OAuthAuthenticator<SlackCallbackParams, SlackTokenResponse>
```

#### Constructor

```typescript
new SlackAuthenticator(allowedScopes: string[], config: SlackAuthenticatorConfig)
```

**Parameters:**
- `allowedScopes`: Array of Slack OAuth scopes your MCP requires
- `config`: Slack OAuth application configuration

#### Methods

##### `getAuthenticationURL(scopes: string[], options: AuthenticationURLOptions): string`

Generate Slack OAuth authorization URL with user scope support.

##### `callback(params: SlackCallbackParams): Promise<SlackTokenResponse>`

Handle OAuth callback and exchange code for tokens.

##### `getUserInfo(accessToken: string): Promise<SlackUserInfo>`

Get authenticated user information.

##### `action(params: ActionParams, accessToken: string, refreshToken?: string): Promise<ActionResponse>`

Execute Slack API actions with automatic error handling.

**Note:** Slack OAuth v2 provides both workspace and user tokens in the response.

## Getting Started

1. **Install the Osiris CLI:**
   ```bash
   npm install -g @osiris-ai/cli
   ```

2. **Set up authentication:**
   ```bash
   npx @osiris-ai/cli register
   npx @osiris-ai/cli connect-auth
   ```

3. **Create your Slack MCP:**
   ```bash
   npx @osiris-ai/cli create-app my-slack-mcp
   ```

4. **Add Slack integration:**
   ```bash
   npm install @osiris-ai/slack-sdk
   ```

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/fetcchx/osiris-ai/blob/main/CONTRIBUTING.md) for details.

## Support

- **Documentation:** [https://docs.osirislabs.xyz](https://docs.osirislabs.xyz)
- **GitHub Issues:** [https://github.com/fetcchx/osiris-ai/issues](https://github.com/fetcchx/osiris-ai/issues)
- **Discord Community:** [Join our Discord](https://discord.osirislabs.xyz)

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

Built with ❤️ by the [Osiris Labs](https://osirislabs.xyz) team.