Goagain

A REST API and MCP (Model Context Protocol) server for Flesh and Blood card game data.

Features

• REST API - Query cards, sets, keywords, and abilities with filtering and pagination
• MCP Server - Integrate Flesh and Blood card data into AI assistants (Claude, etc.)
• Format Legality - Check card legality across Blitz, Classic Constructed, Commoner, Living Legend, Silver Age, and UPF
• Full-Text Search - Search card abilities and effects
• Observability - OpenTelemetry traces, metrics, and logs for production deployments
• Docker Ready - Multi-platform container images for easy deployment

Hosted Service

Public instances are available at:

• REST API: https://api.goagain.dev
• MCP Server: https://mcp.goagain.dev

Quick Start

Run with Go

# Clone the repository
git clone --recursive https://github.com/oleiade/goagain.git
cd goagain

# Run the API server (default port 8080)
go run ./cmd/api

# Or run the MCP server (default port 8081)
go run ./cmd/mcp

Run with Docker

# API server
docker run -p 8080:8080 ghcr.io/oleiade/goagain-api

# MCP server (HTTP mode)
docker run -p 8081:8081 -e MCP_MODE=http ghcr.io/oleiade/goagain-mcp

REST API

Endpoints

Endpoint	Description
GET /	Landing page (HTML) or API info (JSON with Accept: application/json)
GET /health	Health check with data statistics
GET /docs	Interactive Swagger UI documentation
GET /openapi.yaml	OpenAPI 3.0 specification
GET /cards	List/search cards
GET /cards/{id}	Get card by unique ID or name
GET /cards/{id}/legality	Get card legality across all formats
GET /sets	List/search sets
GET /sets/{id}	Get set details with cards
GET /keywords	List all keywords
GET /keywords/{name}	Get keyword description
GET /abilities	List all abilities

Card Search Parameters

Parameter	Description
name	Filter by card name (partial match)
type	Filter by card type (e.g., Action, Attack, Equipment)
class	Filter by class (e.g., Warrior, Ninja, Wizard)
set	Filter by set code (e.g., WTR, ARC, MON)
pitch	Filter by pitch value (1, 2, or 3)
keyword	Filter by keyword (e.g., Go again, Dominate)
q	Full-text search in card abilities
legal_in	Filter by format legality (blitz, cc, commoner, ll, silver_age, upf)
limit	Results per page (default 50, max 100)
offset	Pagination offset

Examples

# Search for Ninja attack actions
curl "https://api.goagain.dev/cards?class=Ninja&type=Attack"

# Find cards with "draw" in their text
curl "https://api.goagain.dev/cards?q=draw"

# Get a specific card
curl "https://api.goagain.dev/cards/WTR001"

# Check format legality
curl "https://api.goagain.dev/cards/WTR001/legality"

# List all sets
curl "https://api.goagain.dev/sets"

MCP Server

The MCP server allows AI assistants to query Flesh and Blood card data. It supports both stdio (for local integrations) and HTTP transports.

Tools

Tool	Description
search_cards	Search cards by name, type, class, set, pitch, cost, power, defense, rarity, keyword, or format legality, with offset pagination
get_card	Get full details of a card by ID or name
list_sets	List all card sets
search_sets	Search sets by name or code
get_set	Get set details with optional card list
search_card_text	Full-text search in card abilities
get_format_legality	Check card legality across all formats
get_banned_list	List cards banned, suspended, restricted, or Living Legend in a format
draw_probability	Calculate exact hypergeometric odds of drawing specific cards
list_keywords	List all game keywords
get_keyword	Get keyword description
search_rules	Search the official Comprehensive Rules by keyword
get_rule	Get a specific rule by number, including its sub-rules

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

Using the hosted service:

{
  "mcpServers": {
    "fab-cards": {
      "url": "https://mcp.goagain.dev/mcp"
    }
  }
}

Using a local binary:

{
  "mcpServers": {
    "fab-cards": {
      "command": "/path/to/goagain-mcp"
    }
  }
}

Using local HTTP mode:

{
  "mcpServers": {
    "fab-cards": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

Configuration

All configuration is via environment variables. See .env.example for a complete template.

API Server

Variable	Default	Description
PORT	8080	API server port
CORS_ORIGINS	*	Comma-separated allowed origins
RATE_LIMIT_RPS	100	Rate limit (requests per second per IP)
TRUSTED_PROXIES		Comma-separated CIDR blocks for proxy header trust
API_BASE_URL	https://api.goagain.dev	Base URL shown in landing page and docs
MCP_BASE_URL	https://mcp.goagain.dev	MCP URL shown in landing page

MCP Server

Variable	Default	Description
MCP_MODE	stdio	MCP transport: stdio or http
MCP_PORT	8081	MCP HTTP server port

Observability

Variable	Default	Description
LOG_LEVEL	info	Log level: debug, info, warn, error
LOG_FORMAT	json	Log format: json or text
SERVICE_NAME	goagain-api / goagain-mcp	Service name for logs
METRICS_ENABLED	true	Enable OTel metrics collection

OpenTelemetry

Variable	Default	Description
OTEL_EXPORTER_OTLP_ENDPOINT	(none)	OTLP endpoint (e.g., localhost:4318). If unset, telemetry goes to stdout
OTEL_EXPORTER_OTLP_INSECURE	false	Disable TLS on OTLP export. Set true only for plaintext/loopback collectors (e.g. a local Alloy)
OTEL_SERVICE_NAME	goagain-api / goagain-mcp	Service name for traces, metrics, and logs
OTEL_SERVICE_VERSION	0.1.0	Service version reported in telemetry
OTEL_ENVIRONMENT	development	Deployment environment (e.g., production, staging)

Observability

Both servers include built-in OpenTelemetry observability for production deployments, providing distributed tracing, metrics, and structured logs.

OpenTelemetry Integration

By default, all telemetry is output to stdout (useful for local development). To send telemetry to an OTLP-compatible collector (e.g., Grafana Alloy, Jaeger, or any OTel Collector), set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable:

# Send telemetry to a local collector (applies to both API and MCP servers)
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318

# Optional: customize service metadata
export OTEL_SERVICE_NAME=goagain-api  # or goagain-mcp for MCP server
export OTEL_SERVICE_VERSION=1.0.0
export OTEL_ENVIRONMENT=production

Both the API server (cmd/api) and MCP server (cmd/mcp) use identical OTel configuration and export traces, metrics, and logs to the same endpoint.

Distributed Tracing

HTTP Requests (both API and MCP servers):

HTTP requests are automatically traced using otelhttp. Each request creates a span with:

• HTTP method, route, and status code
• Request/response sizes
• Timing information
• Trace context propagation (W3C TraceContext and Baggage)

MCP Tool Invocations (MCP server only):

Each MCP tool call creates a child span (mcp.tool.<name>) with:

• Tool name and execution duration
• Result count and error status
• Linked to parent HTTP span (in HTTP mode)

Metrics

Metrics are collected using the OTel Metrics API and exported via OTLP.

HTTP Metrics:

• http.server.request.total - Total HTTP requests
• http.server.request.duration - Request latency histogram (seconds)
• http.server.active_requests - Current in-flight requests
• http.server.response.size - Response size histogram (bytes)
• http.server.rate_limit.rejected - Rate limit rejections (API only)

MCP Tool Metrics:

• mcp.tool.invocations.total - Tool invocation count
• mcp.tool.duration - Tool execution latency (seconds)
• mcp.tool.result_count - Results returned per invocation
• mcp.tool.active - In-flight tool invocations

Application Metrics:

• goagain.data.cards - Total cards loaded
• goagain.data.sets - Total sets loaded
• goagain.data.keywords - Total keywords loaded
• goagain.data.abilities - Total abilities loaded
• goagain.data.index_entries - Index entries by index name

Structured Logging

Logs are output to stdout in structured JSON format and also sent to the OTel log pipeline:

{
  "time": "2025-01-25T14:30:00.123Z",
  "level": "INFO",
  "msg": "HTTP request completed",
  "service": "goagain-api",
  "request_id": "01HQXYZ123ABC",
  "method": "GET",
  "path": "/cards",
  "status": 200,
  "duration_ms": 12.5,
  "client_ip": "192.168.1.100"
}

Grafana Cloud Integration

For Grafana Cloud, configure Grafana Alloy to receive OTLP telemetry:

otelcol.receiver.otlp "default" {
  grpc { endpoint = "0.0.0.0:4317" }
  http { endpoint = "0.0.0.0:4318" }

  output {
    traces  = [otelcol.exporter.otlp.grafana.input]
    metrics = [otelcol.exporter.otlp.grafana.input]
    logs    = [otelcol.exporter.otlp.grafana.input]
  }
}

Then point the application to Alloy:

export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318

Development

Prerequisites

• Go 1.26+
• golangci-lint (for linting)
• k6 (for load testing, optional)

Commands

# Build
go build -v ./...

# Test
go test -race -v ./...

# Lint
golangci-lint run

# Run load tests (requires running API server)
k6 run tests/k6/api.js

Updating Card Data

Card data is sourced from an upstream submodule. To update:

./scripts/sync-data.sh

Updating the Comprehensive Rules

The rules text backing search_rules and get_rule is published by Legend Story Studios. To update it, and to print the version and date to record in internal/data/rules/README.md:

./scripts/sync-rules.sh

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (go test -race -v ./... && golangci-lint run)
5. Commit your changes using conventional commits
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Data Attribution

All card data is sourced from the flesh-and-blood-cards project maintained by The Fab Cube. This community-driven project provides comprehensive, machine-readable data for Flesh and Blood cards.

We are deeply grateful to the maintainers and contributors of flesh-and-blood-cards for their work in making this data available to the community.

Legal Disclaimer

Flesh and Blood is a trademark of Legend Story Studios (LSS). All card names, artwork, and game mechanics are the intellectual property of Legend Story Studios.

This project is not produced, endorsed, supported, or affiliated with Legend Story Studios. This is an unofficial, fan-made project created for educational and community purposes.

The card data provided by this API is derived from publicly available information and is intended to help players, developers, and content creators build tools and applications for the Flesh and Blood community.

All trademarks and copyrights belong to their respective owners. Use of Flesh and Blood card data should comply with Legend Story Studios' Community Guidelines and Intellectual Property Policy.

License

This project is open source. See LICENSE for details.