jimsantora/steam-librarian

Steam Librarian

Your Steam collection, curated by an AI-powered librarian. Natural language search, mood-based recommendations, and social insights that actually help you pick the perfect game.

Steam Librarian is your digital gaming archivist - an intelligent Model Context Protocol (MCP) server that transforms how you interact with your Steam library. Our core philosophy addresses a universal gamer problem: extensive libraries filled with unplayed gems, forgotten favorites, and impulse purchases create decision paralysis where we spend more time browsing than playing. Like a knowledgeable librarian who knows every book on the shelf, Steam Librarian analyzes your gaming patterns, respects your time, and serves as your personal curator.

This AI-powered assistant leverages MCP's advanced features including sampling for natural language understanding, elicitation for interactive parameter gathering, and completions for discoverable functionality. The system tracks your play history and preferences, helps you find games that match your current mood and available time, understands what your friends are playing, and can suggest the perfect game for any situation. Built with FastMCP and featuring HTTP streaming, smart caching, comprehensive testing, and production-ready architecture, it serves as both a practical gaming tool and a comprehensive example of creating an intelligent MCP server.

Features

AI-Powered Gaming Intelligence

• Smart Search with AI Sampling: Natural language queries like "chill puzzle games for tonight" interpreted by AI into structured filters
• Context-Aware Recommendations: Personalized suggestions using elicitation to gather context (mood, time, age, preferences)
• Intelligent Library Analytics: Deep pattern analysis with AI interpretation of your gaming habits and trends
• Interactive Parameter Discovery: MCP completions help you discover available options and query patterns
• Social Gaming Insights: Friend library comparisons and multiplayer game matching

Core Functionality

• Multi-User Support: Query multiple Steam users and seamlessly switch between libraries
• Game Details & Reviews: Comprehensive information including review statistics and ratings
• Recent Activity Tracking: Monitor what you and your friends have been playing
• User Profile Data: Access Steam levels, XP, account age, and profile information

Technical Excellence

• Advanced MCP Features: Full implementation of sampling, elicitation, and completions for intelligent user interaction
• Production-Ready Architecture: Built with FastMCP, HTTP streaming, and comprehensive error handling
• Smart Caching System: Intelligent caching with configurable TTL for optimal performance
• Comprehensive Testing: Full unit and integration test coverage with quality assurance
• Health Monitoring: Built-in health checks, metrics, and administration tools

Example Interactions (Click the dropdowns to see responses)

Prerequisites

• Python 3.8 or higher
• A Steam account with a public game library
• Steam API key (get one from https://steamcommunity.com/dev/apikey)
• Your Steam ID

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Fetch Your Steam Library Data

First, create a .env file with your Steam credentials:

# .env
STEAM_ID=your_steam_id_here
STEAM_API_KEY=your_steam_api_key_here

Then run the data fetcher:

python src/fetcher/steam_library_fetcher.py

This will create a SQLite database (steam_library.db) with all your game data and user profile information.

Optional: To also fetch friends data:

python src/fetcher/steam_library_fetcher.py --friends

3. Run the MCP Server

Start the production server:

python src/mcp_server/run_server.py

The server will start on http://0.0.0.0:8000/mcp with comprehensive health checks and monitoring.

4. Verify the Server is Running

The server will output logs indicating it's running on http://0.0.0.0:8000/mcp.

You can also check the health endpoint:

curl http://localhost:8000/health

Usage Examples

The AI-powered MCP server understands natural language and provides intelligent, contextual responses:

• AI Smart Search: "Show me chill puzzle games for tonight" → AI sampling interprets mood and filters games
• Context-Aware Recommendations: "I need family games" → Elicitation asks for age and preferences
• Interactive Discovery: Tab completion shows available contexts like "family", "quick_session", "mood_based"
• Deep Analytics: "Analyze my gaming patterns" → AI interprets data and provides insights about your habits
• Social Gaming: "Find multiplayer games my friends own" → Intelligent friend library analysis
• Mood-Based Suggestions: "Something relaxing after work" → AI maps sentiment to game recommendations

The server leverages MCP's advanced features (sampling, elicitation, completions) for truly intelligent gaming assistance.

Available Tools

The server provides 3 powerful AI-enhanced tools that showcase MCP's advanced capabilities:

smart_search - AI-Powered Unified Search

• AI Sampling: Natural language queries interpreted by AI into structured filters
• Intelligent Filtering: Multi-tier classification using genres, categories, and tags
• Smart Sorting: Multiple algorithms including relevance, playtime, ratings, and random discovery
• Query Understanding: Handles complex requests like "family-friendly co-op games for short sessions"

recommend_games - Context-Aware Recommendations with Elicitation

• Interactive Context Gathering: Uses elicitation to ask for missing parameters (age, time, preferences)
• Contextual Intelligence: Six specialized contexts (family, quick_session, similar_to, mood_based, unplayed_gems, abandoned)
• Play History Integration: Analyzes your gaming patterns for personalized suggestions
• Age-Appropriate Filtering: ESRB/PEGI rating system integration for family-safe recommendations

get_library_insights - Deep Analytics with AI Interpretation

• Pattern Analysis: AI interpretation of your gaming habits, preferences, and trends
• Comprehensive Analytics: Value analysis, genre distribution, social comparisons, achievement tracking
• Intelligent Insights: AI-generated observations about your gaming personality and behavior
• Trend Recognition: Time-based analysis of how your gaming preferences evolve

MCP Protocol Features

• Completions: Tab completion for parameters, contexts, and query patterns
• Resources: Rich data access through URI templates (library://games, library://genres, etc.)
• Prompts: Interactive examples showcasing all features with humor and practical scenarios

Legacy Utility Tools: get_all_users, get_user_info, get_game_details, get_game_reviews, get_recently_played

For detailed documentation on each tool's capabilities and parameters, see .

Data Source

The server uses a sophisticated relational SQLite database (steam_library.db) with normalized data structure:

• Games: Comprehensive game metadata including ratings, reviews, genres, developers, publishers
• User Profiles: Complete Steam user information, levels, XP, location data, account details
• User Games: Per-user playtime and ownership data with recent activity tracking
• Friends: Social relationships and friend networks for compatibility analysis
• Reviews: Detailed review statistics and sentiment analysis

The database is automatically created and managed by the fetcher script. For detailed schema information, see .

Troubleshooting

1. Server not connecting: Check that the server is running on the correct port
2. Database not found: Run python src/fetcher/steam_library_fetcher.py to create the SQLite database
3. Permission errors: Make sure Python has read/write access to the database file
4. No data returned: Ensure you've run the fetcher and the database contains your Steam data
5. Multiple users: Use get_all_users tool to see available users if queries ask for user selection

Technical Details

Architecture & Framework

• Advanced MCP Implementation: Full use of sampling, elicitation, and completions for intelligent user interaction
• FastMCP Integration: Built with official MCP Python SDK for HTTP streaming and Server-Sent Events
• Production-Ready: Comprehensive error handling, graceful shutdown, and signal management
• Smart Caching: Intelligent memory-based caching with configurable TTL and automatic invalidation
• Multi-User Context: Seamless user resolution with intelligent fallbacks

Database & Performance

• SQLAlchemy ORM: Efficient data modeling with proper relationships and indexing
• SQLite Database: Normalized relational structure for optimal query performance
• Connection Pooling: Configurable database pool management for scalability

Testing & Quality Assurance

• Comprehensive Test Suite: 52+ unit tests and integration tests with 100% pass rate
• Automated Quality Checks: Linting (ruff), formatting (black), and code quality validation
• CI/CD Ready: Make targets for development workflow and continuous integration
• Performance Testing: Load testing and optimization validation

Monitoring & Operations

• Health Monitoring: Built-in health checks, metrics collection, and component status
• Administration Tools: Monitoring script, configuration validation, and system diagnostics
• RESTful Endpoints: Health checks (/health), detailed status (/health/detailed), metrics (/metrics)

For detailed technical documentation, see .

Project Structure

steam-librarian/
├── src/                           # Source code
│   ├── fetcher/                  # Steam library data fetcher service
│   │   └── steam_library_fetcher.py
│   ├── mcp_server/               # Advanced MCP server with AI features
│   │   ├── server.py            # Main FastMCP server with health endpoints
│   │   ├── config.py            # Configuration management system
│   │   ├── run_server.py        # Production startup script
│   │   ├── tools.py             # 3 AI-powered MCP tools (consolidated)
│   │   ├── resources.py         # MCP resources (consolidated)
│   │   ├── prompts.py           # Interactive MCP prompts (consolidated)
│   │   └── completions.py       # Database-driven completions
│   └── shared/                   # Shared database and utilities
│       ├── database.py          # SQLAlchemy models and DB utilities
│       └── README.md            # Database schema documentation
├── tests/                        # Comprehensive test suite
│   ├── test_mcp_server.py       # Unit tests (52 test cases)
│   └── test_integration.py      # Integration tests with server startup
├── deploy/                       # Deployment configurations
│   ├── README.md                # Comprehensive deployment guide
│   ├── docker/                  # Docker configurations and compose files
│   └── helm/                    # Kubernetes Helm charts with values
├── Makefile                      # Development commands and testing
├── requirements.txt              # Python dependencies
└── README.md                     # This file

Service Architecture

• Fetcher Service: Runs as a CronJob in Kubernetes, fetches Steam data via API
• MCP Server: Runs as a Deployment, provides MCP interface to Steam data
• Shared Storage: SQLite database on persistent volume shared between services

Deployment Options

Steam Librarian supports multiple deployment options for different environments and use cases. For comprehensive deployment instructions, configuration options, and troubleshooting, see the .

Quick Start Options

Local Development

# Run production server with full monitoring
python src/mcp_server/run_server.py

# Development mode with debug logging
DEBUG=true LOG_LEVEL=DEBUG python src/mcp_server/run_server.py

Docker (Recommended)

# Build and run with Docker Compose
make build-docker
make run-docker

# Check health and endpoints
curl http://localhost:8000/health
curl http://localhost:8000/metrics

Kubernetes with Helm

# Quick install with Helm
helm install steam-librarian deploy/helm/steam-librarian -f values-override.yaml

For detailed instructions including:

• Complete Docker Compose setup with environment configuration
• Kubernetes deployment with custom values and scaling options
• Production deployment best practices
• Health monitoring and troubleshooting
• Manual data fetching and maintenance

👉 See the complete

Using the MCP Server

This MCP server uses the Model Context Protocol, which requires an MCP client to interact with it. The server exposes tools that can be called by MCP clients such as:

• Claude Desktop (with appropriate configuration)
• MCP-compatible AI assistants
• Custom MCP clients using the MCP SDK

The server runs on port 8000 by default with the following endpoints:

• http://0.0.0.0:8000/mcp - MCP protocol endpoint (HTTP transport with SSE)
• http://0.0.0.0:8000/health - Health check endpoint for monitoring

Testing & Quality Assurance

The project includes comprehensive testing capabilities:

# Run basic import tests (fastest)
make test

# Run unit tests (52 test cases with detailed output)
make test-unit

# Run integration tests with server startup
make test-integration

# Run all tests (unit + integration)
make test-full

# Run complete code quality checks + all tests
make check-full

Available MCP Tools

The server exposes these AI-enhanced tools through the MCP protocol:

Core AI-Powered Tools:

• smart_search - AI sampling for natural language query interpretation and unified search
• recommend_games - Context-aware recommendations with elicitation for parameter gathering
• get_library_insights - Deep analytics with AI interpretation of gaming patterns

MCP Protocol Features:

• Sampling: AI interpretation of natural language queries into structured data
• Elicitation: Interactive parameter gathering for missing or ambiguous inputs
• Completions: Tab completion for parameters, contexts, and query patterns
• Resources: Rich data access through URI templates (library://games, library://users, etc.)
• Prompts: Interactive examples showcasing all features with engaging scenarios

Legacy Utility Tools:

• get_all_users - List all Steam users in the database
• get_user_info - Get comprehensive user profile information
• get_game_details - Get detailed information about specific games
• get_game_reviews - Get review statistics and ratings
• get_recently_played - Get recently played games with activity tracking

For detailed tool documentation and examples, see .