Context7 MCP integration for aiknowsys - validate skills and ESSENTIALS against current library documentation
npm install aiknowsys-plugin-context7> Context7 MCP integration for aiknowsys - automated deliverable validation and documentation queries


A plugin for aiknowsys that adds Context7 MCP integration for:
- Automated validation of skills, CODEBASE_ESSENTIALS.md, and stack templates against current library versions
- Ad-hoc documentation queries using Context7's up-to-date library knowledge
- Breaking change detection when frameworks release new versions
Prerequisites:
- aiknowsys v0.8.0 or higher
- Context7 MCP server configured
``bash`
npm install aiknowsys-plugin-context7
The plugin will be automatically discovered by aiknowsys.
Check if your skills, CODEBASE_ESSENTIALS.md, and stack templates use current best practices:
`bashValidate skills + CODEBASE_ESSENTIALS.md (default)
npx aiknowsys validate
Output Example:
`
Project Validation Report
==================================================Total items validated: 13
✓ Current (11):
- dependency-updates
- code-refactoring
- testing-best-practices
... (8 more)
⚠ Outdated (2):
- nextjs-stack (uses deprecated getServerSideProps)
Suggestion: Migrate to async server components
- vue-stack (uses Options API exclusively)
Suggestion: Add Composition API examples
Validation Score: 85% (11/13 current)
`$3
Ask questions about library documentation:
`bash
Query with library and question
npx aiknowsys query-docs --library nextjs --query "How to implement middleware?"Short form (library name normalization)
npx aiknowsys query-docs -l "Next.js" -q "Server actions best practices"Get JSON output
npx aiknowsys query-docs -l react -q "useEffect cleanup" --format jsonGet markdown output
npx aiknowsys query-docs -l vue -q "composables" --format markdown
`Output Example:
`
Documentation Query
==================================================Library: Next.js
Library ID: /vercel/next.js
Query: How to implement middleware?
Documentation:
--------------------------------------------------
Next.js middleware allows you to run code before a request
is completed. Middleware runs on every route by default,
or you can specify matchers...
[Full documentation response from Context7]
`How It Works
$3
1. Discovery: Plugin scans your
.github/skills/ and templates/stacks/ directories
2. Library Detection: Extracts framework/library references (Next.js, Vue, Django, etc.)
3. Context7 Queries: Uses MCP to fetch current documentation and patterns
4. Validation: Compares your deliverables against current best practices
5. Report: Shows outdated patterns, breaking changes, and suggestions$3
1. Library Normalization: Converts "Next.js", "NextJS", "nextjs" to standard format
2. Library ID Resolution: Maps to Context7 library ID (e.g.,
/vercel/next.js)
3. Documentation Query: Fetches relevant docs from Context7 MCP server
4. Formatting: Outputs in text, JSON, or markdown formatMock Mode (Default)
Important: The plugin runs in mock mode by default for standalone CLI usage.
Mock mode enables:
- ✅ Testing without Context7 MCP server
- ✅ CI/CD integration without external dependencies
- ✅ Fast local development
Mock mode simulates Context7 responses for common libraries (Next.js, Vue, React).
For real Context7 integration: AI assistants (Claude, GPT) access Context7 directly via MCP. This plugin's primary use case is validation workflows, not real-time queries.
Configuration
$3
If you're using this plugin through an AI assistant (Claude Desktop, etc.), Context7 integration happens automatically via MCP configuration.
$3
No configuration needed - mock mode works out of the box.
$3
To connect to a real Context7 MCP server:
1. Install Context7 server: Context7 Setup Guide
2. Configure MCP server connection (future feature - see TODO in code)
3. Set
useMockClient = false in lib/query-docs.jsNote: Real MCP integration is planned but not required for main use cases.
API Reference
$3
Validate aiknowsys skills, CODEBASE_ESSENTIALS.md, and stack templates against current library documentation.
Options:
-
--type - Filter by deliverable type (skills|essentials|stacks|all) [default: all = skills + essentials]
- --library - Filter by specific library (e.g., nextjs, vue, react)
- --format - Output format (text|json|markdown) [default: text]Use Cases:
1. Validate User Project (default - skills + ESSENTIALS):
`bash
npx aiknowsys validate
# Checks .github/skills/ and CODEBASE_ESSENTIALS.md
`2. Validate Only CODEBASE_ESSENTIALS.md:
`bash
npx aiknowsys validate --type essentials
# Checks technologies listed in Section 1: Technology Snapshot
`3. Validate Stack Templates (aiknowsys maintainers):
`bash
npx aiknowsys validate --type stacks
# Checks templates/stacks/ directory
`Example Outputs:
Text Format (default):
`
Project Validation Report
==================================================
Total items validated: 13
✓ Current (11)
⚠ Outdated (2)
Validation Score: 85%
`JSON Format:
`json
{
"items": [
{
"name": "nextjs-stack",
"type": "stack",
"libraries": ["nextjs"],
"status": "outdated",
"issues": ["Uses deprecated getServerSideProps"],
"suggestions": ["Migrate to async server components"]
}
],
"summary": {
"total": 13,
"current": 11,
"outdated": 2,
"score": 0.85
}
}
`$3
Query library documentation via Context7 MCP.
Options:
-
-l, --library - Library name (required)
- -q, --query - Documentation query (required)
- --format - Output format (text|json|markdown) [default: text]Library Name Normalization:
The following inputs are equivalent:
-
"Next.js" → nextjs
- "NextJS" → nextjs
- "next.js" → nextjs
- "Vue" → vue
- "React" → reactExample Outputs:
Text Format:
`
Documentation Query
==================================================
Library: Next.js
Library ID: /vercel/next.js
Query: How to implement middleware?Documentation:
--------------------------------------------------
[Documentation content from Context7]
`JSON Format:
`json
{
"library": "Next.js",
"libraryId": "/vercel/next.js",
"query": "How to implement middleware?",
"documentation": "...",
"timestamp": "2026-02-01T20:15:00.000Z",
"success": true
}
`Use Cases
$3
Run validation before major releases:
`bash
Generate full validation report
npx aiknowsys validate --format markdown > reports/validation-$(date +%Y-%m).mdCommit report to track quality over time
git add reports/
git commit -m "docs: Monthly validation report"
`$3
Check if your CODEBASE_ESSENTIALS.md patterns need updates after package upgrades:
`bash
After npm update or package.json changes
npx aiknowsys validate --type essentialsCheck specific library for breaking changes
npx aiknowsys validate --library nextjs
npx aiknowsys query-docs -l nextjs -q "What changed in latest version?" --format markdown
`Automate with postinstall script (package.json):
`json
{
"scripts": {
"postinstall": "npx aiknowsys validate --type essentials || echo 'Warning: Dependencies may need pattern updates'"
}
}
`$3
Check if your docs need updates after framework releases:
`bash
Check Next.js patterns after v15 release
npx aiknowsys validate --library nextjsGet detailed changelog comparison
npx aiknowsys query-docs -l nextjs -q "What changed in v15?" --format markdown
`$3
Add validation to your GitHub Actions:
`yaml
.github/workflows/validate.yml
name: Validate Documentation
on: [push, pull_request]jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm install aiknowsys aiknowsys-plugin-context7
- run: npx aiknowsys validate --format json > validation.json
- run: |
# Fail if validation score < 80%
node -e "
const report = require('./validation.json');
if (report.summary.score < 0.8) {
console.error('Validation score too low:', report.summary.score);
process.exit(1);
}
"
`$3
Quick checks while writing docs:
`bash
Verify current best practice before documenting
npx aiknowsys query-docs -l vue -q "composables vs mixins" --format markdownCheck if pattern is deprecated
npx aiknowsys query-docs -l react -q "class components still supported?"
`$3
Automatically validate your CODEBASE_ESSENTIALS.md when dependencies change:
#### 1. Postinstall Hook (Recommended)
Add to your
package.json:`json
{
"scripts": {
"postinstall": "npx aiknowsys validate --type essentials || echo 'Warning: Check CODEBASE_ESSENTIALS.md for deprecated patterns'"
}
}
`Triggers:
- After
npm install
- After npm update
- After adding new dependencies
- On CI/CD npm ci#### 2. Git Hook (Post-Merge)
Detect package.json changes after pulling/merging:
`bash
.github/hooks/post-merge
#!/bin/bash
if git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD | grep --quiet 'package.json\|package-lock.json'; then
echo "Dependencies changed - validating ESSENTIALS..."
npx aiknowsys validate --type essentials
fi
`#### 3. Monthly Scheduled Validation
For projects with infrequent dependency updates:
`bash
crontab -e
0 9 1 cd /path/to/project && npx aiknowsys validate --type essentials --format markdown > reports/monthly-validation.md
`#### 4. CI/CD Pipeline
Add to
.github/workflows/validate.yml:`yaml
on:
pull_request:
paths:
- 'package.json'
- 'package-lock.json'
- 'requirements.txt'
- 'pyproject.toml'jobs:
validate-essentials:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install aiknowsys-plugin-context7
- run: npx aiknowsys validate --type essentials --format json
- name: Comment on PR if outdated
if: failure()
run: echo "CODEBASE_ESSENTIALS.md may need updates after dependency changes"
`Supported Package Managers:
- npm / yarn (package.json, package-lock.json, yarn.lock)
- Python (requirements.txt, pyproject.toml, poetry.lock, Pipfile)
Troubleshooting
$3
Problem: Query returns "Library not found" error
Solutions:
1. Check library name spelling (use
--library nextjs not --library next)
2. Library normalization: "Next.js" → "nextjs", "Vue.js" → "vue"
3. Try exact library ID: npx aiknowsys query-docs -l "/vercel/next.js" -q "..."$3
Problem:
validate reports 0 items foundSolutions:
1. Run from project root (where
.github/ or CODEBASE_ESSENTIALS.md exists)
2. Check directory structure: .github/skills/ for skills, root for ESSENTIALS
3. Ensure SKILL.md files exist in skill directories
4. For essentials: Verify CODEBASE_ESSENTIALS.md has "## 1. Technology Snapshot" section$3
Question: How do I use real Context7 instead of mock mode?
Answer:
Mock mode is intentional for standalone CLI usage. For real Context7 integration:
- AI assistants (Claude, GPT) access Context7 directly via their MCP config
- Plugin validation uses mock mode for CI/CD workflows
- Real MCP integration is a future enhancement (see TODO in code)
Development
`bash
Clone the plugin
git clone https://github.com/arpa73/aiknowsys-plugin-context7.git
cd aiknowsys-plugin-context7Install dependencies
npm installRun tests
npm testLint code
npm run lint
``Contributions welcome! Please:
1. Follow the aiknowsys Contributing Guide
2. Write tests for new features
3. Update documentation
MIT © arpa73
- aiknowsys - AI-powered development workflow
- Context7 MCP - Library documentation server
- MCP SDK - Model Context Protocol SDK