# MCP Server for Alignment Forum

An MCP (Model Context Protocol) server that provides access to alignment-related posts from LessWrong and Alignment Forum. This server acts as a research mentor, helping you quickly understand AI alignment concepts and discover unknown unknowns through semantic search and content retrieval.

## Features

- **Semantic Search**: Search through 60+ alignment posts using natural language queries
- **Recent Posts**: Browse the latest alignment research chronologically
- **Full Article Access**: Retrieve complete article content including HTML, metadata, and images
- **Daily Updates**: Automatically syncs with LessWrong via GitHub Actions
- **Efficient Storage**: CSV-based approach with plaintext descriptions
- **High-Quality Content**: Includes major works by Eliezer Yudkowsky, Paul Christiano, Nate Soares, and others

## Quick Start (Recommended)

The easiest way to use this MCP server is with the hosted deployment. Just add this to your Claude Desktop config:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux**: `~/.config/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "alignment-forum": {
      "url": "https://alignmentforum.fastmcp.app/mcp",
      "transport": "sse"
    }
  }
}
```

Then **completely quit and restart Claude Desktop**. That's it! You can now search and read Alignment Forum posts directly in Claude.

## Local Installation (Optional)

### Prerequisites

- Python 3.10 or higher
- pip or uv package manager

### Setup

1. **Clone the repository**:

   ```bash
   cd ~/Github
   git clone https://github.com/YOUR_USERNAME/mcp-alignmentforum.git
   cd mcp-alignmentforum
   ```

2. **Install dependencies**:

   ```bash
   pip install -e .
   ```

   Or using `uv` (recommended):

   ```bash
   uv pip install -e .
   ```

3. **Update configuration**:

   - Edit `src/mcp_alignmentforum/server.py`
   - Replace `YOUR_USERNAME` with your GitHub username in the CSV_URL constant

4. **Run initial data collection** (optional):
   ```bash
   export OPENROUTER_API_KEY="your-api-key-here"
   python scripts/update_posts.py
   ```

## Testing the Server

Before configuring Claude Desktop, you can test the MCP server using the MCP Inspector:

```bash
# Test remote server (recommended)
npx @modelcontextprotocol/inspector sse \
  https://alignmentforum.fastmcp.app/mcp

# Test local server
npx @modelcontextprotocol/inspector \
  /usr/local/bin/uv \
  --directory /Users/ram/Github/mcp-alignmentforum \
  run \
  mcp-alignmentforum
```

This will:

1. Start the MCP server
2. Open a web interface at `http://localhost:5173`
3. Allow you to interactively test all three tools:
   - `search_posts` - Semantic search through alignment posts
   - `list_recent_posts` - Browse recent posts chronologically
   - `fetch_article_content` - Get full article content

## Usage with Claude Desktop

### Remote Server (Recommended)

See the [Quick Start](#quick-start-recommended) section above to use the hosted deployment at `https://alignmentforum.fastmcp.app/mcp`.

### Local Server (Advanced)

If you've installed the server locally, add the following to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux**: `~/.config/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "alignment-forum": {
      "command": "/usr/local/bin/uv",
      "args": [
        "--directory",
        "/Users/ram/Github/mcp-alignmentforum",
        "run",
        "mcp-alignmentforum"
      ]
    }
  }
}
```

**Note**: Replace `/Users/ram/Github/mcp-alignmentforum` with the actual path to your cloned repository.

### Restart Claude Desktop

After updating the configuration, **completely quit and restart** Claude Desktop for the changes to take effect.

## Remote Deployment (Railway)

**Note**: A public deployment is already available at `https://alignmentforum.fastmcp.app/mcp` (see [Quick Start](#quick-start-recommended)). The instructions below are for deploying your own custom instance.

### Deploy to Railway

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https://github.com/rapturt9/mcp-alignmentforum)

Or manually deploy:

1. **Push your code to GitHub** (if not already done)

2. **Create a new project on Railway**:

   - Go to [railway.app](https://railway.app)
   - Click "New Project"
   - Select "Deploy from GitHub repo"
   - Choose `mcp-alignmentforum`

3. **Railway will automatically**:

   - Detect the Dockerfile
   - Install dependencies from `pyproject.toml`
   - Start the server using the Procfile
   - Assign a public URL (e.g., `https://your-app.railway.app`)

4. **Get your deployment URL**:
   - Go to your Railway project settings
   - Copy the public domain URL
   - Your SSE endpoint will be: `https://your-app.railway.app/mcp`

### Use Custom Remote Deployment in Claude Desktop

Update your Claude Desktop config to use your custom deployment:

```json
{
  "mcpServers": {
    "alignment-forum-custom": {
      "url": "https://your-app.railway.app/mcp",
      "transport": "sse"
    }
  }
}
```

Replace `your-app.railway.app` with your actual Railway deployment URL.

### Environment Variables (Optional)

Railway deployment doesn't require any environment variables, but you can add:

- `PORT` - Railway sets this automatically (default: 8000)
- `HOST` - Defaults to `0.0.0.0`

### Monitoring

- **Railway Dashboard**: Monitor logs, metrics, and deployments
- **Health Check**: Railway automatically checks `/` endpoint
- **Auto-deploy**: Pushes to GitHub automatically trigger redeployments

## Available MCP Tools

### 1. `search_posts`

Search through Alignment Forum posts using natural language queries with semantic search.

**Parameters**:

- `query` (string, required): Natural language search query (e.g., "mesa-optimization risks")
- `limit` (integer, optional): Maximum results to return (default: 20, max: 100)
- `offset` (integer, optional): Results to skip for pagination (default: 0)

**Returns**: JSON object with matching posts and similarity scores

**Example usage in Claude**:

```
Search for posts about mesa-optimizers and inner alignment
Find articles discussing deceptive alignment
```

### 2. `list_recent_posts`

List recent Alignment Forum posts in chronological order (newest first).

**Parameters**:

- `limit` (integer, optional): Maximum results to return (default: 20, max: 100)
- `offset` (integer, optional): Results to skip for pagination (default: 0)

**Returns**: JSON object with posts array and pagination info

**Example usage in Claude**:

```
Show me the 10 most recent alignment forum posts
What are the latest posts on the alignment forum?
```

### 3. `fetch_article_content`

Fetch the full content of a specific Alignment Forum article.

**Parameters**:

- `post_id` (string, required): The post ID (`_id` field) or slug from the database
- `url` (string, optional): Direct URL to the post (used as fallback)

**Returns**: Complete article with HTML content, metadata, and statistics

**Example usage in Claude**:

```
Fetch the full article content for post ID abc123xyz456789ab
Get the complete text of the article with slug "risks-from-learned-optimization"
```

## Daily Updates

### GitHub Actions Workflow

The repository includes a GitHub Actions workflow that automatically updates the CSV file daily:

- **Schedule**: 3:47 AM UTC every day
- **Manual trigger**: Can be run manually from the Actions tab

### Setup for Automated Updates

1. **Go to your GitHub repository settings** → Secrets and variables → Actions

2. **Add a new secret**:

   - Name: `OPENROUTER_API_KEY`
   - Value: Your OpenRouter API key from https://openrouter.ai/

3. **Enable GitHub Actions**:
   - Go to the "Actions" tab
   - Enable workflows if prompted

The workflow will:

1. Fetch all posts from Alignment Forum
2. Generate summaries using OpenRouter (or use fallback descriptions)
3. Write to `data/alignment-forum-posts.csv`
4. Commit and push changes

## Development

### Project Structure

```
mcp-alignmentforum/
├── README.md                          # This file
├── pyproject.toml                     # Python project configuration
├── .gitignore                         # Git ignore rules
├── src/
│   └── mcp_alignmentforum/
│       ├── __init__.py               # Package initialization
│       └── server.py                 # MCP server with 3 tools
├── scripts/
│   └── update_posts.py               # Daily update script
├── data/
│   ├── .gitkeep                      # Track directory in git
│   └── alignment-forum-posts.csv     # Generated by GitHub Actions
└── .github/
    └── workflows/
        └── update-posts.yml          # Daily GitHub Actions workflow
```

### Running Locally

**Start the MCP server**:

```bash
python src/mcp_alignmentforum/server.py
```

The server will run on stdio and wait for MCP protocol messages.

**Run the update script**:

```bash
# Without OpenRouter (uses plaintext descriptions)
python scripts/update_posts.py

# With OpenRouter (generates AI summaries)
export OPENROUTER_API_KEY="your-key"
python scripts/update_posts.py
```

### Testing

You can test the GraphQL queries directly at:
https://www.alignmentforum.org/graphiql

### Code Quality

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Format code
black src/ scripts/

# Lint code
ruff check src/ scripts/

# Type check
mypy src/
```

## API Details

### Alignment Forum GraphQL API

- **Endpoint**: `https://www.alignmentforum.org/graphql`
- **GraphiQL Explorer**: `https://www.alignmentforum.org/graphiql`
- **Rate Limits**: Be respectful, add delays between requests
- **Documentation**: Based on LessWrong codebase

### OpenRouter API

- **Endpoint**: `https://openrouter.ai/api/v1/chat/completions`
- **Model Used**: `openai/gpt-3.5-turbo` (reliable and cost-effective)
- **Purpose**: Generate 2-3 sentence summaries of posts
- **Fallback**: Uses `plaintextDescription` if API fails or key not provided

## Troubleshooting

### MCP server not appearing in Claude Desktop

1. Check that the path in `claude_desktop_config.json` is correct
2. Ensure Python 3.10+ is installed: `python3 --version`
3. Verify dependencies are installed: `pip list | grep mcp`
4. Check Claude Desktop logs:
   - macOS: `~/Library/Logs/Claude/`
   - Look for error messages related to mcp-alignmentforum

### CSV file not found (404 error)

1. Make sure you've updated the `CSV_URL` in `server.py` with your GitHub username
2. Verify the CSV file exists at: `https://raw.githubusercontent.com/YOUR_USERNAME/mcp-alignmentforum/main/data/alignment-forum-posts.csv`
3. Run the update script to generate the initial CSV: `python scripts/update_posts.py`
4. Commit and push the CSV file to GitHub

### GitHub Actions not running

1. Go to repository Settings → Actions → General
2. Ensure "Allow all actions and reusable workflows" is selected
3. Check that the workflow file is in `.github/workflows/`
4. Manually trigger from Actions tab to test

### Import errors when running server

```bash
# Reinstall dependencies
pip install --upgrade mcp httpx 'gql[httpx]' pydantic
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- [Alignment Forum](https://www.alignmentforum.org/) for providing the content and API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [Anthropic](https://www.anthropic.com/) for Claude and Claude Desktop

## Support

For issues, questions, or suggestions, please open an issue on GitHub.