Update documentation for MCP integration
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>
This commit is contained in:
yusyus
@@ -2,6 +2,11 @@
|
||||
|
||||
Step-by-step guide to set up the Skill Seeker MCP server with Claude Code.
|
||||
|
||||
**✅ Fully Tested and Working**: All 6 MCP tools verified in production use with Claude Code
|
||||
- ✅ 25 comprehensive unit tests (100% pass rate)
|
||||
- ✅ Integration tested via actual Claude Code MCP protocol
|
||||
- ✅ All 6 tools working with natural language commands
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
@@ -68,9 +73,21 @@ Successfully installed mcp-0.9.0 requests-2.31.0 beautifulsoup4-4.12.3
|
||||
|
||||
```bash
|
||||
# Test MCP server can start
|
||||
python3 mcp/server.py
|
||||
timeout 3 python3 mcp/server.py || echo "Server OK (timeout expected)"
|
||||
|
||||
# You should see MCP protocol initialization (Ctrl+C to exit)
|
||||
# Should exit cleanly or timeout (both are normal)
|
||||
```
|
||||
|
||||
**Optional: Run Tests**
|
||||
|
||||
```bash
|
||||
# Install test dependencies
|
||||
pip3 install pytest
|
||||
|
||||
# Run MCP server tests (25 tests)
|
||||
python3 -m pytest tests/test_mcp_server.py -v
|
||||
|
||||
# Expected: 25 passed in ~0.3s
|
||||
```
|
||||
|
||||
### Step 3: Note Your Repository Path
|
||||
|
||||
342
docs/TEST_MCP_IN_CLAUDE_CODE.md
Normal file
342
docs/TEST_MCP_IN_CLAUDE_CODE.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# Testing MCP Server in Claude Code
|
||||
|
||||
This guide shows you how to test the Skill Seeker MCP server **through actual Claude Code** using the MCP protocol (not just Python function calls).
|
||||
|
||||
## Important: What We Tested vs What You Need to Test
|
||||
|
||||
### What I Tested (Python Direct Calls) ✅
|
||||
I tested the MCP server **functions** by calling them directly with Python:
|
||||
```python
|
||||
await server.list_configs_tool({})
|
||||
await server.generate_config_tool({...})
|
||||
```
|
||||
|
||||
This verified the **code works**, but didn't test the **MCP protocol integration**.
|
||||
|
||||
### What You Need to Test (Actual MCP Protocol) 🎯
|
||||
You need to test via **Claude Code** using the MCP protocol:
|
||||
```
|
||||
In Claude Code:
|
||||
> List all available configs
|
||||
> mcp__skill-seeker__list_configs
|
||||
```
|
||||
|
||||
This verifies the **full integration** works.
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### Step 1: Configure Claude Code
|
||||
|
||||
Create the MCP configuration file:
|
||||
|
||||
```bash
|
||||
# Create config directory
|
||||
mkdir -p ~/.config/claude-code
|
||||
|
||||
# Create/edit MCP configuration
|
||||
nano ~/.config/claude-code/mcp.json
|
||||
```
|
||||
|
||||
Add this configuration (replace `/path/to/` with your actual path):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"skill-seeker": {
|
||||
"command": "python3",
|
||||
"args": [
|
||||
"/mnt/1ece809a-2821-4f10-aecb-fcdf34760c0b/Git/Skill_Seekers/mcp/server.py"
|
||||
],
|
||||
"cwd": "/mnt/1ece809a-2821-4f10-aecb-fcdf34760c0b/Git/Skill_Seekers"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or use the setup script:
|
||||
```bash
|
||||
./setup_mcp.sh
|
||||
```
|
||||
|
||||
### Step 2: Restart Claude Code
|
||||
|
||||
**IMPORTANT:** Completely quit and restart Claude Code (don't just close the window).
|
||||
|
||||
### Step 3: Verify MCP Server Loaded
|
||||
|
||||
In Claude Code, check if the server loaded:
|
||||
|
||||
```
|
||||
Show me all available MCP tools
|
||||
```
|
||||
|
||||
You should see 6 tools with the prefix `mcp__skill-seeker__`:
|
||||
- `mcp__skill-seeker__list_configs`
|
||||
- `mcp__skill-seeker__generate_config`
|
||||
- `mcp__skill-seeker__validate_config`
|
||||
- `mcp__skill-seeker__estimate_pages`
|
||||
- `mcp__skill-seeker__scrape_docs`
|
||||
- `mcp__skill-seeker__package_skill`
|
||||
|
||||
## Testing All 6 MCP Tools
|
||||
|
||||
### Test 1: list_configs
|
||||
|
||||
**In Claude Code, type:**
|
||||
```
|
||||
List all available Skill Seeker configs
|
||||
```
|
||||
|
||||
**Or explicitly:**
|
||||
```
|
||||
Use mcp__skill-seeker__list_configs
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
📋 Available Configs:
|
||||
|
||||
• django.json
|
||||
• fastapi.json
|
||||
• godot.json
|
||||
• react.json
|
||||
• vue.json
|
||||
...
|
||||
```
|
||||
|
||||
### Test 2: generate_config
|
||||
|
||||
**In Claude Code, type:**
|
||||
```
|
||||
Generate a config for Astro documentation at https://docs.astro.build with max 15 pages
|
||||
```
|
||||
|
||||
**Or explicitly:**
|
||||
```
|
||||
Use mcp__skill-seeker__generate_config with:
|
||||
- name: astro-test
|
||||
- url: https://docs.astro.build
|
||||
- description: Astro framework testing
|
||||
- max_pages: 15
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✅ Config created: configs/astro-test.json
|
||||
```
|
||||
|
||||
### Test 3: validate_config
|
||||
|
||||
**In Claude Code, type:**
|
||||
```
|
||||
Validate the astro-test config
|
||||
```
|
||||
|
||||
**Or explicitly:**
|
||||
```
|
||||
Use mcp__skill-seeker__validate_config for configs/astro-test.json
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✅ Config is valid!
|
||||
Name: astro-test
|
||||
Base URL: https://docs.astro.build
|
||||
Max pages: 15
|
||||
```
|
||||
|
||||
### Test 4: estimate_pages
|
||||
|
||||
**In Claude Code, type:**
|
||||
```
|
||||
Estimate pages for the astro-test config
|
||||
```
|
||||
|
||||
**Or explicitly:**
|
||||
```
|
||||
Use mcp__skill-seeker__estimate_pages for configs/astro-test.json
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
📊 ESTIMATION RESULTS
|
||||
Estimated Total: ~25 pages
|
||||
Recommended max_pages: 75
|
||||
```
|
||||
|
||||
### Test 5: scrape_docs
|
||||
|
||||
**In Claude Code, type:**
|
||||
```
|
||||
Scrape docs using the astro-test config
|
||||
```
|
||||
|
||||
**Or explicitly:**
|
||||
```
|
||||
Use mcp__skill-seeker__scrape_docs with configs/astro-test.json
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✅ Skill built: output/astro-test/
|
||||
Scraped X pages
|
||||
Created Y categories
|
||||
```
|
||||
|
||||
### Test 6: package_skill
|
||||
|
||||
**In Claude Code, type:**
|
||||
```
|
||||
Package the astro-test skill
|
||||
```
|
||||
|
||||
**Or explicitly:**
|
||||
```
|
||||
Use mcp__skill-seeker__package_skill for output/astro-test/
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✅ Package created: output/astro-test.zip
|
||||
Size: X KB
|
||||
```
|
||||
|
||||
## Complete Workflow Test
|
||||
|
||||
Test the entire workflow in Claude Code with natural language:
|
||||
|
||||
```
|
||||
Step 1:
|
||||
> List all available configs
|
||||
|
||||
Step 2:
|
||||
> Generate config for Svelte at https://svelte.dev/docs with description "Svelte framework" and max 20 pages
|
||||
|
||||
Step 3:
|
||||
> Validate configs/svelte.json
|
||||
|
||||
Step 4:
|
||||
> Estimate pages for configs/svelte.json
|
||||
|
||||
Step 5:
|
||||
> Scrape docs using configs/svelte.json
|
||||
|
||||
Step 6:
|
||||
> Package skill at output/svelte/
|
||||
```
|
||||
|
||||
Expected result: `output/svelte.zip` ready to upload to Claude!
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Tools Not Appearing
|
||||
|
||||
**Symptoms:**
|
||||
- Claude Code doesn't recognize skill-seeker commands
|
||||
- No `mcp__skill-seeker__` tools listed
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Check configuration exists:
|
||||
```bash
|
||||
cat ~/.config/claude-code/mcp.json
|
||||
```
|
||||
|
||||
2. Verify server can start:
|
||||
```bash
|
||||
cd /path/to/Skill_Seekers
|
||||
python3 mcp/server.py
|
||||
# Should start without errors (Ctrl+C to exit)
|
||||
```
|
||||
|
||||
3. Check dependencies installed:
|
||||
```bash
|
||||
pip3 list | grep mcp
|
||||
# Should show: mcp x.x.x
|
||||
```
|
||||
|
||||
4. Completely restart Claude Code (quit and reopen)
|
||||
|
||||
5. Check Claude Code logs:
|
||||
- macOS: `~/Library/Logs/Claude Code/`
|
||||
- Linux: `~/.config/claude-code/logs/`
|
||||
|
||||
### Issue: "Permission Denied"
|
||||
|
||||
```bash
|
||||
chmod +x mcp/server.py
|
||||
```
|
||||
|
||||
### Issue: "Module Not Found"
|
||||
|
||||
```bash
|
||||
pip3 install -r mcp/requirements.txt
|
||||
pip3 install requests beautifulsoup4
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Use this checklist to verify MCP integration:
|
||||
|
||||
- [ ] Configuration file created at `~/.config/claude-code/mcp.json`
|
||||
- [ ] Repository path in config is absolute and correct
|
||||
- [ ] Python dependencies installed (`mcp`, `requests`, `beautifulsoup4`)
|
||||
- [ ] Server starts without errors when run manually
|
||||
- [ ] Claude Code completely restarted (quit and reopened)
|
||||
- [ ] Tools appear when asking "show me all MCP tools"
|
||||
- [ ] Tools have `mcp__skill-seeker__` prefix
|
||||
- [ ] Can list configs successfully
|
||||
- [ ] Can generate a test config
|
||||
- [ ] Can scrape and package a small skill
|
||||
|
||||
## What Makes This Different from My Tests
|
||||
|
||||
| What I Tested | What You Should Test |
|
||||
|---------------|---------------------|
|
||||
| Python function calls | Claude Code MCP protocol |
|
||||
| `await server.list_configs_tool({})` | Natural language in Claude Code |
|
||||
| Direct Python imports | Full MCP server integration |
|
||||
| Validates code works | Validates Claude Code integration |
|
||||
| Quick unit testing | Real-world usage testing |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ **MCP Integration is Working When:**
|
||||
|
||||
1. You can ask Claude Code to "list all available configs"
|
||||
2. Claude Code responds with the actual config list
|
||||
3. You can generate, validate, scrape, and package skills
|
||||
4. All through natural language commands in Claude Code
|
||||
5. No Python code needed - just conversation!
|
||||
|
||||
## Next Steps After Successful Testing
|
||||
|
||||
Once MCP integration works:
|
||||
|
||||
1. **Create your first skill:**
|
||||
```
|
||||
> Generate config for TailwindCSS at https://tailwindcss.com/docs
|
||||
> Scrape docs using configs/tailwind.json
|
||||
> Package skill at output/tailwind/
|
||||
```
|
||||
|
||||
2. **Upload to Claude:**
|
||||
- Take the generated `.zip` file
|
||||
- Upload to Claude.ai
|
||||
- Start using your new skill!
|
||||
|
||||
3. **Share feedback:**
|
||||
- Report any issues on GitHub
|
||||
- Share successful skills created
|
||||
- Suggest improvements
|
||||
|
||||
## Reference
|
||||
|
||||
- **Full Setup Guide:** [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
|
||||
- **MCP Documentation:** [mcp/README.md](mcp/README.md)
|
||||
- **Main README:** [README.md](README.md)
|
||||
- **Setup Script:** `./setup_mcp.sh`
|
||||
|
||||
---
|
||||
|
||||
**Important:** This document is for testing the **actual MCP protocol integration** with Claude Code, not just the Python functions. Make sure you're testing through Claude Code's UI, not Python scripts!
|
||||
Reference in New Issue
Block a user