# Slack Code MCP

Model Context Protocol (MCP) is a standardized way for LLMs to use external systems through tools. This repository provides a focused remote MCP server for Slack Web API so agents can discover operations and execute validated API calls with a fixed low-context tool surface.

Design references:
- [Cloudflare Code Mode MCP](https://blog.cloudflare.com/code-mode-mcp/)
- [Anthropic: Building Effective Agents (advanced tool use)](https://www.anthropic.com/engineering/building-effective-agents)

The server supports `streamable-http` transport via `/mcp`.

## Server in this Repository

| Server | Description | URL |
| --- | --- | --- |
| `slack-code-mcp` | Search + execute over Slack Web API operations with OAuth and write guardrails | `http://127.0.0.1:3000/mcp` |

## Tools Exposed

| Tool | Purpose | Typical use |
| --- | --- | --- |
| `search` | Finds ranked operations from Slack method catalog + docs context | "list channels", "post message", "get conversation history" |
| `execute` | Validates and executes operation by `operation_id` | Read and write API calls with typed validation |
| `auth_status` | Returns auth status for current caller | Preflight before `execute` |

## Why Better Than Official MCP Patterns

Compared to official/provider MCP servers that expose many endpoint-level tools, this implementation is better for agent behavior:

- Fixed `3`-tool interface keeps context and tool-selection ambiguity low.
- Two-step control loop (`search` then `execute`) aligns with how agents plan and call tools.
- Write safety is explicit: server policy gate plus per-call confirmation token.
- Performance controls (catalog cache, read cache, response truncation) reduce latency and context bloat.

## Access from Any MCP Client

If your MCP client supports remote MCP directly:

```json
{
  "mcpServers": {
    "slack-code-mcp": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}
```

If your client needs a command bridge:

```json
{
  "mcpServers": {
    "slack-code-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp"],
      "env": {
        "MCP_REMOTE_HEADERS": "{\"x-user-id\":\"default\"}"
      }
    }
  }
}
```

## Quick Start

```bash
cd slack
npm install
npm run build
npm test
```

Seed access token from environment:

```bash
SLACK_BOT_TOKEN='<xoxb-token>' npm run seed:token
```

Start server:

```bash
TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64='<seed-output-key>' \
PORT=3000 HOST=127.0.0.1 npm run dev
```

Smoke test:

```bash
curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp
```

## Tool Calling Flow

1. Call `auth_status`.
2. Call `search` with intent (for example, `list channels`).
3. Pick an `operation_id`.
4. Call `execute` with required params in `body`.
5. For writes: call `dry_run=true`, then replay with `confirm_write_token` and `ALLOW_WRITES=true`.

Example `search` input:

```json
{
  "query": "post a message to a channel",
  "limit": 5
}
```

Example read `execute` input:

```json
{
  "operation_id": "POST /conversations.list"
}
```

Example write `execute` dry run:

```json
{
  "operation_id": "POST /chat.postMessage",
  "body": {
    "channel": "C12345678",
    "text": "Hello from Slack Code MCP"
  },
  "dry_run": true
}
```

## Configuration

Key environment variables:

- `ALLOW_WRITES` (default `false`)
- `REQUEST_TIMEOUT_MS`
- `MAX_RETRIES`
- `CATALOG_CACHE_PATH`
- `READ_CACHE_TTL_MS`
- `EXECUTE_MAX_BODY_BYTES`
- `EXECUTE_BODY_PREVIEW_CHARS`

See `.env.example` for the full set.

## Safety Model

- Mutating operations are blocked unless `ALLOW_WRITES=true`.
- Mutating calls require `confirm_write_token` from matching dry-run request.
- Sensitive headers and body fields are redacted.

## Performance Model

- Fixed 3-tool MCP surface to keep context small.
- Persisted catalog cache enables fast startup and asynchronous refresh.
- Conditional docs refresh (`ETag`/`Last-Modified`) where available.
- Short TTL cache for repeated read operations.
- Execute body truncation controls context overhead.

## Troubleshooting

- MCP Inspector connect failure: confirm URL is `http://127.0.0.1:3000/mcp` and server is running.
- `AUTH_REQUIRED`: seed token or complete OAuth bootstrap.
- Write blocked: set `ALLOW_WRITES=true` and use returned `confirm_write_token`.
- Slack API error with HTTP 200: Slack methods often return `{ ok: false, error: "..." }`; this is surfaced as tool error.

## Development

- Source: `src`
- Tests: `tests`
- References: `REFERENCES.md`