mcp-lightcast

Name	mcp-lightcast JSON
Version	0.2.1 JSON
	download
home_page	None
Summary	MCP server for Lightcast API integration using FastMCP
upload_time	2025-08-22 05:24:34
maintainer	Lawrence Wu
docs_url	None
author	Lawrence Wu
requires_python	>=3.12
license	MIT
keywords	api fastmcp job-titles lightcast mcp skills
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # MCP Lightcast Server

[![PyPI Version](https://img.shields.io/pypi/v/mcp-lightcast)](https://pypi.org/project/mcp-lightcast/)
[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![CI/CD Pipeline](https://github.com/lawwu/mcp-lightcast/workflows/Release/badge.svg)](https://github.com/lawwu/mcp-lightcast/actions)

A production-ready Model Context Protocol (MCP) server that provides seamless integration with Lightcast APIs for job titles, skills analysis, and career data. Built with FastMCP and modern Python development practices.

**🎯 Current Status: v0.2.1**

## 🚀 Features

### ✅ **Working APIs & Endpoints**

#### **🎯 Skills API (9/9 endpoints)** - Version 9.33, 41,139 skills
- ✅ **Skills Search** - Search with filters (type, category, subcategory)
- ✅ **Individual Skill Retrieval** - Get detailed skill information by ID
- ✅ **Skills Extraction from Text** - Extract skills from job descriptions with confidence scores
- ✅ **Bulk Skills Retrieval** - Efficient batch processing of multiple skills
- ✅ **Related Skills** - Find skills related to a specific skill (POST endpoint working)
- ✅ **Similar Skills** - Find similar skills via Similarity API
- ✅ **Skill Types** - Get all available skill types
- ✅ **Version Metadata** - Complete API version and statistics information
- ✅ **Skills Metadata** - General skills taxonomy information

#### **🏷️ Titles API (8/8 endpoints)** - Version 5.47, 73,993 titles
- ✅ **Job Title Search** - Search Lightcast's comprehensive job title database
- ✅ **Individual Title Retrieval** - Get detailed title information by ID
- ✅ **Bulk Title Retrieval** - Efficient batch processing of multiple titles
- ✅ **Title Normalization** - Normalize raw job titles
- ✅ **Title Hierarchy** - Get hierarchical structure for titles
- ✅ **Version Metadata** - Complete API version and statistics information
- ✅ **General Metadata** - Latest version and attribution information
- ✅ **Full Metadata** - Comprehensive taxonomy information

#### **🔄 Classification API (5/5 endpoints)** - Version 2025.8
- ✅ **Skills Extraction** - Extract skills from text using classification models
- ✅ **Available Versions** - Get all available API versions
- ✅ **Version Metadata** - Detailed version information
- ✅ **Skill Normalization** - Normalize skill text via extraction
- ✅ **Title Normalization** - Normalize title text with fallback

#### **🔗 Similarity API (7/7 endpoints)** - Premium Features
- ✅ **Available Models** - Get all similarity models
- ✅ **API Metadata** - Similarity API capabilities
- ✅ **Occupation Skills** - Skills associated with occupations
- ✅ **Similar Occupations** - Find similar occupations
- ✅ **Similar Skills** - Find similar skills
- ✅ **SOC Model** - Direct SOC similarity queries
- ✅ **Skill Model** - Direct skill similarity queries

#### **📊 Occupation Benchmark API (6/6 endpoints)** - Premium Features
- ✅ **API Metadata** - Benchmark API capabilities
- ✅ **Available Areas** - Geographic areas available
- ✅ **Available Metrics** - All available benchmark metrics
- ✅ **Benchmark Data** - Salary and employment data
- ✅ **SOC Dimension** - SOC code dimension data
- ✅ **LOT Dimension** - LOT occupation dimension data

#### **🛤️ Career Pathways API (3/3 endpoints)** - Premium Features
- ✅ **API Metadata** - Career pathways capabilities
- ✅ **Available Dimensions** - Pathway analysis dimensions
- ✅ **Pathway Analysis** - Career transition analysis

#### **💼 Job Postings API (3/3 endpoints)** - Premium Features
- ✅ **Available Facets** - Job posting search facets
- ✅ **Postings Summary** - Job posting trends and statistics
- ✅ **Top Skills** - Most in-demand skills from job postings

#### **🔄 Workflow Integration (2/2 endpoints)** - Custom Workflows
- ✅ **Title → Skills Workflow** - Complete title normalization and skills extraction
- ✅ **Simple Title Skills** - Streamlined title-to-skills pipeline

### 🔧 **Core Functionality
- **🎯 Skills Extraction from Text** - High accuracy skill identification from job descriptions
- **📊 Search & Discovery** - Fast, filtered search across skills, titles, and job postings
- **⚡ Bulk Operations** - Efficient processing of multiple items in single requests
- **🔄 Version Management** - Uses "latest" keyword with backward compatibility
- **🔐 OAuth2 Authentication** - Secure authentication with dynamic scope switching
- **🔗 Related & Similar Skills** - Find skills relationships via multiple APIs
- **💼 Job Market Data** - Real-time job posting analysis and trends
- **📊 Benchmarks & Analytics** - Salary and employment data access
- **🛤️ Career Pathways** - Career transition analysis and recommendations

### 🛠️ **MCP Tools Available (23 core tools across 7 categories)**

#### **Skills Tools (7 tools)**
API Docs: https://docs.lightcast.dev/apis/skills

- `bulk_retrieve_skills` - Efficient bulk skill retrieval
- `extract_skills_from_text` - Extract skills with custom confidence threshold
- `find_similar_skills` - Find similar skills via Similarity API
- `get_skill_details` - Get detailed skill information by ID
- `get_skills_metadata` - General skills taxonomy metadata
- `get_related_skills` - Find skills related to a specific skill (now working with POST endpoint)
- `search_skills` - Search skills with advanced filters (type, category, subcategory)

#### **Titles Tools (4 tools)**
API Docs: https://docs.lightcast.dev/apis/titles

- `bulk_retrieve_titles` - Efficient bulk title retrieval
- `get_job_title_details` - Get detailed title information by ID
- `normalize_job_title` - Normalize raw job titles
- `search_job_titles` - Search job titles in Lightcast database

#### **Job Postings Tools (3 tools)**
API Docs: https://docs.lightcast.dev/apis/job-postings

- `get_job_posting_details` - Get detailed job posting information
- `get_posting_statistics` - Job posting trends and analytics
- `search_job_postings` - Search real-time job market data

#### **Classification Tools (1 tool)**
API Docs: https://docs.lightcast.dev/apis/classification

- `get_classification_metadata` - Classification API capabilities and metadata

#### **Occupation Benchmark Tools (2 tools)**
API Docs: https://docs.lightcast.dev/apis/occupation-benchmark

- `get_benchmark_metadata` - Benchmark API capabilities and metadata
- `get_occupation_benchmark` - Salary and employment benchmarks by occupation

#### **Similarity Tools (3 tools)**
API Docs: https://docs.lightcast.dev/apis/similarity

- `get_similarity_metadata` - Similarity API capabilities and metadata
- `get_pathways_metadata` - Career pathways API capabilities and metadata


#### **Unified Workflows (4 tools)**
- `analyze_job_posting_skills` - Comprehensive job posting analysis
- `normalize_title_and_get_skills` - Complete title→skills workflow
- `normalize_title_and_extract_skills` - Alternative classification-based extraction


## 🛠️ Installation

### Prerequisites

- Python 3.12+ (required for uv-dynamic-versioning)
- [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
- Lightcast API credentials (Client ID and Secret with `emsi_open` scope). You can request free API access [here](https://lightcast.io/open-skills/access) which will give you access to the skills and titles taxonomies (subset of only the Skills and Titles APIs).

### 🚀 Quick Start with uvx (Recommended)

```bash
# Install and run directly from PyPI (no installation required)
uvx --from mcp-lightcast mcp-lightcast --help

# Run with environment variables
LIGHTCAST_CLIENT_ID=your_id LIGHTCAST_CLIENT_SECRET=your_secret \
uvx --from mcp-lightcast mcp-lightcast

# Use stdio transport for Claude Desktop
LIGHTCAST_CLIENT_ID=your_id LIGHTCAST_CLIENT_SECRET=your_secret \
uvx --from mcp-lightcast mcp-lightcast --transport stdio
```

### 📦 Install from PyPI

```bash
# Install globally
pip install mcp-lightcast

# Or with uv
uv tool install mcp-lightcast

# Run the server
mcp-lightcast --help
```

### 🔧 Development Installation

```bash
# 1. Clone the repository
git clone https://github.com/lawwu/mcp-lightcast.git
cd mcp-lightcast

# 2. Set up development environment 
make setup

# 3. Configure your API credentials
# Edit .env with your Lightcast API credentials

# 4. Validate configuration
make validate-config

# 5. Run the server
make run
```

### 🐳 Docker Installation

```bash
# Pull the latest image (when available)
docker pull ghcr.io/lawwu/mcp-lightcast:latest

# Run with environment variables
docker run --rm -it \
  -e LIGHTCAST_CLIENT_ID=your_id \
  -e LIGHTCAST_CLIENT_SECRET=your_secret \
  ghcr.io/lawwu/mcp-lightcast:latest

# Or with environment file
docker run --rm -it --env-file .env ghcr.io/lawwu/mcp-lightcast:latest
```

## ⚙️ Configuration

### Environment Variables

Create a `.env` file with your Lightcast API credentials:

```bash
# Required - Lightcast API Configuration
LIGHTCAST_CLIENT_ID=your_client_id_here
LIGHTCAST_CLIENT_SECRET=your_client_secret_here

# Optional - API Configuration (with defaults)
LIGHTCAST_BASE_URL=https://api.lightcast.io
LIGHTCAST_OAUTH_URL=https://auth.emsicloud.com/connect/token
LIGHTCAST_OAUTH_SCOPE=emsi_open
LIGHTCAST_RATE_LIMIT=1000

# Optional - MCP Server Configuration
MCP_SERVER_NAME=lightcast-mcp-server
LOG_LEVEL=INFO
MASK_ERROR_DETAILS=true
```

### Lightcast API Access

To use this server, you need:

1. 📝 A [Lightcast API account](https://lightcast.io/open-skills/access)
2. 🔑 Client ID and Client Secret for OAuth2 authentication
3. 🎯 Access to the following Lightcast APIs:
   - Titles API - Job title search and normalization
   - Skills API - Skills search and categorization
   - Classification API - Occupation code mapping
   - Similarity API - Skills and occupation relationships


## 🎯 Usage

### Command Line Interface

The server includes a comprehensive CLI with multiple options:

```bash
# Basic usage (uses streamable-http on port 3000 by default)
mcp-lightcast

# Use stdio transport (for Claude Desktop integration)
mcp-lightcast --transport stdio

# Use streamable-http transport with custom port
mcp-lightcast --transport streamable-http --port 8080

# With custom log level
mcp-lightcast --log-level DEBUG

# Validate configuration without starting server
mcp-lightcast --validate-config

# Use custom environment file
mcp-lightcast --env-file /path/to/custom.env

# Quiet mode (no logging)
mcp-lightcast --quiet

# Show help
mcp-lightcast --help
```

### Development Commands

Using the included Makefile for easy development:

```bash
# Quick development setup and run
make dev

# Run with debug logging
make dev-server

# Run all quality checks
make check

# Run tests with coverage
make test-coverage

# Show Claude Desktop configuration
make claude-config
```

### Claude Desktop Integration

#### Using uv (Recommended)

```json
{
  "mcpServers": {
    "lightcast": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-lightcast",
        "mcp-lightcast"
      ],
      "env": {
        "LIGHTCAST_CLIENT_ID": "your_client_id",
        "LIGHTCAST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

#### Using Docker

```json
{
  "mcpServers": {
    "lightcast": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "LIGHTCAST_CLIENT_ID",
        "-e", "LIGHTCAST_CLIENT_SECRET",
        "ghcr.io/lawwu/mcp-lightcast:latest"
      ],
      "env": {
        "LIGHTCAST_CLIENT_ID": "your_client_id",
        "LIGHTCAST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

#### Using uvx (Isolated)

```json
{
  "mcpServers": {
    "lightcast": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-lightcast",
        "mcp-lightcast"
      ],
      "env": {
        "LIGHTCAST_CLIENT_ID": "your_client_id",
        "LIGHTCAST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### 🔧 Detailed Tool Usage Examples

#### **🎯 Skills Tools**

**search_skills** - Search skills with advanced filters
```python
skills = await search_skills(
    query="python programming",
    limit=10,
    skill_type="Hard Skill",  # Optional: filter by skill type
    category="Information Technology",  # Optional: filter by category
    version="latest"  # Uses latest API version
)
```

**extract_skills_from_text** - Extract skills from job descriptions
```python
# Extract skills with custom confidence threshold
skills = await extract_skills_from_text(
    text="Looking for Python developer with React and database experience...",
    confidence_threshold=0.7,
    version="latest"
)
```

**extract_skills_simple** - Extract skills with default settings
```python
# Quick skills extraction with default confidence (0.5)
skills = await extract_skills_simple(
    text="We need Java developers with Spring Boot experience",
    version="latest"
)
```

**bulk_retrieve_skills** - Efficient bulk skill retrieval
```python
# Get multiple skills in one request
skills = await bulk_retrieve_skills(
    skill_ids=["KS125LS6N7WP4S6SFTCK", "KS440C66FGP5WGWYMP0F"],
    version="latest"
)
```

#### **🏷️ Titles Tools**

**search_job_titles** - Search job titles
```python
titles = await search_job_titles(
    query="software engineer",
    limit=10,
    version="latest"
)
```

**get_job_title_details** - Get detailed title information
```python
title = await get_job_title_details(
    title_id="ET6850661D6AE5FA86",
    version="latest"
)
```

**bulk_retrieve_titles** - Efficient bulk title retrieval
```python
titles = await bulk_retrieve_titles(
    title_ids=["ET6850661D6AE5FA86", "ETBF8AE9187B3810C5"],
    version="latest"
)
```

#### **📊 Metadata Tools**

**get_skills_version_metadata** - API version information
```python
metadata = await get_skills_version_metadata(version="latest")
# Returns: version, skill_count, language_support, skill_types, etc.
```

**get_titles_version_metadata** - API version information  
```python
metadata = await get_titles_version_metadata(version="latest")
# Returns: version, title_count, removed_title_count, fields
```

#### **⚠️ Limited Availability Tools**
Some tools require premium authentication scopes or have endpoint limitations:

**normalize_job_title** - ❌ Requires premium scope
```python
# Currently returns 401 Unauthorized with emsi_open scope
result = await normalize_job_title("sr software dev")
```

**analyze_job_posting_skills** - ✅ Working via skills extraction
```python
# Uses skills extraction instead of normalization
result = await analyze_job_posting_skills(
    job_title="Software Engineer",
    job_description="Full job description text...",
    extract_from_description=True  # Uses working skills extraction
)
```

### 🎯 Example Workflows

#### **1. Extract Skills from Job Description**

```python
# Analyze a job posting to extract relevant skills
job_description = """
We're looking for a Senior Software Engineer with expertise in Python, 
React, and cloud technologies. Experience with Docker, Kubernetes, 
and AWS is required. Strong communication skills and team collaboration 
abilities are essential.
"""

# Extract skills with high confidence
skills = await extract_skills_from_text(
    text=job_description,
    confidence_threshold=0.8,
    version="latest"
)

print(f"High-confidence skills found: {len(skills)}")
for skill in skills:
    print(f"- {skill['name']} (confidence: {skill['confidence']:.2f})")
```

#### **2. Compare Skills Across Job Titles**

```python
# Search and compare skills requirements for different roles
titles = ["Data Scientist", "Machine Learning Engineer", "Software Engineer"]
title_skills = {}

for title in titles:
    # Search for the title
    title_results = await search_job_titles(query=title, limit=1)
    if title_results:
        title_id = title_results[0]['id']
        
        # Get detailed title information  
        title_details = await get_job_title_details(title_id)
        title_skills[title] = title_details
        
print("Job title comparison completed")
```

#### **3. Bulk Skills Analysis**

```python
# Efficiently analyze multiple skills at once
skill_names = ["Python", "JavaScript", "Machine Learning", "Docker"]

# First search for skill IDs
skill_ids = []
for name in skill_names:
    results = await search_skills(query=name, limit=1)
    if results:
        skill_ids.append(results[0]['id'])

# Get detailed information for all skills in one request
if skill_ids:
    detailed_skills = await bulk_retrieve_skills(skill_ids)
    
    for skill in detailed_skills:
        print(f"Skill: {skill['name']}")
        print(f"Type: {skill.get('type', {}).get('name', 'Unknown')}")
        print(f"Category: {skill.get('category', 'Unknown')}")
        print("---")
```

#### **4. API Version and Statistics**

```python
# Get comprehensive API information
skills_meta = await get_skills_version_metadata()
titles_meta = await get_titles_version_metadata()

print(f"Skills API v{skills_meta['version']}: {skills_meta['skill_count']:,} skills")
print(f"Languages: {', '.join(skills_meta['language_support'])}")
print(f"Skill types: {len(skills_meta['skill_types'])}")

print(f"Titles API v{titles_meta['version']}: {titles_meta['title_count']:,} titles")
```

## 🧪 Development

### Prerequisites

- Python 3.12+ (required)
- [uv](https://docs.astral.sh/uv/) package manager
- Docker (for containerized development)
- Make (for development commands)

### Development Setup

```bash
# Clone and setup
git clone https://github.com/lawwu/mcp-lightcast.git
cd mcp-lightcast

# Quick setup (installs dependencies, creates .env)
make setup

# Install development dependencies only  
make install-dev

# Run development server with debug logging
make dev-server
```

### Project Structure

```
mcp-lightcast/
├── 📁 src/mcp_lightcast/           # Main package
│   ├── __init__.py                 # CLI entry point with Click
│   ├── __main__.py                 # Module execution entry
│   ├── server.py                   # FastMCP server instance
│   ├── 📁 auth/                    # Authentication modules
│   │   ├── __init__.py
│   │   └── oauth.py               # OAuth2 implementation
│   ├── 📁 apis/                    # API client modules  
│   │   ├── __init__.py
│   │   ├── base.py                # Base client with error handling
│   │   ├── titles.py              # Titles API client
│   │   ├── skills.py              # Skills API client
│   │   ├── classification.py      # Classification API client
│   │   └── similarity.py          # Similarity API client
│   ├── 📁 tools/                   # MCP tools registration
│   │   ├── __init__.py
│   │   ├── titles_tools.py        # Title-related MCP tools
│   │   ├── skills_tools.py        # Skills-related MCP tools
│   │   ├── workflow_tools.py      # Combined workflow tools
│   │   └── normalize_title_get_skills.py  # Core workflow logic
│   └── 📁 utils/                   # Utility functions
│       └── __init__.py
├── 📁 tests/                       # Test suite
│   ├── 📁 unit/                    # Unit tests
│   ├── 📁 integration/             # Integration tests
│   └── conftest.py                # Pytest fixtures
├── 📁 config/                      # Configuration management
│   └── settings.py                # Pydantic settings
├── 📁 .github/workflows/           # CI/CD pipelines
│   └── ci.yml                     # GitHub Actions workflow
├── 🐳 Dockerfile                   # Production container
├── 🐳 Dockerfile.dev               # Development container  
├── 🐳 docker-compose.yml           # Multi-service setup
├── 📋 Makefile                     # Development commands
├── 📦 pyproject.toml               # Project metadata & dependencies
├── 🔒 uv.lock                      # Dependency lock file
└── 📖 README.md                    # This file
```

### Development Workflow

#### Code Quality & Testing

```bash
# Run all quality checks (lint + type-check + test)
make check

# Individual quality checks
make lint           # Ruff linting
make type-check     # MyPy type checking  
make format         # Black + Ruff formatting

# Testing options
make test           # Run all tests
make test-coverage  # Tests with coverage report
make test-basic     # Basic functionality test
```

#### Docker Development

```bash
# Build Docker images
make docker-build       # Production image
make docker-build-dev   # Development image

# Run with Docker
make docker-run         # Run production container
make docker-dev         # Run development container

# Test Docker configuration
make docker-test        # Validate container setup
```

#### uv Package Management

```bash
# Dependency management
make uv-lock           # Generate lockfile
make uv-sync           # Sync from lockfile
make uv-update         # Update all dependencies

# Add dependencies
make uv-add PACKAGE=requests
make uv-add-dev PACKAGE=pytest-mock
```

## API Reference

### Rate Limits

- Default: 1000 requests per hour per API key
- Rate limit headers are included in responses
- Rate limit errors (429) are handled gracefully

### Error Handling

- Authentication errors are automatically retried
- Rate limits include reset time information
- API errors include detailed status codes and messages
- Network errors are handled with appropriate timeouts

### API Version Flexibility

The MCP server provides flexible version management:

- **Default**: `"latest"` - Always uses the newest available API version
- **Backward Compatible**: Users can specify any previous version (e.g., `"5.47"`, `"9.33"`)
- **Future-Proof**: Automatically gets new API features when Lightcast releases updates

**Examples:**
```python
# Use latest version (default)
search_job_titles("software engineer")

# Use specific version for consistency
search_job_titles("software engineer", version="5.47")

# Use older version if needed
search_skills("python", version="9.32")
```

**Current API Versions:**
- Skills API: `9.33` with 41,139 skills (English, Spanish, French support)
- Titles API: `5.47` with 73,993 titles
- Both APIs use `"latest"` keyword for automatic version management

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 📚 Documentation & Support

### **API Documentation**
- [Lightcast API Documentation](https://docs.lightcast.dev/) - Official Lightcast API reference
- [FastMCP Documentation](https://gofastmcp.com/) - FastMCP framework documentation  
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

### **Project Resources**
- [PyPI Package](https://pypi.org/project/mcp-lightcast/) - Official Python package
- [GitHub Repository](https://github.com/lawwu/mcp-lightcast) - Source code and issues
- [GitHub Releases](https://github.com/lawwu/mcp-lightcast/releases) - Version history and changelog

### **Getting Help**
- **Issues**: [GitHub Issues](https://github.com/lawwu/mcp-lightcast/issues) for bugs and feature requests
- **Discussions**: [GitHub Discussions](https://github.com/lawwu/mcp-lightcast/discussions) for questions and community support
- **Lightcast Support**: [Contact Lightcast](https://docs.lightcast.dev/contact) for API access and credentials

### **Current Status**
- **Version**: 0.2.0 (Production Ready)
- **API Coverage**: 43/43 endpoints (100%)
- **MCP Tools**: 23 core tools (streamlined)
- **Premium Features**: All working with user credentials
- **Python**: 3.12+ required
- **License**: MIT
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mcp-lightcast",
    "maintainer": "Lawrence Wu",
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": null,
    "keywords": "api, fastmcp, job-titles, lightcast, mcp, skills",
    "author": "Lawrence Wu",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/28/5b/5607afbf65e06331f581e326d060d6966ef9490a30a1c3b5f77b9fd202f2/mcp_lightcast-0.2.1.tar.gz",
    "platform": null,
    "description": "# MCP Lightcast Server\n\n[![PyPI Version](https://img.shields.io/pypi/v/mcp-lightcast)](https://pypi.org/project/mcp-lightcast/)\n[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![CI/CD Pipeline](https://github.com/lawwu/mcp-lightcast/workflows/Release/badge.svg)](https://github.com/lawwu/mcp-lightcast/actions)\n\nA production-ready Model Context Protocol (MCP) server that provides seamless integration with Lightcast APIs for job titles, skills analysis, and career data. Built with FastMCP and modern Python development practices.\n\n**\ud83c\udfaf Current Status: v0.2.1**\n\n## \ud83d\ude80 Features\n\n### \u2705 **Working APIs & Endpoints**\n\n#### **\ud83c\udfaf Skills API (9/9 endpoints)** - Version 9.33, 41,139 skills\n- \u2705 **Skills Search** - Search with filters (type, category, subcategory)\n- \u2705 **Individual Skill Retrieval** - Get detailed skill information by ID\n- \u2705 **Skills Extraction from Text** - Extract skills from job descriptions with confidence scores\n- \u2705 **Bulk Skills Retrieval** - Efficient batch processing of multiple skills\n- \u2705 **Related Skills** - Find skills related to a specific skill (POST endpoint working)\n- \u2705 **Similar Skills** - Find similar skills via Similarity API\n- \u2705 **Skill Types** - Get all available skill types\n- \u2705 **Version Metadata** - Complete API version and statistics information\n- \u2705 **Skills Metadata** - General skills taxonomy information\n\n#### **\ud83c\udff7\ufe0f Titles API (8/8 endpoints)** - Version 5.47, 73,993 titles\n- \u2705 **Job Title Search** - Search Lightcast's comprehensive job title database\n- \u2705 **Individual Title Retrieval** - Get detailed title information by ID\n- \u2705 **Bulk Title Retrieval** - Efficient batch processing of multiple titles\n- \u2705 **Title Normalization** - Normalize raw job titles\n- \u2705 **Title Hierarchy** - Get hierarchical structure for titles\n- \u2705 **Version Metadata** - Complete API version and statistics information\n- \u2705 **General Metadata** - Latest version and attribution information\n- \u2705 **Full Metadata** - Comprehensive taxonomy information\n\n#### **\ud83d\udd04 Classification API (5/5 endpoints)** - Version 2025.8\n- \u2705 **Skills Extraction** - Extract skills from text using classification models\n- \u2705 **Available Versions** - Get all available API versions\n- \u2705 **Version Metadata** - Detailed version information\n- \u2705 **Skill Normalization** - Normalize skill text via extraction\n- \u2705 **Title Normalization** - Normalize title text with fallback\n\n#### **\ud83d\udd17 Similarity API (7/7 endpoints)** - Premium Features\n- \u2705 **Available Models** - Get all similarity models\n- \u2705 **API Metadata** - Similarity API capabilities\n- \u2705 **Occupation Skills** - Skills associated with occupations\n- \u2705 **Similar Occupations** - Find similar occupations\n- \u2705 **Similar Skills** - Find similar skills\n- \u2705 **SOC Model** - Direct SOC similarity queries\n- \u2705 **Skill Model** - Direct skill similarity queries\n\n#### **\ud83d\udcca Occupation Benchmark API (6/6 endpoints)** - Premium Features\n- \u2705 **API Metadata** - Benchmark API capabilities\n- \u2705 **Available Areas** - Geographic areas available\n- \u2705 **Available Metrics** - All available benchmark metrics\n- \u2705 **Benchmark Data** - Salary and employment data\n- \u2705 **SOC Dimension** - SOC code dimension data\n- \u2705 **LOT Dimension** - LOT occupation dimension data\n\n#### **\ud83d\udee4\ufe0f Career Pathways API (3/3 endpoints)** - Premium Features\n- \u2705 **API Metadata** - Career pathways capabilities\n- \u2705 **Available Dimensions** - Pathway analysis dimensions\n- \u2705 **Pathway Analysis** - Career transition analysis\n\n#### **\ud83d\udcbc Job Postings API (3/3 endpoints)** - Premium Features\n- \u2705 **Available Facets** - Job posting search facets\n- \u2705 **Postings Summary** - Job posting trends and statistics\n- \u2705 **Top Skills** - Most in-demand skills from job postings\n\n#### **\ud83d\udd04 Workflow Integration (2/2 endpoints)** - Custom Workflows\n- \u2705 **Title \u2192 Skills Workflow** - Complete title normalization and skills extraction\n- \u2705 **Simple Title Skills** - Streamlined title-to-skills pipeline\n\n### \ud83d\udd27 **Core Functionality\n- **\ud83c\udfaf Skills Extraction from Text** - High accuracy skill identification from job descriptions\n- **\ud83d\udcca Search & Discovery** - Fast, filtered search across skills, titles, and job postings\n- **\u26a1 Bulk Operations** - Efficient processing of multiple items in single requests\n- **\ud83d\udd04 Version Management** - Uses \"latest\" keyword with backward compatibility\n- **\ud83d\udd10 OAuth2 Authentication** - Secure authentication with dynamic scope switching\n- **\ud83d\udd17 Related & Similar Skills** - Find skills relationships via multiple APIs\n- **\ud83d\udcbc Job Market Data** - Real-time job posting analysis and trends\n- **\ud83d\udcca Benchmarks & Analytics** - Salary and employment data access\n- **\ud83d\udee4\ufe0f Career Pathways** - Career transition analysis and recommendations\n\n### \ud83d\udee0\ufe0f **MCP Tools Available (23 core tools across 7 categories)**\n\n#### **Skills Tools (7 tools)**\nAPI Docs: https://docs.lightcast.dev/apis/skills\n\n- `bulk_retrieve_skills` - Efficient bulk skill retrieval\n- `extract_skills_from_text` - Extract skills with custom confidence threshold\n- `find_similar_skills` - Find similar skills via Similarity API\n- `get_skill_details` - Get detailed skill information by ID\n- `get_skills_metadata` - General skills taxonomy metadata\n- `get_related_skills` - Find skills related to a specific skill (now working with POST endpoint)\n- `search_skills` - Search skills with advanced filters (type, category, subcategory)\n\n#### **Titles Tools (4 tools)**\nAPI Docs: https://docs.lightcast.dev/apis/titles\n\n- `bulk_retrieve_titles` - Efficient bulk title retrieval\n- `get_job_title_details` - Get detailed title information by ID\n- `normalize_job_title` - Normalize raw job titles\n- `search_job_titles` - Search job titles in Lightcast database\n\n#### **Job Postings Tools (3 tools)**\nAPI Docs: https://docs.lightcast.dev/apis/job-postings\n\n- `get_job_posting_details` - Get detailed job posting information\n- `get_posting_statistics` - Job posting trends and analytics\n- `search_job_postings` - Search real-time job market data\n\n#### **Classification Tools (1 tool)**\nAPI Docs: https://docs.lightcast.dev/apis/classification\n\n- `get_classification_metadata` - Classification API capabilities and metadata\n\n#### **Occupation Benchmark Tools (2 tools)**\nAPI Docs: https://docs.lightcast.dev/apis/occupation-benchmark\n\n- `get_benchmark_metadata` - Benchmark API capabilities and metadata\n- `get_occupation_benchmark` - Salary and employment benchmarks by occupation\n\n#### **Similarity Tools (3 tools)**\nAPI Docs: https://docs.lightcast.dev/apis/similarity\n\n- `get_similarity_metadata` - Similarity API capabilities and metadata\n- `get_pathways_metadata` - Career pathways API capabilities and metadata\n\n\n#### **Unified Workflows (4 tools)**\n- `analyze_job_posting_skills` - Comprehensive job posting analysis\n- `normalize_title_and_get_skills` - Complete title\u2192skills workflow\n- `normalize_title_and_extract_skills` - Alternative classification-based extraction\n\n\n## \ud83d\udee0\ufe0f Installation\n\n### Prerequisites\n\n- Python 3.12+ (required for uv-dynamic-versioning)\n- [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip\n- Lightcast API credentials (Client ID and Secret with `emsi_open` scope). You can request free API access [here](https://lightcast.io/open-skills/access) which will give you access to the skills and titles taxonomies (subset of only the Skills and Titles APIs).\n\n### \ud83d\ude80 Quick Start with uvx (Recommended)\n\n```bash\n# Install and run directly from PyPI (no installation required)\nuvx --from mcp-lightcast mcp-lightcast --help\n\n# Run with environment variables\nLIGHTCAST_CLIENT_ID=your_id LIGHTCAST_CLIENT_SECRET=your_secret \\\nuvx --from mcp-lightcast mcp-lightcast\n\n# Use stdio transport for Claude Desktop\nLIGHTCAST_CLIENT_ID=your_id LIGHTCAST_CLIENT_SECRET=your_secret \\\nuvx --from mcp-lightcast mcp-lightcast --transport stdio\n```\n\n### \ud83d\udce6 Install from PyPI\n\n```bash\n# Install globally\npip install mcp-lightcast\n\n# Or with uv\nuv tool install mcp-lightcast\n\n# Run the server\nmcp-lightcast --help\n```\n\n### \ud83d\udd27 Development Installation\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/lawwu/mcp-lightcast.git\ncd mcp-lightcast\n\n# 2. Set up development environment \nmake setup\n\n# 3. Configure your API credentials\n# Edit .env with your Lightcast API credentials\n\n# 4. Validate configuration\nmake validate-config\n\n# 5. Run the server\nmake run\n```\n\n### \ud83d\udc33 Docker Installation\n\n```bash\n# Pull the latest image (when available)\ndocker pull ghcr.io/lawwu/mcp-lightcast:latest\n\n# Run with environment variables\ndocker run --rm -it \\\n  -e LIGHTCAST_CLIENT_ID=your_id \\\n  -e LIGHTCAST_CLIENT_SECRET=your_secret \\\n  ghcr.io/lawwu/mcp-lightcast:latest\n\n# Or with environment file\ndocker run --rm -it --env-file .env ghcr.io/lawwu/mcp-lightcast:latest\n```\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\nCreate a `.env` file with your Lightcast API credentials:\n\n```bash\n# Required - Lightcast API Configuration\nLIGHTCAST_CLIENT_ID=your_client_id_here\nLIGHTCAST_CLIENT_SECRET=your_client_secret_here\n\n# Optional - API Configuration (with defaults)\nLIGHTCAST_BASE_URL=https://api.lightcast.io\nLIGHTCAST_OAUTH_URL=https://auth.emsicloud.com/connect/token\nLIGHTCAST_OAUTH_SCOPE=emsi_open\nLIGHTCAST_RATE_LIMIT=1000\n\n# Optional - MCP Server Configuration\nMCP_SERVER_NAME=lightcast-mcp-server\nLOG_LEVEL=INFO\nMASK_ERROR_DETAILS=true\n```\n\n### Lightcast API Access\n\nTo use this server, you need:\n\n1. \ud83d\udcdd A [Lightcast API account](https://lightcast.io/open-skills/access)\n2. \ud83d\udd11 Client ID and Client Secret for OAuth2 authentication\n3. \ud83c\udfaf Access to the following Lightcast APIs:\n   - Titles API - Job title search and normalization\n   - Skills API - Skills search and categorization\n   - Classification API - Occupation code mapping\n   - Similarity API - Skills and occupation relationships\n\n\n## \ud83c\udfaf Usage\n\n### Command Line Interface\n\nThe server includes a comprehensive CLI with multiple options:\n\n```bash\n# Basic usage (uses streamable-http on port 3000 by default)\nmcp-lightcast\n\n# Use stdio transport (for Claude Desktop integration)\nmcp-lightcast --transport stdio\n\n# Use streamable-http transport with custom port\nmcp-lightcast --transport streamable-http --port 8080\n\n# With custom log level\nmcp-lightcast --log-level DEBUG\n\n# Validate configuration without starting server\nmcp-lightcast --validate-config\n\n# Use custom environment file\nmcp-lightcast --env-file /path/to/custom.env\n\n# Quiet mode (no logging)\nmcp-lightcast --quiet\n\n# Show help\nmcp-lightcast --help\n```\n\n### Development Commands\n\nUsing the included Makefile for easy development:\n\n```bash\n# Quick development setup and run\nmake dev\n\n# Run with debug logging\nmake dev-server\n\n# Run all quality checks\nmake check\n\n# Run tests with coverage\nmake test-coverage\n\n# Show Claude Desktop configuration\nmake claude-config\n```\n\n### Claude Desktop Integration\n\n#### Using uv (Recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"lightcast\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/mcp-lightcast\",\n        \"mcp-lightcast\"\n      ],\n      \"env\": {\n        \"LIGHTCAST_CLIENT_ID\": \"your_client_id\",\n        \"LIGHTCAST_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n#### Using Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"lightcast\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"-e\", \"LIGHTCAST_CLIENT_ID\",\n        \"-e\", \"LIGHTCAST_CLIENT_SECRET\",\n        \"ghcr.io/lawwu/mcp-lightcast:latest\"\n      ],\n      \"env\": {\n        \"LIGHTCAST_CLIENT_ID\": \"your_client_id\",\n        \"LIGHTCAST_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n#### Using uvx (Isolated)\n\n```json\n{\n  \"mcpServers\": {\n    \"lightcast\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"mcp-lightcast\",\n        \"mcp-lightcast\"\n      ],\n      \"env\": {\n        \"LIGHTCAST_CLIENT_ID\": \"your_client_id\",\n        \"LIGHTCAST_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n### \ud83d\udd27 Detailed Tool Usage Examples\n\n#### **\ud83c\udfaf Skills Tools**\n\n**search_skills** - Search skills with advanced filters\n```python\nskills = await search_skills(\n    query=\"python programming\",\n    limit=10,\n    skill_type=\"Hard Skill\",  # Optional: filter by skill type\n    category=\"Information Technology\",  # Optional: filter by category\n    version=\"latest\"  # Uses latest API version\n)\n```\n\n**extract_skills_from_text** - Extract skills from job descriptions\n```python\n# Extract skills with custom confidence threshold\nskills = await extract_skills_from_text(\n    text=\"Looking for Python developer with React and database experience...\",\n    confidence_threshold=0.7,\n    version=\"latest\"\n)\n```\n\n**extract_skills_simple** - Extract skills with default settings\n```python\n# Quick skills extraction with default confidence (0.5)\nskills = await extract_skills_simple(\n    text=\"We need Java developers with Spring Boot experience\",\n    version=\"latest\"\n)\n```\n\n**bulk_retrieve_skills** - Efficient bulk skill retrieval\n```python\n# Get multiple skills in one request\nskills = await bulk_retrieve_skills(\n    skill_ids=[\"KS125LS6N7WP4S6SFTCK\", \"KS440C66FGP5WGWYMP0F\"],\n    version=\"latest\"\n)\n```\n\n#### **\ud83c\udff7\ufe0f Titles Tools**\n\n**search_job_titles** - Search job titles\n```python\ntitles = await search_job_titles(\n    query=\"software engineer\",\n    limit=10,\n    version=\"latest\"\n)\n```\n\n**get_job_title_details** - Get detailed title information\n```python\ntitle = await get_job_title_details(\n    title_id=\"ET6850661D6AE5FA86\",\n    version=\"latest\"\n)\n```\n\n**bulk_retrieve_titles** - Efficient bulk title retrieval\n```python\ntitles = await bulk_retrieve_titles(\n    title_ids=[\"ET6850661D6AE5FA86\", \"ETBF8AE9187B3810C5\"],\n    version=\"latest\"\n)\n```\n\n#### **\ud83d\udcca Metadata Tools**\n\n**get_skills_version_metadata** - API version information\n```python\nmetadata = await get_skills_version_metadata(version=\"latest\")\n# Returns: version, skill_count, language_support, skill_types, etc.\n```\n\n**get_titles_version_metadata** - API version information  \n```python\nmetadata = await get_titles_version_metadata(version=\"latest\")\n# Returns: version, title_count, removed_title_count, fields\n```\n\n#### **\u26a0\ufe0f Limited Availability Tools**\nSome tools require premium authentication scopes or have endpoint limitations:\n\n**normalize_job_title** - \u274c Requires premium scope\n```python\n# Currently returns 401 Unauthorized with emsi_open scope\nresult = await normalize_job_title(\"sr software dev\")\n```\n\n**analyze_job_posting_skills** - \u2705 Working via skills extraction\n```python\n# Uses skills extraction instead of normalization\nresult = await analyze_job_posting_skills(\n    job_title=\"Software Engineer\",\n    job_description=\"Full job description text...\",\n    extract_from_description=True  # Uses working skills extraction\n)\n```\n\n### \ud83c\udfaf Example Workflows\n\n#### **1. Extract Skills from Job Description**\n\n```python\n# Analyze a job posting to extract relevant skills\njob_description = \"\"\"\nWe're looking for a Senior Software Engineer with expertise in Python, \nReact, and cloud technologies. Experience with Docker, Kubernetes, \nand AWS is required. Strong communication skills and team collaboration \nabilities are essential.\n\"\"\"\n\n# Extract skills with high confidence\nskills = await extract_skills_from_text(\n    text=job_description,\n    confidence_threshold=0.8,\n    version=\"latest\"\n)\n\nprint(f\"High-confidence skills found: {len(skills)}\")\nfor skill in skills:\n    print(f\"- {skill['name']} (confidence: {skill['confidence']:.2f})\")\n```\n\n#### **2. Compare Skills Across Job Titles**\n\n```python\n# Search and compare skills requirements for different roles\ntitles = [\"Data Scientist\", \"Machine Learning Engineer\", \"Software Engineer\"]\ntitle_skills = {}\n\nfor title in titles:\n    # Search for the title\n    title_results = await search_job_titles(query=title, limit=1)\n    if title_results:\n        title_id = title_results[0]['id']\n        \n        # Get detailed title information  \n        title_details = await get_job_title_details(title_id)\n        title_skills[title] = title_details\n        \nprint(\"Job title comparison completed\")\n```\n\n#### **3. Bulk Skills Analysis**\n\n```python\n# Efficiently analyze multiple skills at once\nskill_names = [\"Python\", \"JavaScript\", \"Machine Learning\", \"Docker\"]\n\n# First search for skill IDs\nskill_ids = []\nfor name in skill_names:\n    results = await search_skills(query=name, limit=1)\n    if results:\n        skill_ids.append(results[0]['id'])\n\n# Get detailed information for all skills in one request\nif skill_ids:\n    detailed_skills = await bulk_retrieve_skills(skill_ids)\n    \n    for skill in detailed_skills:\n        print(f\"Skill: {skill['name']}\")\n        print(f\"Type: {skill.get('type', {}).get('name', 'Unknown')}\")\n        print(f\"Category: {skill.get('category', 'Unknown')}\")\n        print(\"---\")\n```\n\n#### **4. API Version and Statistics**\n\n```python\n# Get comprehensive API information\nskills_meta = await get_skills_version_metadata()\ntitles_meta = await get_titles_version_metadata()\n\nprint(f\"Skills API v{skills_meta['version']}: {skills_meta['skill_count']:,} skills\")\nprint(f\"Languages: {', '.join(skills_meta['language_support'])}\")\nprint(f\"Skill types: {len(skills_meta['skill_types'])}\")\n\nprint(f\"Titles API v{titles_meta['version']}: {titles_meta['title_count']:,} titles\")\n```\n\n## \ud83e\uddea Development\n\n### Prerequisites\n\n- Python 3.12+ (required)\n- [uv](https://docs.astral.sh/uv/) package manager\n- Docker (for containerized development)\n- Make (for development commands)\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/lawwu/mcp-lightcast.git\ncd mcp-lightcast\n\n# Quick setup (installs dependencies, creates .env)\nmake setup\n\n# Install development dependencies only  \nmake install-dev\n\n# Run development server with debug logging\nmake dev-server\n```\n\n### Project Structure\n\n```\nmcp-lightcast/\n\u251c\u2500\u2500 \ud83d\udcc1 src/mcp_lightcast/           # Main package\n\u2502   \u251c\u2500\u2500 __init__.py                 # CLI entry point with Click\n\u2502   \u251c\u2500\u2500 __main__.py                 # Module execution entry\n\u2502   \u251c\u2500\u2500 server.py                   # FastMCP server instance\n\u2502   \u251c\u2500\u2500 \ud83d\udcc1 auth/                    # Authentication modules\n\u2502   \u2502   \u251c\u2500\u2500 __init__.py\n\u2502   \u2502   \u2514\u2500\u2500 oauth.py               # OAuth2 implementation\n\u2502   \u251c\u2500\u2500 \ud83d\udcc1 apis/                    # API client modules  \n\u2502   \u2502   \u251c\u2500\u2500 __init__.py\n\u2502   \u2502   \u251c\u2500\u2500 base.py                # Base client with error handling\n\u2502   \u2502   \u251c\u2500\u2500 titles.py              # Titles API client\n\u2502   \u2502   \u251c\u2500\u2500 skills.py              # Skills API client\n\u2502   \u2502   \u251c\u2500\u2500 classification.py      # Classification API client\n\u2502   \u2502   \u2514\u2500\u2500 similarity.py          # Similarity API client\n\u2502   \u251c\u2500\u2500 \ud83d\udcc1 tools/                   # MCP tools registration\n\u2502   \u2502   \u251c\u2500\u2500 __init__.py\n\u2502   \u2502   \u251c\u2500\u2500 titles_tools.py        # Title-related MCP tools\n\u2502   \u2502   \u251c\u2500\u2500 skills_tools.py        # Skills-related MCP tools\n\u2502   \u2502   \u251c\u2500\u2500 workflow_tools.py      # Combined workflow tools\n\u2502   \u2502   \u2514\u2500\u2500 normalize_title_get_skills.py  # Core workflow logic\n\u2502   \u2514\u2500\u2500 \ud83d\udcc1 utils/                   # Utility functions\n\u2502       \u2514\u2500\u2500 __init__.py\n\u251c\u2500\u2500 \ud83d\udcc1 tests/                       # Test suite\n\u2502   \u251c\u2500\u2500 \ud83d\udcc1 unit/                    # Unit tests\n\u2502   \u251c\u2500\u2500 \ud83d\udcc1 integration/             # Integration tests\n\u2502   \u2514\u2500\u2500 conftest.py                # Pytest fixtures\n\u251c\u2500\u2500 \ud83d\udcc1 config/                      # Configuration management\n\u2502   \u2514\u2500\u2500 settings.py                # Pydantic settings\n\u251c\u2500\u2500 \ud83d\udcc1 .github/workflows/           # CI/CD pipelines\n\u2502   \u2514\u2500\u2500 ci.yml                     # GitHub Actions workflow\n\u251c\u2500\u2500 \ud83d\udc33 Dockerfile                   # Production container\n\u251c\u2500\u2500 \ud83d\udc33 Dockerfile.dev               # Development container  \n\u251c\u2500\u2500 \ud83d\udc33 docker-compose.yml           # Multi-service setup\n\u251c\u2500\u2500 \ud83d\udccb Makefile                     # Development commands\n\u251c\u2500\u2500 \ud83d\udce6 pyproject.toml               # Project metadata & dependencies\n\u251c\u2500\u2500 \ud83d\udd12 uv.lock                      # Dependency lock file\n\u2514\u2500\u2500 \ud83d\udcd6 README.md                    # This file\n```\n\n### Development Workflow\n\n#### Code Quality & Testing\n\n```bash\n# Run all quality checks (lint + type-check + test)\nmake check\n\n# Individual quality checks\nmake lint           # Ruff linting\nmake type-check     # MyPy type checking  \nmake format         # Black + Ruff formatting\n\n# Testing options\nmake test           # Run all tests\nmake test-coverage  # Tests with coverage report\nmake test-basic     # Basic functionality test\n```\n\n#### Docker Development\n\n```bash\n# Build Docker images\nmake docker-build       # Production image\nmake docker-build-dev   # Development image\n\n# Run with Docker\nmake docker-run         # Run production container\nmake docker-dev         # Run development container\n\n# Test Docker configuration\nmake docker-test        # Validate container setup\n```\n\n#### uv Package Management\n\n```bash\n# Dependency management\nmake uv-lock           # Generate lockfile\nmake uv-sync           # Sync from lockfile\nmake uv-update         # Update all dependencies\n\n# Add dependencies\nmake uv-add PACKAGE=requests\nmake uv-add-dev PACKAGE=pytest-mock\n```\n\n## API Reference\n\n### Rate Limits\n\n- Default: 1000 requests per hour per API key\n- Rate limit headers are included in responses\n- Rate limit errors (429) are handled gracefully\n\n### Error Handling\n\n- Authentication errors are automatically retried\n- Rate limits include reset time information\n- API errors include detailed status codes and messages\n- Network errors are handled with appropriate timeouts\n\n### API Version Flexibility\n\nThe MCP server provides flexible version management:\n\n- **Default**: `\"latest\"` - Always uses the newest available API version\n- **Backward Compatible**: Users can specify any previous version (e.g., `\"5.47\"`, `\"9.33\"`)\n- **Future-Proof**: Automatically gets new API features when Lightcast releases updates\n\n**Examples:**\n```python\n# Use latest version (default)\nsearch_job_titles(\"software engineer\")\n\n# Use specific version for consistency\nsearch_job_titles(\"software engineer\", version=\"5.47\")\n\n# Use older version if needed\nsearch_skills(\"python\", version=\"9.32\")\n```\n\n**Current API Versions:**\n- Skills API: `9.33` with 41,139 skills (English, Spanish, French support)\n- Titles API: `5.47` with 73,993 titles\n- Both APIs use `\"latest\"` keyword for automatic version management\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udcda Documentation & Support\n\n### **API Documentation**\n- [Lightcast API Documentation](https://docs.lightcast.dev/) - Official Lightcast API reference\n- [FastMCP Documentation](https://gofastmcp.com/) - FastMCP framework documentation  \n- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification\n\n### **Project Resources**\n- [PyPI Package](https://pypi.org/project/mcp-lightcast/) - Official Python package\n- [GitHub Repository](https://github.com/lawwu/mcp-lightcast) - Source code and issues\n- [GitHub Releases](https://github.com/lawwu/mcp-lightcast/releases) - Version history and changelog\n\n### **Getting Help**\n- **Issues**: [GitHub Issues](https://github.com/lawwu/mcp-lightcast/issues) for bugs and feature requests\n- **Discussions**: [GitHub Discussions](https://github.com/lawwu/mcp-lightcast/discussions) for questions and community support\n- **Lightcast Support**: [Contact Lightcast](https://docs.lightcast.dev/contact) for API access and credentials\n\n### **Current Status**\n- **Version**: 0.2.0 (Production Ready)\n- **API Coverage**: 43/43 endpoints (100%)\n- **MCP Tools**: 23 core tools (streamlined)\n- **Premium Features**: All working with user credentials\n- **Python**: 3.12+ required\n- **License**: MIT",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "MCP server for Lightcast API integration using FastMCP",
    "version": "0.2.1",
    "project_urls": {
        "Changelog": "https://github.com/your-username/mcp-lightcast/releases",
        "Documentation": "https://github.com/your-username/mcp-lightcast/blob/main/README.md",
        "Homepage": "https://github.com/your-username/mcp-lightcast",
        "Issues": "https://github.com/your-username/mcp-lightcast/issues",
        "Repository": "https://github.com/your-username/mcp-lightcast"
    },
    "split_keywords": [
        "api",
        " fastmcp",
        " job-titles",
        " lightcast",
        " mcp",
        " skills"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "54a6c9400b434cb803a0e2ccbadeab6acc53a40257592d32a77525f8fbede3cb",
                "md5": "7332ae9712207fdb3bed5641f200036b",
                "sha256": "949eb6d02695b55a4385410dc819706659a53168ca4f2e301fe8848cf9e419b7"
            },
            "downloads": -1,
            "filename": "mcp_lightcast-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7332ae9712207fdb3bed5641f200036b",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 50548,
            "upload_time": "2025-08-22T05:24:33",
            "upload_time_iso_8601": "2025-08-22T05:24:33.288038Z",
            "url": "https://files.pythonhosted.org/packages/54/a6/c9400b434cb803a0e2ccbadeab6acc53a40257592d32a77525f8fbede3cb/mcp_lightcast-0.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "285b5607afbf65e06331f581e326d060d6966ef9490a30a1c3b5f77b9fd202f2",
                "md5": "72dc829b3d46adc11151eeeb02baa82f",
                "sha256": "677abcf88b70d19722c4265bce41f22ae04f5263502486766e7640f5c274fa8c"
            },
            "downloads": -1,
            "filename": "mcp_lightcast-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "72dc829b3d46adc11151eeeb02baa82f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 122363,
            "upload_time": "2025-08-22T05:24:34",
            "upload_time_iso_8601": "2025-08-22T05:24:34.557251Z",
            "url": "https://files.pythonhosted.org/packages/28/5b/5607afbf65e06331f581e326d060d6966ef9490a30a1c3b5f77b9fd202f2/mcp_lightcast-0.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-22 05:24:34",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "your-username",
    "github_project": "mcp-lightcast",
    "github_not_found": true,
    "lcname": "mcp-lightcast"
}