# Tarantella MCPs - Slack MCP Server

A Model Context Protocol (MCP) server implementation that provides Slack search capabilities to Claude and other MCP clients.

## Overview

This MCP server enables AI assistants to search Slack messages and channels using the Slack Web API. It provides two main tools:

- **search-messages**: Search across all accessible Slack messages
- **search-in-channel**: Search within a specific Slack channel

## Prerequisites

- Node.js v22 or later (see `.nvmrc`)
- A Slack workspace with API access
- A Slack Bot Token with appropriate permissions

## Slack Setup

### 1. Create a Slack App

1. Go to [https://api.slack.com/apps](https://api.slack.com/apps)
2. Click "Create New App" and choose "From scratch"
3. Give your app a name (e.g., "MCP Search Bot") and select your workspace
4. Click "Create App"

### 2. Configure OAuth Scopes

1. Navigate to "OAuth & Permissions" in the sidebar
2. Under "Bot Token Scopes", add the following scopes:
   - `search:read` - Search workspace content
   - `channels:read` - View basic channel information
   - `groups:read` - View basic private channel information
   - `im:read` - View basic direct message information
   - `mpim:read` - View basic group direct message information

### 3. Install App to Workspace

1. Scroll to "OAuth Tokens for Your Workspace"
2. Click "Install to Workspace"
3. Authorize the app
4. Copy the "Bot User OAuth Token" (starts with `xoxb-`)

### 4. Set Environment Variable

Export your token as an environment variable:

```bash
export SLACK_BOT_TOKEN="xoxb-your-token-here"
```

Or create a `.env` file (not committed to git):

```env
SLACK_BOT_TOKEN=xoxb-your-token-here
PORT=3000
```

## Installation

```bash
# Install dependencies
npm install

# Run development server with hot reload
npm run dev

# Build for production
npm run build

# Run production server
npm start
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SLACK_BOT_TOKEN` | Yes | - | Slack Bot User OAuth Token (starts with `xoxb-`) |
| `PORT` | No | 3000 | Port number for the HTTP server |

## Available MCP Tools

### 1. search-messages

Search across all accessible Slack messages in your workspace.

**Parameters:**
- `query` (required): Search query string
- `limit` (optional): Number of results to return (1-100, default: 20)
- `from_user` (optional): Filter by user ID
- `in_channel` (optional): Filter by channel ID
- `after` (optional): Filter messages after this date (YYYY-MM-DD)
- `before` (optional): Filter messages before this date (YYYY-MM-DD)
- `exclude_bots` (optional): Exclude messages from bots (boolean)
- `has_attachments` (optional): Only messages with attachments (boolean)
- `has_links` (optional): Only messages with links (boolean)

**Example:**
```json
{
  "query": "bug fix",
  "limit": 10,
  "exclude_bots": true,
  "after": "2024-01-01"
}
```

### 2. search-in-channel

Search messages within a specific Slack channel.

**Parameters:**
- `channel_id` (required): Slack channel ID (e.g., C1234567890)
- `query` (required): Search query string
- `limit` (optional): Number of results to return (1-100, default: 20)
- `from_user` (optional): Filter by user ID
- `after` (optional): Filter messages after this date (YYYY-MM-DD)
- `before` (optional): Filter messages before this date (YYYY-MM-DD)
- `exclude_bots` (optional): Exclude messages from bots (boolean)

**Example:**
```json
{
  "channel_id": "C1234567890",
  "query": "deployment",
  "limit": 5
}
```

## MCP Client Configuration

### Claude Desktop

Add this to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "slack": {
      "url": "http://localhost:3000/mcp/slack/sse",
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}
```

### Other MCP Clients

Connect to the SSE endpoint:
```
http://localhost:3000/mcp/slack/sse
```

## Development

### Code Quality

```bash
# Format and lint code
npm run check

# Type checking only
npm run typecheck

# Linting only
npm run lint

# Format only
npm run format
```

### Testing

```bash
# Run tests (watch mode)
npm test

# Run tests with UI
npm run test:ui

# Run tests with coverage (80% threshold)
npm run test:coverage

# Run mutation testing (74% threshold)
npm run test:mutation
```

### CI Pipeline

Run the full continuous integration pipeline:

```bash
npm run ci
```

This runs:
1. TypeScript type checking
2. Biome linting
3. Unit tests
4. Mutation tests

## Project Structure

```
src/
├── mcps/
│   └── slack/
│       ├── __tests__/          # Integration tests
│       ├── services/           # Slack API client
│       │   ├── __tests__/
│       │   └── slack-client.ts
│       ├── tools/              # MCP tool implementations
│       │   ├── __tests__/
│       │   ├── search-messages.ts
│       │   └── search-in-channel.ts
│       └── index.ts            # MCP server setup
├── shared/
│   ├── __tests__/
│   ├── config.ts               # Environment validation
│   └── types.ts                # Shared TypeScript types
└── server.ts                   # HTTP server entry point
```

## Technology Stack

- **Runtime**: Node.js v22
- **Language**: TypeScript 5.6+ (ESM modules)
- **MCP SDK**: @modelcontextprotocol/sdk v1.25.1
- **Web Framework**: Express v5.2.1
- **Validation**: Zod v4.2.1
- **Testing**: Vitest 2.x
- **Linter/Formatter**: Biome 2.x
- **Mutation Testing**: Stryker 8.x

## License

See LICENSE file for details.

## Contributing

1. Follow the TypeScript strictness guidelines in `CLAUDE.md`
2. Write tests for all new features (80% coverage minimum)
3. Run `npm run ci` before committing
4. Use named exports only (no default exports)
5. Extract magic numbers to named constants
6. Use bracket notation for `process.env` access

## Troubleshooting

### "SLACK_BOT_TOKEN environment variable is required" error

Make sure you've set the `SLACK_BOT_TOKEN` environment variable:
```bash
export SLACK_BOT_TOKEN="xoxb-your-token-here"
```

### Search returns no results

1. Verify your bot token has the `search:read` scope
2. Ensure the bot has been added to channels you want to search
3. Check that your search query matches actual message content

### API rate limiting

Slack has rate limits on API calls. If you hit rate limits:
- Reduce the search frequency
- Use more specific queries
- Implement caching (not currently included)

### Connection issues

If the MCP client can't connect:
1. Verify the server is running: `curl http://localhost:3000/`
2. Check the port matches your configuration
3. Review server logs for error messages