uscardforum/
├── src/uscardforum/
│   ├── __init__.py          # Package exports
│   ├── client.py            # Main client (composes APIs)
│   ├── server.py            # FastMCP server (MCP layer)
│   ├── server_core.py       # Server configuration
│   ├── models/              # Domain models (Pydantic)
│   │   ├── topics.py        # Topic, Post, TopicInfo, TopicSummary
│   │   ├── users.py         # UserSummary, UserAction, Badge, etc.
│   │   ├── search.py        # SearchResult, SearchPost, SearchTopic
│   │   ├── categories.py    # Category, CategoryMap
│   │   └── auth.py          # Session, Notification, Bookmark, etc.
│   ├── api/                 # API modules (backend)
│   │   ├── base.py          # Base API with HTTP methods
│   │   ├── topics.py        # Topic operations
│   │   ├── users.py         # User profile operations
│   │   ├── search.py        # Search operations
│   │   └── auth.py          # Authentication operations
│   ├── server_tools/        # MCP tool definitions
│   └── utils/               # HTTP and Cloudflare utilities
├── tests/                   # Integration tests
├── .github/workflows/       # CI/CD workflows
│   ├── ci.yml               # Tests, linting, type checking
│   └── deploy.yml           # Multi-platform deployment
├── Dockerfile               # Container build
├── docker-compose.yml       # Local development
├── fly.toml                 # Fly.io configuration
├── railway.toml             # Railway configuration
├── render.yaml              # Render blueprint
├── koyeb.yaml               # Koyeb configuration
├── digitalocean-app.yaml    # DigitalOcean App Platform
├── cloudbuild.yaml          # Google Cloud Build
├── heroku.yml               # Heroku manifest
├── app.json                 # Heroku button config
├── Procfile                 # Heroku process
└── pyproject.toml           # Python package config

# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum

# Install with UV
uv sync

# Run the server
uv run uscardforum

# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install
pip install -e .

# Run
uscardforum

# Start server with streamable HTTP transport
MCP_TRANSPORT=streamable-http MCP_PORT=8000 uv run uscardforum

# The MCP endpoint will be available at:
# http://localhost:8000/mcp

# Start server with authentication required
MCP_TRANSPORT=streamable-http NITAN_TOKEN=my-secret-token uv run uscardforum

# Clients must include Authorization header:
# Authorization: Bearer my-secret-token

# Using User API Key (when username/password are not set)
export NITAN_API_KEY="your_api_key_here"
export NITAN_API_CLIENT_ID="your_client_id_here"
uv run uscardforum

{
  "mcpServers": {
    "uscardforum": {
      "command": "uv",
      "args": ["--directory", "/path/to/uscardforum", "run", "uscardforum"],
      "env": {
        "NITAN_USERNAME": "your_forum_username",
        "NITAN_PASSWORD": "your_forum_password"
      }
    }
  }
}

{
  "mcpServers": {
    "uscardforum": {
      "command": "uv",
      "args": ["--directory", "/path/to/uscardforum", "run", "uscardforum"],
      "env": {
        "NITAN_API_KEY": "your_api_key",
        "NITAN_API_CLIENT_ID": "your_client_id"
      }
    }
  }
}

{
  "mcpServers": {
    "uscardforum": {
      "command": "uv",
      "args": ["--directory", "/path/to/uscardforum", "run", "uscardforum"],
      "env": {
        "NITAN_USERNAME": "your_forum_username",
        "NITAN_PASSWORD": "your_forum_password"
      }
    }
  }
}

{
  "mcpServers": {
    "uscardforum": {
      "command": "uv",
      "args": ["--directory", "/path/to/uscardforum", "run", "uscardforum"],
      "env": {
        "NITAN_API_KEY": "your_api_key",
        "NITAN_API_CLIENT_ID": "your_client_id"
      }
    }
  }
}

# Manual deployment
heroku login
heroku create your-app-name

# Set environment variables
heroku config:set NITAN_TOKEN=$(openssl rand -hex 32)
heroku config:set NITAN_USERNAME=your_username
heroku config:set NITAN_PASSWORD=your_password

# Deploy
git push heroku main
heroku ps:scale web=1

# Install Railway CLI
npm i -g @railway/cli

# Login and deploy
railway login
railway init
railway up

# Set environment variables
railway variables set MCP_TRANSPORT=streamable-http
railway variables set NITAN_TOKEN=$(openssl rand -hex 32)
railway variables set NITAN_USERNAME=your_username
railway variables set NITAN_PASSWORD=your_password

# Open dashboard
railway open

# render.yaml is included in the repository
# Just connect your repo and Render will auto-detect it

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Login and launch
fly auth login
fly launch --name uscardforum-mcp

# Set secrets
fly secrets set NITAN_TOKEN=$(openssl rand -hex 32)
fly secrets set NITAN_USERNAME=your_username
fly secrets set NITAN_PASSWORD=your_password

# Deploy
fly deploy

# Check status
fly status
fly logs

# Deploy to Cloud Run
gcloud run deploy uscardforum-mcp \
  --source . \
  --region us-west1 \
  --platform managed \
  --allow-unauthenticated \
  --port 8000 \
  --memory 512Mi \
  --set-env-vars "MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8000"

# Enable required APIs
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Deploy directly from source
gcloud run deploy uscardforum-mcp \
  --source . \
  --region us-west1 \
  --platform managed \
  --allow-unauthenticated \
  --port 8000 \
  --memory 512Mi \
  --set-env-vars "MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8000"

# Set secrets (create them first in Secret Manager)
gcloud run services update uscardforum-mcp \
  --set-secrets="NITAN_TOKEN=nitan-token:latest"

gcloud builds submit --config cloudbuild.yaml

# Install doctl CLI
brew install doctl  # or: snap install doctl

# Authenticate
doctl auth init

# Create app from spec
doctl apps create --spec digitalocean-app.yaml

# Or deploy via dashboard:
# 1. Go to https://cloud.digitalocean.com/apps
# 2. Create App → GitHub → Select repository
# 3. Configure environment variables

# Install Koyeb CLI
curl -fsSL https://raw.githubusercontent.com/koyeb/koyeb-cli/master/install.sh | sh

# Login and deploy
koyeb login
koyeb app create uscardforum-mcp \
  --docker-image ghcr.io/uscardforum/mcp-server:latest \
  --ports 8000:http \
  --env MCP_TRANSPORT=streamable-http \
  --env MCP_PORT=8000

# Set secrets
koyeb secrets create nitan-token --value your-secret-token
koyeb app update uscardforum-mcp --env NITAN_TOKEN=@nitan-token

# Pull from Docker Hub (recommended)
docker pull uscarddev/uscardforum-mcp:latest

# Run the container
docker run -d \
  -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e NITAN_TOKEN=your-secret-token \
  --name uscardforum-mcp \
  uscarddev/uscardforum-mcp:latest

# Or build locally
docker build -t uscardforum-mcp .
docker run -d \
  -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e NITAN_TOKEN=your-secret-token \
  --name uscardforum-mcp \
  uscardforum-mcp

# Or use Docker Compose
docker compose up -d

# View logs
docker compose logs -f

{
  "mcpServers": {
    "uscardforum": {
      "url": "https://your-app.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-nitan-token"
      }
    }
  }
}

# Set test credentials
export NITAN_USERNAME="your_test_username"
export NITAN_PASSWORD="your_test_password"

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=uscardforum --cov-report=term-missing

from uscardforum import TopicSummary, TopicInfo, Post

# TopicSummary - for list views
topic: TopicSummary
topic.id          # int: Topic ID
topic.title       # str: Topic title
topic.posts_count # int: Number of posts
topic.views       # int: View count
topic.like_count  # int: Total likes

# TopicInfo - detailed metadata
info: TopicInfo
info.post_count          # int: Total posts
info.highest_post_number # int: Last post number

# Post - individual post
post: Post
post.id           # int: Post ID
post.post_number  # int: Position in topic
post.username     # str: Author
post.cooked       # str: HTML content
post.like_count   # int: Likes

from uscardforum import UserSummary, UserAction, Badge

# UserSummary - profile overview
summary: UserSummary
summary.username  # str: Username
summary.stats     # UserStats: Activity statistics
summary.badges    # List[Badge]: Earned badges

# UserAction - activity entry
action: UserAction
action.topic_id   # int: Related topic
action.excerpt    # str: Content preview

from uscardforum import SearchResult, SearchPost, SearchTopic

# SearchResult - search response
result: SearchResult
result.posts   # List[SearchPost]: Matching posts
result.topics  # List[SearchTopic]: Matching topics
result.users   # List[SearchUser]: Matching users

from uscardforum import LoginResult, Session, Notification, Bookmark

# LoginResult - login response
login: LoginResult
login.success      # bool: Whether succeeded
login.requires_2fa # bool: 2FA needed

# Session - current session
session: Session
session.is_authenticated  # bool: Logged in
session.current_user      # CurrentUser: User info

from uscardforum import DiscourseClient

client = DiscourseClient()

# Browse hot topics
for topic in client.get_hot_topics():
    print(f"{topic.title} ({topic.posts_count} posts, {topic.views} views)")

# Get topic info and posts
info = client.get_topic_info(12345)
print(f"Topic has {info.post_count} posts")

posts = client.get_topic_posts(12345)
for post in posts:
    print(f"#{post.post_number} by {post.username}: {post.like_count} likes")

# Search
results = client.search("Chase Sapphire Reserve", order="latest")
for post in results.posts:
    print(f"[Topic {post.topic_id}] {post.blurb}")

# User profile
summary = client.get_user_summary("creditexpert")
print(f"{summary.username}: {summary.stats.post_count} posts")

# Login to forum
result = client.login("username", "password")
if result.success:
    print(f"Logged in as {result.username}")
elif result.requires_2fa:
    result = client.login("username", "password", second_factor_token="123456")

# Get notifications
notifications = client.get_notifications(only_unread=True)
for n in notifications:
    print(f"Notification {n.id}: {n.notification_type}")

# Bookmark a post
bookmark = client.bookmark_post(54321, name="Important info")

# Install dev dependencies
uv sync --group dev

# Run tests
NITAN_USERNAME="user" NITAN_PASSWORD="pass" uv run pytest

# Lint
uv run ruff check src/

# Type check
uv run mypy src/