npm package: @pulsestream-ai/mcp
Description: MCP server for PulseStream integration
Author: PulseStream
Latest version: 2.2.2

# PulseStream MCP Server v2.2.0

Model Context Protocol (MCP) server that integrates PulseStream with any MCP-compatible client, enabling AI-powered investigation of your Kubernetes infrastructure directly from your AI assistant.

## What's New in v2.2.0

- **27 tools** — 12 customer-facing + 13 operator + 2 auth
- **Remote debug** — execute read-only commands on customer K8s clusters via the agent
- **Diagnostic capture** — collect pod logs, events, describes, and metrics into downloadable bundles
- **Log search** — query ERROR/WARN logs in OpenSearch across customer workspaces
- **Fleet management** — tenant lookup, workspace listing, connectivity health
- **Observability** — AI analytics, onboarding funnel, system health, audit logs
- **AI-powered analysis** with streaming support
- **Proactive investigation** — ask questions without waiting for incidents
- **Published to npm** — `npm install -g @pulsestream-ai/mcp`

## Features

### Investigation & Analysis
- List and filter incident groups by status and severity
- Get detailed incident information with AI root cause analysis
- Interactive chat with AI about specific incidents
- Proactive namespace and cluster-wide investigation

### Namespace & Service Management
- List all namespaces with service counts and analysis status
- Get detailed namespace information
- Trigger AI codebase analysis for namespaces
- List services with filters by namespace
- Get service details with analysis information

### Operator Tools (require operator access token)
- **Tenant lookup** — find customers by email, org name, workspace ID, or cluster UID
- **Fleet summary** — connectivity health across all workspaces
- **Remote debug** — run read-only K8s commands on customer clusters (19 commands)
- **Diagnostic capture** — collect and download cluster diagnostic bundles
- **Log search** — query OpenSearch for ERROR/WARN logs across workspaces
- **Audit logs** — search event history with filters
- **AI analytics** — LLM performance metrics and model comparison
- **Onboarding status** — funnel metrics and stuck organizations
- **System health** — WebSocket connections, RPC errors, DB/Redis status

### Security & Authentication
- Secure access token authentication (no OAuth prompts!)
- Token stored in OS keychain
- Operator tools gated by token type — hidden from non-operator users
- Read-only and chat operations only (customer tools)
- No write access to infrastructure

## Installation

### Quick Start (Recommended)

1. **Install the Package**

   ```bash
   npm install -g @pulsestream-ai/mcp
   ```

2. **Configure Your MCP Client**

   Add the following to your MCP client's configuration:
   ```json
   {
     "mcpServers": {
       "pulsestream": {
         "command": "pulsestream-mcp",
         "env": {
           "PULSESTREAM_BACKEND_URL": "https://app.pulsestream.ai"
         }
       }
     }
   }
   ```

   For local development:
   ```json
   {
     "mcpServers": {
       "pulsestream": {
         "command": "pulsestream-mcp",
         "env": {
           "PULSESTREAM_BACKEND_URL": "http://localhost:8000"
         }
       }
     }
   }
   ```

3. **Restart Your MCP Client**

4. **Set Your Token**
    - Generate a token at https://app.pulsestream.ai/settings/access-tokens
    - In your MCP client, ask: "Set my PulseStream token"
    - Paste your token (starts with `ps_at_`)

Done! Your token is stored securely in your OS keychain.

### Platform-Specific Notes

**Windows & macOS:** Works out of the box

**Linux:** If you see keychain errors, install libsecret:
```bash
sudo apt-get install libsecret-1-dev  # Debian/Ubuntu
sudo yum install libsecret-devel      # Red Hat/CentOS
```

Or use environment variable:
```json
{
  "mcpServers": {
    "pulsestream": {
      "command": "pulsestream-mcp",
      "env": {
        "PULSESTREAM_BACKEND_URL": "https://app.pulsestream.ai",
        "PULSESTREAM_ACCESS_TOKEN": "ps_at_your_token_here"
      }
    }
  }
}
```

## Available Tools (27 Total)

### Authentication (2 tools)
- `set_token` - Configure your access token
- `logout` - Clear stored token

### Namespaces (4 tools)
- `list_namespaces` - List all Kubernetes namespaces
- `get_namespace` - Get detailed namespace information
- `analyze_namespace` - Trigger AI codebase analysis (streaming)
- `get_namespace_analysis` - View completed analysis results

### Services (2 tools)
- `list_services` - List all services with optional filters
- `get_service_details` - Get service details with analysis status

### Incident Groups (4 tools)
- `list_incident_groups` - List incidents with filters (status, severity)
- `get_incident_group` - Get detailed incident information
- `analyze_incident_group` - AI root cause analysis (streaming)
- `send_group_chat_message` - Interactive Q&A with AI (streaming)

### Proactive Investigation (2 tools)
- `investigate_namespace` - Ask AI about a namespace (streaming)
- `investigate_cluster` - Ask AI about the entire cluster (streaming)

### Operator: Tenant & Fleet (3 tools)
- `lookup_tenant` - Find customer by email, org, workspace ID, or cluster UID
- `get_fleet_summary` - Fleet-wide connectivity summary
- `list_workspaces` - List workspaces with status filters

### Operator: Remote Debug (2 tools)
- `remote_debug` - Execute read-only K8s commands on customer clusters
- `list_debug_commands` - Discover available debug commands for a workspace

### Operator: Diagnostic Capture (3 tools)
- `start_capture_session` - Collect pod logs, events, describes, metrics
- `list_capture_sessions` - List sessions with status filters
- `get_capture_session` - Get session details and download URLs

### Operator: Observability (5 tools)
- `query_audit_logs` - Search audit logs with filters
- `query_logs` - Search ERROR/WARN logs in OpenSearch
- `get_ai_analytics` - AI/LLM performance metrics
- `get_onboarding_status` - Onboarding funnel and stuck orgs
- `get_system_health` - System health summary

## Usage Examples

### Investigating an Incident

```
User: "Show me all critical incidents"
> AI uses: list_incident_groups

User: "Analyze the payment service incident"
> AI uses: analyze_incident_group (streaming AI analysis)

User: "Why did it crash?"
> AI uses: send_group_chat_message (interactive chat)
```

### Analyzing a Namespace

```
User: "What's in the production namespace?"
> AI uses: get_namespace

User: "Show me all services in production"
> AI uses: list_services

User: "Analyze the production codebase"
> AI uses: analyze_namespace (streaming analysis)
```

### Proactive Investigation

```
User: "Why is latency high in staging?"
> AI uses: investigate_namespace (AI analyzes and responds)

User: "What services are unhealthy in my cluster?"
> AI uses: investigate_cluster (cluster-wide analysis)
```

### Operator: Customer Investigation

```
User: "Look up customer acme@example.com"
> AI uses: lookup_tenant

User: "Show me their pods"
> AI uses: remote_debug (command: get_pods)

User: "Get logs from the crashing pod"
> AI uses: remote_debug (command: get_pod_logs)

User: "Capture a full diagnostic bundle"
> AI uses: start_capture_session
```

### Natural Language Queries

Just ask naturally - your AI assistant will pick the right tools:

- "Show me open incidents"
- "What services are in the production namespace?"
- "Analyze the payment service incident"
- "Why is my staging environment slow?"
- "What's failing in my cluster?"
- "Look up customer by email john@acme.com"
- "Show fleet health"
- "What's the system status?"

## Streaming Support

Five tools use Server-Sent Events (SSE) for real-time streaming:
- `analyze_namespace` - Streams codebase analysis
- `analyze_incident_group` - Streams root cause analysis
- `send_group_chat_message` - Streams AI chat responses
- `investigate_namespace` - Streams investigation results
- `investigate_cluster` - Streams cluster investigation results

The MCP server currently buffers streaming responses for client compatibility. Internal APIs remain streaming-first for future enhancements.

## Development

### Run in Development Mode

```bash
cd mcp
npm install
npm run build
npm run dev
```

### Run Tests

```bash
npm test
```

### Watch Mode (Auto-rebuild)

```bash
npm run watch
```

### Project Structure

```
mcp/
├── src/
│   ├── index.ts                    # MCP server entry point
│   ├── auth/
│   │   └── access-token-manager.ts # Access token authentication
│   ├── api/
│   │   └── pulsestream-client.ts   # PulseStream API client
│   ├── utils/
│   │   └── sse-handler.ts          # SSE streaming handler
│   ├── tools/
│   │   ├── namespaces/             # Namespace tools
│   │   ├── services/               # Service tools
│   │   ├── incidents/              # Incident group tools
│   │   ├── investigation/          # Investigation tools
│   │   ├── operator/               # Operator tools (fleet, debug, capture, etc.)
│   │   └── index.ts                # Tool exports
│   └── types/
│       └── index.ts                # TypeScript type definitions
├── tests/                          # Vitest test suite
├── dist/                           # Compiled JavaScript (generated)
├── USAGE-GUIDE.md                  # Comprehensive usage guide
├── vitest.config.ts
├── package.json
├── tsconfig.json
└── README.md
```

## Documentation

- **[Usage Guide](./USAGE-GUIDE.md)** - Comprehensive guide with workflows and examples
- **[PulseStream Docs](https://docs.pulsestream.ai)** - Full platform documentation
- **[API Reference](https://api.pulsestream.ai/docs)** - Backend API documentation

## Troubleshooting

### MCP Server Not Starting

1. Check your MCP client's configuration
2. Run `pulsestream-mcp` directly in terminal to see errors
3. Check your MCP client's developer console
4. Ensure Node.js 18+ is installed

### Authentication Fails

1. Generate a new token at https://app.pulsestream.ai/settings/access-tokens
2. Run `set_token` tool with the new token
3. Verify token starts with `ps_at_`
4. Check backend URL is correct

### "No namespaces found"

1. Verify you're a member of a workspace in PulseStream
2. Check that your organization has Kubernetes namespaces configured
3. Ensure log collection is enabled

### Keychain Access Denied (macOS)

Click "Always Allow" when prompted, or add `node` to keychain's trusted applications.

### Linux libsecret Errors

1. Install libsecret: `sudo apt-get install libsecret-1-dev`
2. Or use `PULSESTREAM_ACCESS_TOKEN` environment variable

### Streaming Timeouts

For long-running analysis:
- Increase timeout in environment: `STREAMING_TIMEOUT=180000` (3 minutes)
- Network issues may interrupt streams - retry if needed

## Security

- **Access Token Authentication**: Industry-standard PAT-style tokens (format: `ps_at_...`)
- **Secure Storage**: Tokens stored in OS keychain (Keychain Access, Credential Manager, Secret Service)
- **Safe Operations**: Customer tools are read-only or chat-based — no write/delete operations
- **Operator Gating**: Operator tools hidden from non-operator users; backend enforces access control
- **Scoped Permissions**: Tokens have granular scope control (read:namespaces, read:incidents, etc.)
- **No OAuth Prompts**: Simple token-based auth, no browser redirects

## Support

For issues or questions:

1. Check the [Usage Guide](./USAGE-GUIDE.md)
2. Review [PulseStream Documentation](https://docs.pulsestream.ai)
3. Open an issue in the [repository](https://github.com/pulsestream/pulsestream/issues)
4. Email: support@pulsestream.ai

## Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

## License

MIT License - See LICENSE file for details

## Changelog

### v2.2.0 (Current)
- 27 tools total (12 customer + 13 operator + 2 auth)
- Added 13 operator tools: tenant lookup, fleet summary, workspace listing, remote debug, debug command discovery, diagnostic capture sessions, audit log search, OpenSearch log queries, AI analytics, onboarding status, system health
- Remote debug supports 19 K8s commands via agent RPC
- Published to npm as `@pulsestream-ai/mcp`

### v2.1.0
- 14 tools (12 customer + 2 auth)
- AI-powered streaming analysis
- Proactive investigation capabilities
- Comprehensive documentation

### v2.0.0
- Access token authentication
- Replaced OAuth with PAT-style tokens
- Improved security and UX

### v1.0.3
- Initial release
- OAuth authentication
- Basic namespace listing