npm package: @pwhermanson/stax-mcp-server
Description: Stax MCP Client - Connect Cursor to Stax Cloud with provider-agnostic authentication
Author: Stax AI
Latest version: 1.1.1

# Stax MCP Server

Enterprise-grade Model Context Protocol (MCP) server for the Stax AI development platform. This server provides powerful tools for code analysis, project management, and GitHub integration.

## Features

- 🔧 **13 MCP Tools** - Comprehensive set of development tools
- 🔐 **Secure Authentication** - JWT-based authentication system
- ⚡ **Redis Caching** - High-performance caching with Upstash Redis
- 🐙 **GitHub Integration** - Full GitHub API integration
- 📊 **Health Monitoring** - Built-in health checks and monitoring
- 🚀 **Easy Deployment** - Simple CLI-based deployment

## Quick Start

### Installation

```bash
npm install -g @stax/mcp-server
```

### Setup

Run the interactive setup to configure your credentials:

```bash
stax-mcp-server setup
```

### Running the Server

```bash
stax-mcp-server run <your-config-key>
```

## Configuration

### Cursor MCP Configuration

Add this to your Cursor MCP configuration file:

```json
{
  "mcpServers": {
    "stax-mcp-server": {
      "command": "npx",
      "args": ["-y", "@stax/mcp-server@latest", "run", "your-config-key"]
    }
  }
}
```

### Environment Variables

The server can be configured using environment variables:

```bash
# Required
GITHUB_TOKEN=your_github_token
GITHUB_REPO_OWNER=your_username
GITHUB_REPO_NAME=your_repo
UPSTASH_REDIS_URL=your_redis_url
UPSTASH_REDIS_TOKEN=your_redis_token
MCP_AUTH_SECRET=your_jwt_secret

# Optional
STAX_APP_URL=http://localhost:3000
STAX_CONFIG_KEY=your_config_key
```

## Available Tools

### Project Analysis Tools

- `fetch_blueprint` - Get project blueprint information
- `fetch_tech_stack` - Get technology stack details
- `fetch_project_structure` - Get project structure analysis
- `fetch_dependencies` - Get project dependencies
- `fetch_readme` - Get README content

### Code Analysis Tools

- `fetch_file_content` - Fetch file content from GitHub
- `fetch_directory_contents` - List directory contents
- `search_code` - Search for code patterns
- `find_related_code` - Find code related to specific features
- `build_diff_analysis` - Analyze code changes and impact

### Repository Tools

- `fetch_repository_info` - Get repository metadata
- `fetch_branches` - Get Git branch information

### Utility Tools

- `puns` - Fun utility tool

## CLI Commands

### `stax-mcp-server run <config-key>`

Run the MCP server with the specified configuration key.

**Options:**

- `-p, --port <port>` - Port to run the server on (default: 8080)
- `-e, --env <file>` - Environment file path
- `--verbose` - Enable verbose logging

### `stax-mcp-server setup`

Interactive setup wizard for configuring credentials.

### `stax-mcp-server config`

Generate Cursor MCP configuration file.

**Options:**

- `-o, --output <file>` - Output file path (default: mcp-config.json)

### `stax-mcp-server health`

Check server health status.

**Options:**

- `-u, --url <url>` - Server URL (default: http://localhost:8080)

## Configuration Management

The server supports multiple configuration sources in order of preference:

1. **Local Configuration** - `.stax-mcp-server/config.json` in your project
2. **Global Configuration** - `~/.stax-mcp-server/config.json` in your home directory
3. **Environment Variables** - Standard environment variables
4. **Stax API** - Remote configuration from Stax's API (future feature)

## Security

- All credentials are stored securely and never exposed in logs
- JWT-based authentication for MCP protocol endpoints
- Rate limiting and request validation
- CORS protection and security headers

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Linting

```bash
npm run lint
```

## Deployment

### Railway

```bash
npm run deploy:railway
```

### Docker

```bash
docker build -t stax-mcp-server .
docker run -p 8080:8080 stax-mcp-server
```

## Support

- 📧 Email: support@stax.ai
- 🐛 Issues: [GitHub Issues](https://github.com/stax-ai/mcp-server/issues)
- 📖 Documentation: [Stax Docs](https://docs.stax.ai)

## License

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

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

---

Made with ❤️ by the Stax AI team