flipside-mcp-extension/README.md

# Flipside Intelligence via MCP

## What it is
An AI agent that acts as your personal blockchain data scientist, accessible directly through Claude Desktop via Model Context Protocol (MCP).

## How it works
Natural language interface to Flipside's curated blockchain datasets and embedded analytical workflows. Simply ask questions in plain English and get sophisticated blockchain analytics instantly.

## Key capabilities
- **Complex Analysis Made Simple**: Execute cohort analysis, user journey mapping, and trend detection through conversational queries
- **Comprehensive Data Access**: Query data across 30+ blockchain networks with billions of indexed transactions
- **Proprietary Insights**: Access Flipside's specialized scoring algorithms and predictive metrics
- **Domain Expertise**: Leverage years of blockchain growth intelligence embedded in AI workflows

## The Vision
Democratize blockchain data science expertise. For the first time, any stakeholder—from ecosystem CEOs to community managers—can conduct sophisticated blockchain analysis without years of technical training.

## Integration
Available through Claude Desktop's MCP integration, bringing enterprise-grade blockchain analytics directly into your workflow without switching tools or platforms.

---

*Flipside Intelligence transforms specialized data science expertise into accessible AI-powered tools, making blockchain growth insights available to everyone.*

## Technical Features

- **Zero Dependencies**: Self-contained Go binary with no runtime requirements
- **Cross-Platform**: Supports macOS, Linux, and Windows (x64 and ARM64)
- **Secure Connection**: Environment-based configuration with encrypted API key authentication
- **Real-time Analytics**: Direct access to live blockchain data streams
- **Optimized Performance**: Lightweight proxy design for seamless Claude Desktop integration

## Configuration

The proxy is configured via environment variables:

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `MCP_REMOTE_URL` | Yes | Flipside Intelligence MCP endpoint | `https://mcp.flipsidecrypto.xyz/beta/sse` |
| `FLIPSIDE_API_KEY` | Yes | Your Flipside API key for authenticated access | `your-api-key-here` |
| `MCP_DEBUG` | No | Enable debug logging | `true` or `false` |

## Installation

### As a Claude Desktop Extension (Recommended)

1. Download the appropriate `.dxt` file for your platform from releases
2. Import the DXT file into Claude Desktop
3. Configure your Flipside API key and MCP endpoint in the extension settings
4. Start analyzing blockchain data with natural language queries in Claude Desktop

### Manual Installation

1. Download the binary for your platform:
   - macOS (Intel): `remote-mcp-proxy-darwin-amd64`
   - macOS (Apple Silicon): `remote-mcp-proxy-darwin-arm64`
   - Linux (x64): `remote-mcp-proxy-linux-amd64`
   - Linux (ARM64): `remote-mcp-proxy-linux-arm64`
   - Windows (x64): `remote-mcp-proxy-windows-amd64.exe`
   - Windows (ARM64): `remote-mcp-proxy-windows-arm64.exe`

2. Make executable (Unix-like systems):
   ```bash
   chmod +x remote-mcp-proxy-*
   ```

3. Configure environment variables:
   ```bash
   export MCP_REMOTE_URL="https://mcp.flipsidecrypto.xyz/beta/sse"
   export FLIPSIDE_API_KEY="your-api-key-here"
   export MCP_DEBUG="false"  # Optional
   ```

4. Run the proxy:
   ```bash
   ./remote-mcp-proxy-darwin-amd64
   ```

## Usage Examples

Once connected through Claude Desktop, you can ask natural language questions like:

- "Show me the top 10 DeFi protocols by TVL on Ethereum this week"
- "Analyze user retention patterns for Uniswap v3 over the last 6 months"
- "What's the correlation between gas prices and DEX trading volume?"
- "Create a cohort analysis of new wallet addresses on Polygon"

The extension handles all the technical complexity, translating your questions into sophisticated blockchain queries and returning actionable insights.

## Getting Your API Key

To access Flipside Intelligence:

1. Visit [flipsidecrypto.xyz](https://flipsidecrypto.xyz) 
2. Create an account or sign in
3. Navigate to your API settings to generate your key
4. Use this key in the extension configuration

## Development

### Building from Source

```bash
# Install dependencies
make deps

# Build and package both Go and Node.js desktop extensions
make dxt-all

# Build just the Go desktop extension
make dxt

# Build just the Node.js desktop extension
make dxt-node

# Create tar.gz packages (alternative format)
make dxt-tar
```

**Note**: The DXT packages are properly formatted for Claude Desktop. The Go implementation provides a cross-platform proxy binary, while the Node.js implementation uses `npx mcp-remote` for a simpler setup.

### Creating Releases

The project uses tag-based releases that trigger automatic builds and publishing via GitHub Actions:

```bash
# Create a patch release (e.g., 1.2.3 -> 1.2.4)
make release-patch

# Create a minor release (e.g., 1.2.3 -> 1.3.0)  
make release-minor

# Create a major release (e.g., 1.2.3 -> 2.0.0)
make release-major
```

**Release Process:**

1. **Choose release type** based on your changes:
   - `patch`: Bug fixes, small improvements
   - `minor`: New features, backward-compatible changes
   - `major`: Breaking changes

2. **Run the release command** - it will:
   - Show current version and calculated new version
   - Ask for confirmation before proceeding
   - Create and push the version tag to GitHub

3. **GitHub Actions automatically:**
   - Builds binaries for all platforms
   - Creates a GitHub release
   - Uploads DXT and tar.gz packages
   - Updates the manifest.json with the new version

**Manual Release (if needed):**
```bash
# Create and push a version tag manually
git tag v1.3.0
git push origin v1.3.0
```

The release will be available at: `https://github.com/flipside-org/flipside-mcp-extension/releases`

### Project Structure

```
/
├── main.go           # Go proxy implementation
├── manifest.json     # Go extension manifest
├── node/            # Node.js implementation
│   ├── manifest.json # Node.js extension manifest
│   └── icon.png     # Extension icon
├── Makefile         # Build automation
├── README.md        # This file
├── go.mod           # Go module definition
└── dist/            # Build artifacts (created by make)
```

### Testing

The project includes comprehensive unit tests for the proxy server functionality:

```bash
# Run unit tests
go test -v

# Run tests with coverage
go test -v -race -coverprofile=coverage.out

# View coverage report
go tool cover -html=coverage.out

# Run tests via Makefile (includes functional testing)
make test
```

**Test Coverage:**
- Proxy creation and configuration
- Client authentication (Bearer tokens + query parameters)
- URL conversion (SSE → MCP endpoints)
- Error handling and network failures
- API key security (masking functionality)
- Integration testing with mock MCP server

### CI/CD Pipeline

All pull requests and pushes to main automatically run:

**Test Workflow:**
- Unit tests with race detection and coverage reporting
- Cross-platform build verification (Linux, macOS, Windows)
- Code quality checks with golangci-lint
- Security scanning with gosec and govulncheck
- Makefile integration testing

**Quality Gates:**
- All tests must pass before merge
- Code coverage tracking via Codecov
- Security vulnerabilities blocking deployment
- Linting errors preventing merge

To ensure your PR passes CI:
```bash
# Run the same checks locally
go test -v -race -coverprofile=coverage.out
go build -v .
make test
```

### Dependencies

- [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) - MCP protocol implementation for Go
- [@anthropic-ai/dxt](https://www.npmjs.com/package/@anthropic-ai/dxt) - For packaging desktop extensions
- [mcp-remote](https://www.npmjs.com/package/mcp-remote) - For Node.js implementation

## Security Considerations

- The proxy forwards all requests to the configured remote URL
- Ensure your remote MCP server implements proper authentication and authorization
- Use HTTPS URLs for production deployments
- Consider network timeouts and rate limiting on the server side

## Troubleshooting

### Enable Debug Logging

Set `MCP_DEBUG=true` to see detailed request/response logs:

```bash
MCP_DEBUG=true MCP_REMOTE_URL=https://mcp.flipsidecrypto.xyz/beta/sse FLIPSIDE_API_KEY=your-key ./flipside-mcp-extension
```

### Common Issues

1. **Authentication failed**: Verify your Flipside API key is correct and active
2. **Connection refused**: Check your internet connection and firewall settings
3. **Timeout errors**: Large queries may take time; try breaking them into smaller requests
4. **Rate limiting**: Ensure you're within your API plan limits

## License

MIT License - see the project root for details.

## Support

For issues and questions:
- GitHub Issues: [flipside-org/flipside-mcp-extension](https://github.com/flipside-org/flipside-mcp-extension/issues)
- Documentation: [docs.flipsidecrypto.xyz](https://docs.flipsidecrypto.xyz)
- Email: support@flipside.xyz