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>
Add comprehensive AI enhancement to C3.4 Configuration Pattern Extraction
similar to C3.3's dual-mode architecture (API + LOCAL).
NEW CAPABILITIES (What users can do now):
1. **AI-Powered Config Analysis** - Understand what configs do, not just extract them
- Explanations: What each configuration setting does
- Best Practices: Suggested improvements and better organization
- Security Analysis: Identifies hardcoded secrets, exposed credentials
- Migration Suggestions: Opportunities to consolidate configs
- Context: Explains detected patterns and when to use them
2. **Dual-Mode AI Support** (Same as C3.3):
- API Mode: Claude API analyzes configs (requires ANTHROPIC_API_KEY)
- LOCAL Mode: Claude Code CLI (FREE, no API key needed)
- AUTO Mode: Automatically detects best available mode
3. **Seamless Integration**:
- CLI: --enhance, --enhance-local, --ai-mode flags
- Codebase Scraper: Works with existing enhance_with_ai parameter
- MCP Tools: Enhanced extract_config_patterns with AI parameters
- Optional: Enhancement only runs when explicitly requested
Components Added:
- ConfigEnhancer class (~400 lines) - Dual-mode AI enhancement engine
- Enhanced CLI flags in config_extractor.py
- AI integration in codebase_scraper.py config extraction workflow
- MCP tool parameter expansion (enhance, enhance_local, ai_mode)
- FastMCP server tool signature updates
- Comprehensive documentation in CHANGELOG.md and README.md
Performance:
- Basic extraction: ~3 seconds for 100 config files
- With AI enhancement: +30-60 seconds (LOCAL mode, FREE)
- With AI enhancement: +20-40 seconds (API mode, ~$0.10-0.20)
Use Cases:
- Security audits: Find hardcoded secrets across all configs
- Migration planning: Identify consolidation opportunities
- Onboarding: Understand what each config file does
- Best practices: Get improvement suggestions for config organization
Technical Details:
- Structured JSON prompts for reliable AI responses
- 5 enhancement categories: explanations, best_practices, security, migration, context
- Graceful fallback if AI enhancement fails
- Security findings logged separately for visibility
- Results stored in JSON under 'ai_enhancements' key
Testing:
- 28 comprehensive tests in test_config_extractor.py
- Tests cover: file detection, parsing, pattern detection, enhancement modes
- All integrations tested: CLI, codebase_scraper, MCP tools
Documentation:
- CHANGELOG.md: Complete C3.4 feature description
- README.md: Updated C3.4 section with AI enhancement
- MCP tool descriptions: Added AI enhancement details
Related Issues: #74🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add comprehensive multi-LLM support section featuring:
- 4 supported platforms (Claude, Gemini, OpenAI, Markdown)
- Comparison table showing format, upload, enhancement, API keys
- Example commands for each platform
- Installation instructions for optional dependencies
- 100% backward compatibility guarantee
Highlights:
- Claude remains default (no changes needed)
- Optional dependencies: [gemini], [openai], [all-llms]
- Universal scraping works for all platforms
- Platform-specific packaging and upload
Related to #179
Add automatic skill installation to 10+ AI coding agents with a single command.
New Features:
- New install-agent command for installing skills to any AI agent
- Support for 10+ agents: Claude Code, Cursor, VS Code, Amp, Goose, OpenCode, Letta, Aide, Windsurf
- Smart path resolution (global ~/.agent vs project-relative .agent/)
- Fuzzy agent name matching with suggestions
- --agent all flag to install to all agents at once
- --force flag to overwrite existing installations
- --dry-run flag to preview installations
- Comprehensive error handling and user feedback
Implementation:
- Created install_agent.py (379 lines) with core installation logic
- Updated main.py with install-agent subcommand
- Updated pyproject.toml with entry point
- Added 32 comprehensive tests (all passing, 603 total)
- No regressions in existing functionality
Documentation:
- Updated README.md with multi-agent installation guide
- Updated CLAUDE.md with install-agent examples
- Updated CHANGELOG.md with v2.3.0 release notes
- Added agent compatibility table
Technical Details:
- 100% own implementation (no external dependencies)
- Pure Python using stdlib (shutil, pathlib, argparse)
- Compatible with Agent Skills open standard (agentskills.io)
- Works offline
Closes#210🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Phase 4 Complete:
- Updated README.md with git source usage examples and use cases
- Created docs/GIT_CONFIG_SOURCES.md (800+ lines comprehensive guide)
- Updated CHANGELOG.md with v2.2.0 release notes
- Added configs/example-team/ example repository with E2E test
Documentation covers:
- Quick start and architecture
- MCP tools reference (4 tools with examples)
- Authentication for GitHub, GitLab, Bitbucket
- Use cases (small teams, enterprise, open source)
- Best practices, troubleshooting, advanced topics
- Complete API reference
Example repository includes:
- 3 example configs (react-custom, vue-internal, company-api)
- README with usage guide
- E2E test script (7 steps, 100% passing)
🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Major improvements:
- Configurable directory exclusions (Issue #203)
- Unlimited local repository analysis
- Skip llms.txt option (PR #198)
- 10+ bug fixes for GitHub scraper
- Test suite expanded to 427 tests
See CHANGELOG.md for full details.
Updates across all major documentation files to reflect v2.1.0 release
status and recent completions.
Changes:
- CLAUDE.md:
* Updated version from v2.0.0 to v2.1.0
* Updated date to November 29, 2025
* Updated test count from 391 to 427
* Moved completed PRs (#195, #198) and Issue #203 to "Completed" section
* Updated "Next Up" priorities
- README.md:
* Updated version badge from 2.0.0 to 2.1.0
* Updated test badge from 379 to 427 passing
- CHANGELOG.md:
* Added Issue #203 (Configurable EXCLUDED_DIRS) to Unreleased section
* Documented 19 comprehensive tests for exclude_dirs feature
* Listed both extend and replace modes
- FUTURE_RELEASES.md:
* Marked v2.1.0 as "Released" (November 29, 2025)
* Moved "Fix 12 unified tests" to completed
* Updated release schedule table
- FLEXIBLE_ROADMAP.md:
* Updated current status from v1.0.0 to v2.1.0
* Added latest release date
* Expanded "What Works" section with new features
* Updated test count to 427
All documentation now accurately reflects:
- v2.1.0 release status ✅
- 427 tests passing (up from 391) ✅ - Issue #203 completion ✅
- PR #195 and #198 merged status ✅
Related: #203
All unified scraping tests are now passing! Updated documentation to reflect current status.
**Changes:**
1. **CLAUDE.md** - Updated test status throughout
- Changed "⚠️ 12 unified tests need fixes" to "✅ All 22 unified tests passing"
- Updated test count from 379 to 391 tests
- Marked unified configs as ✅ (all 5 working and tested)
- Updated "Next Up" section with completed items
- Updated last verification date to Nov 29, 2025
2. **README.md** - Updated test count
- Changed "379 tests" to "391 tests"
3. **docs/CLAUDE.md** - Updated test documentation
- Updated test counts throughout
- Removed outdated warnings about failing tests
**Test Status:**
- ✅ tests/test_unified.py: 18/18 passing
- ✅ tests/test_unified_mcp_integration.py: 4/4 passing
- ✅ Total: 391 tests passing, 32 skipped
**Unified Scraping:**
- All 5 unified configs verified and working
- Conflict detection fully tested
- Rule-based and AI merge modes tested
- Feature is production-ready
Task 2.2 Complete - No code changes needed, tests were already passing!
README.md:
- Add PyPI badges (version, downloads, python version)
- Update test count from 299 to 379 passing tests
- Add prominent 'Now Available on PyPI!' callout section
- Reorder installation options (pip as Option 1, uv as Option 2)
- Add links to Quick Start and Bulletproof guides
- Emphasize PyPI as the recommended installation method
CHANGELOG.md:
- Add comprehensive v2.0.0 release entry (dated 2025-11-11)
- Document PyPI publication as major milestone
- Detail modern Python packaging changes
- Include unified CLI interface documentation
- Add migration guide for users and developers
- List all breaking changes and deprecations
- Document 379 passing tests and import fixes
FUTURE_RELEASES.md (NEW):
- Create roadmap document for upcoming releases
- Plan v2.1.0 (Dec 2025): Test coverage & quality improvements
- Plan v2.2.0 (Q1 2026): Web presence & community growth
- Plan v2.3.0 (Q2 2026): Developer experience & integrations
- Long-term vision for v3.0+
- Community contribution guidelines
- Release schedule and priority system
🚀 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add smart terminal selection for --enhance-local with cascading priority:
1. SKILL_SEEKER_TERMINAL env var (explicit user preference)
2. TERM_PROGRAM env var (inherit current terminal)
3. Terminal.app (fallback default)
Supports Ghostty, iTerm2, WezTerm, and Terminal.app. Includes comprehensive
test suite (11 tests) and user documentation.
Changes:
- Add detect_terminal_app() function with priority-based selection
- Support for 4 major macOS terminals via TERMINAL_MAP
- Fallback handling for unknown terminals (IDE terminals)
- Add TERMINAL_SELECTION.md with setup examples and troubleshooting
- Update README.md to link to terminal selection guide
- Full test coverage for all detection paths and edge cases
Updated main description and feature sections to accurately reflect v2.0.0 capabilities:
## Changes:
**Main Description**:
- Changed from 'documentation website' to 'documentation websites, GitHub repositories, and PDFs'
- Added code analysis, conflict detection to workflow steps
- Emphasized multi-source capabilities
**What is Skill Seeker Section**:
- Updated to mention all three sources (docs, GitHub, PDFs)
- Added 'Analyzes code repositories with deep AST parsing'
- Added 'Detects conflicts between documentation and code'
- Now shows 6 steps instead of 4 (more comprehensive)
**Why Use This Section**:
- Updated use cases to include GitHub + docs combinations
- Added conflict detection benefits
- Added documentation gap analysis use case
- Added open source analysis use case
**GitHub Repository Scraping Section**:
- Updated version tag from v1.4.0 to v2.0.0
- Added 'Deep Code Analysis' with AST parsing
- Added 'API Extraction' with parameters and types
- Added 'Conflict Detection' feature
- Reorganized features to highlight new capabilities
## Rationale:
The previous README said 'any documentation website to skill' but we now support:
1. Documentation websites (original)
2. GitHub repositories (NEW - v2.0.0)
3. PDF files (v1.2.0)
4. Unified multi-source (docs + GitHub + PDF) (NEW - v2.0.0)
This update ensures users know they can scrape GitHub repos directly and combine multiple sources.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major documentation update explaining the new unified scraping system that combines documentation + GitHub + PDF sources in a single skill with automatic conflict detection.
## Changes:
**README.md:**
- Update version badge to v2.0.0
- Add "Unified Multi-Source Scraping" to Key Features section
- Add comprehensive Option 5 section showing:
- Problem statement (documentation drift)
- Solution with code example
- Conflict detection types and severity levels
- Transparent reporting with side-by-side comparison
- List of advantages (identifies gaps, catches changes, single source of truth)
- Available unified configs
- Link to full guide (docs/UNIFIED_SCRAPING.md)
**CLAUDE.md:**
- Update Current Status to v2.0.0
- Add "Major Release: Unified Multi-Source Scraping" in Recent Updates
- Update configs count from 11/11 to 15/15 (added 4 unified configs)
- Add new "Unified Multi-Source Scraping" section under Core Commands
- Include command examples and feature highlights
- Explain what makes unified scraping special
**QUICKSTART.md:**
- Add Option D: Unified Multi-Source to Step 2
- Add unified configs to Available Presets section
- Show react_unified, django_unified, fastapi_unified, godot_unified examples
## Value:
This documentation update explains how unified scraping helps developers:
- Mix documentation + code in one skill
- Automatically detect conflicts (missing_in_docs, missing_in_code, signature_mismatch)
- Get transparent side-by-side comparisons with ⚠️ warnings
- Identify documentation gaps and outdated docs
- Create a single source of truth combining both sources
Related to: Phase 7-11 unified scraper implementation (commit 5d8c7e3)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add PDF support to README.md Key Features
- Add PDF CLI example (Option 3)
- Update MCP README from 9 to 10 tools
- Add scrape_pdf tool documentation
- Add PDF workflow example
- Update tool descriptions
All main documentation now reflects PDF functionality
Added ansible-core.json config to available presets list in:
- README.md: Added to preset table and usage examples
- CLAUDE.md: Added to production configs list with details
Changes:
- Total configs: 11 → 12
- New category: DevOps & Automation
- Reorganized config list for better categorization
Related: PR #147
The MCP package requires Python 3.10 or higher. Updated:
- GitHub Actions workflow to test Python 3.10, 3.11, 3.12
- README.md badge to Python 3.10+
- CLAUDE.md prerequisites
- CONTRIBUTING.md prerequisites
- docs/MCP_SETUP.md prerequisites
This fixes the MCP installation error in CI:
'ERROR: No matching distribution found for mcp>=1.0.0'
MCP package versions 0.9.1+ all require Python 3.10+.
Infrastructure:
- Add GitHub Actions workflows (tests.yml, release.yml)
- Add CHANGELOG.md with full version history
- Add CONTRIBUTING.md with contribution guidelines
- Add RELEASE_NOTES_v1.0.0.md for v1.0.0 release
Documentation:
- Update README.md with version badge (v1.0.0)
- Update test count badge (14 tests)
- Add links to new documentation files
Features:
- CI/CD pipeline with automated testing
- Multi-OS testing (Ubuntu, macOS)
- Multi-Python version testing (3.7-3.11)
- Automated release creation on tag push
- Code coverage reporting
This completes the v1.0.0 production release setup.
Comprehensive documentation updates reflecting MCP integration:
README.md:
- Add MCP Integration and Tests Passing badges
- Enhance MCP section with "Tested and Working" status
- Add links to both setup and testing guides
docs/MCP_SETUP.md:
- Update status to reflect production testing
- Add integration testing verification notes
- Confirm all 6 tools working with natural language
CLAUDE.md:
- Add prominent MCP Integration section at top
- List all 6 available MCP tools with descriptions
- Add setup instructions and production status
docs/TEST_MCP_IN_CLAUDE_CODE.md (moved from root):
- Relocate testing guide to docs/ for better organization
- Provides step-by-step MCP integration testing workflow
- Documents complete test suite for all 6 tools
All documentation now accurately reflects the fully tested and
working MCP integration verified in production Claude Code environment.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add estimate_pages.py script (~270 lines)
- Fast estimation without downloading content (HEAD requests only)
- Shows estimated total pages and recommended max_pages
- Validates URL patterns work correctly
- Estimates scraping time based on rate_limit
- Update CLAUDE.md with estimator workflow and commands
- Update README.md features section with estimation benefits
- Usage: python3 estimate_pages.py configs/react.json
- Time: 1-2 minutes vs 20-40 minutes for full scrape
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
