firefrost-gaming/skill-seekers-reference

Files

MiaoDX bd974148a2 feat: Update MCP to use server_fastmcp with venv Python support

This PR improves MCP server configuration by updating all documentation
to use the current server_fastmcp module and ensuring setup scripts
automatically use virtual environment Python instead of system Python.

## Changes

### 1. Documentation Updates (server → server_fastmcp)

Updated all references from deprecated `server` module to `server_fastmcp`:

**User-facing documentation:**
- examples/http_transport_examples.sh: All 13 command examples
- README.md: Configuration examples and troubleshooting commands
- docs/guides/MCP_SETUP.md: Enhanced migration guide with stdio/HTTP examples
- docs/guides/TESTING_GUIDE.md: Test import statements
- docs/guides/MULTI_AGENT_SETUP.md: Updated examples
- docs/guides/SETUP_QUICK_REFERENCE.md: Updated paths
- CLAUDE.md: CLI command examples

**MCP module:**
- src/skill_seekers/mcp/README.md: Updated config examples
- src/skill_seekers/mcp/agent_detector.py: Use server_fastmcp module

Note: Historical release notes (CHANGELOG.md) preserved unchanged.

### 2. Venv Python Configuration

**setup_mcp.sh improvements:**
- Added automatic venv detection (checks .venv, venv, and $VIRTUAL_ENV)
- Sets PYTHON_CMD to venv Python path when available
- **CRITICAL FIX**: Now updates PYTHON_CMD after creating/activating venv
- Generates MCP configs with full venv Python path
- Falls back to system python3 if no venv found
- Displays detected Python version and path

**Config examples updated:**
- .claude/mcp_config.example.json: Use venv Python path
- example-mcp-config.json: Use venv Python path
- Added "type": "stdio" for clarity
- Updated to use server_fastmcp module

### 3. Bug Fix: PYTHON_CMD Not Updated After Venv Creation

Previously, when setup_mcp.sh created or activated a venv, it failed to
update PYTHON_CMD, causing generated configs to still use system python3.

**Fixed cases:**
- When $VIRTUAL_ENV is already set → Update PYTHON_CMD to venv Python
- When existing venv is activated → Set PYTHON_CMD="$REPO_PATH/venv/bin/python3"
- When new venv is created → Set PYTHON_CMD="$REPO_PATH/venv/bin/python3"

## Benefits

### For Users:
✅ No deprecation warnings - All docs show current module
✅ Proper Python environment - MCP uses venv with all dependencies
✅ No system Python issues - Avoids "module not found" errors
✅ No global installation needed - No --break-system-packages required
✅ Automatic detection - setup_mcp.sh finds venv automatically
✅ Clean isolation - Projects don't interfere with system Python

### For Maintainers:
✅ Prepared for v3.0.0 - Documentation ready for server.py removal
✅ Reduced support burden - Fewer MCP configuration issues
✅ Consistent examples - All docs use same module/pattern

## Testing

**Verified:**
- ✅ All command examples use server_fastmcp
- ✅ No deprecated module references in user-facing docs (0 results)
- ✅ New module correctly referenced (129 instances)
- ✅ setup_mcp.sh detects venv and generates correct config
- ✅ PYTHON_CMD properly updated after venv creation
- ✅ MCP server starts correctly with venv Python

**Files changed:** 12 files (+262/-107 lines)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-18 15:55:46 +08:00

README.md

Skill Seekers Documentation

Welcome to the Skill Seekers documentation hub. This directory contains comprehensive documentation organized by category.

🆕 New in v2.7.0

Recently Added Documentation:

⭐ Quick Reference - One-page cheat sheet
⭐ API Reference - Programmatic usage guide
⭐ Bootstrap Skill - Self-hosting documentation
⭐ Code Quality - Linting and standards
⭐ Testing Guide - Complete testing reference
⭐ Migration Guide - Version upgrade guide
⭐ FAQ - Frequently asked questions

🚀 Getting Started

New to Skill Seekers? Start here:

Main README - Project overview and installation
Quick Reference - One-page cheat sheet ⚡
FAQ - Frequently asked questions
Quickstart Guide - Fast introduction
Bulletproof Quickstart - Beginner-friendly guide
Troubleshooting - Common issues and solutions

📖 User Guides

Essential guides for setup and daily usage:

Setup & Configuration
- Setup Quick Reference - Quick setup commands
- MCP Setup - MCP server configuration
- Multi-Agent Setup - Multi-agent configuration
- HTTP Transport - HTTP transport mode setup
Usage Guides
- Usage Guide - Comprehensive usage instructions
- Upload Guide - Uploading skills to platforms
- Testing Guide - Complete testing reference (1200+ tests)
- Migration Guide - Version upgrade instructions

⚡ Feature Documentation

Learn about core features and capabilities:

Core Features

Pattern Detection (C3.1) - Design pattern detection
Test Example Extraction (C3.2) - Extract usage from tests
How-To Guides (C3.3) - Auto-generate tutorials
Unified Scraping - Multi-source scraping
Bootstrap Skill - Self-hosting capability (dogfooding)

AI Enhancement

AI Enhancement - AI-powered skill enhancement
Enhancement Modes - Headless, background, daemon modes

PDF Features

PDF Scraper - Extract from PDF documents
PDF Advanced Features - OCR, images, tables
PDF Chunking - Handle large PDFs
PDF MCP Tool - MCP integration

🔌 Platform Integrations

Multi-LLM platform support:

Multi-LLM Support - Overview of platform support
Gemini Integration - Google Gemini
OpenAI Integration - ChatGPT

📘 Reference Documentation

Technical reference and architecture:

API Reference - Programmatic usage guide ⭐
Code Quality - Linting, testing, CI/CD standards ⭐
Feature Matrix - Platform compatibility matrix
Git Config Sources - Config repository management
Large Documentation - Handling large docs
llms.txt Support - llms.txt format
Skill Architecture - Skill structure
AI Skill Standards - Quality standards
C3.x Router Architecture - Router skills
Claude Integration - Claude-specific features

📋 Planning & Design

Development plans and designs:

Design Plans - Feature design documents

📦 Archive

Historical documentation and completed features:

Historical - Completed features and reports
Research - Research notes and POCs
Temporary - Temporary analysis documents

🤝 Contributing

Want to contribute? See:

Contributing Guide - Contribution guidelines
Roadmap - Comprehensive roadmap with 136 tasks

📝 Changelog

CHANGELOG - Version history and release notes

💡 Quick Links

For Users

For Developers

Contributing
Development Setup
Testing Guide - Complete testing reference
Code Quality - Linting and standards
API Reference - Programmatic usage
Architecture

API & Tools

🔍 Finding What You Need

I want to...

Get started quickly → Quick Reference or Quickstart Guide

Find quick answers → FAQ - Frequently asked questions

Use Skill Seekers programmatically → API Reference - Python integration

Set up MCP server → MCP Setup Guide

Run tests → Testing Guide - 1200+ tests

Understand code quality standards → Code Quality - Linting and CI/CD

Upgrade to new version → Migration Guide - Version upgrades

Scrape documentation → Usage Guide → Documentation Scraping

Scrape GitHub repos → Usage Guide → GitHub Scraping

Scrape PDFs → PDF Scraper

Combine multiple sources → Unified Scraping

Enhance my skill with AI → AI Enhancement

Upload to Google Gemini → Gemini Integration

Upload to ChatGPT → OpenAI Integration

Understand design patterns → Pattern Detection

Extract test examples → Test Example Extraction

Generate how-to guides → How-To Guides

Create self-documenting skill → Bootstrap Skill - Dogfooding

Fix an issue → Troubleshooting or FAQ

Contribute code → Contributing Guide and Code Quality

📢 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Project Board: GitHub Projects

Documentation Version: 2.7.0 Last Updated: 2026-01-18 Status: ✅ Complete & Organized