Project Standardization & Automation for @j0kz/mcp-agents
Ensure consistency across monorepo using automated scripts and established patterns.
4 Critical Rules (NEVER VIOLATE)
Rule 1: version.json is Single Source of Truth
- ❌ NEVER manually edit package.json versions
- ✅ ALWAYS use:
npm run version:sync - 11 packages must stay in sync
Rule 2: URL Casing Rules
- GitHub:
j0KZ(capital K, Z) - npm:
@j0kz(lowercase) - Mixing breaks links and installations
Rule 3: Test Count Automation
- ❌ NEVER manually edit test badges
- ✅ ALWAYS use:
npm run update:test-count - Currently: 632 tests passing
Rule 4: @latest in Documentation
- ❌ WRONG:
npx @j0kz/mcp-agents@1.0.36 - ✅ RIGHT:
npx @j0kz/mcp-agents@latest
Quick Command Reference
# Version management
npm run version:sync # Sync all versions from version.json
npm run version:check-shared # Verify shared package versions
# Testing
npm test # Run all tests
npm run update:test-count # Update test count in docs
# Building
npm run build # Build all packages
npm run dev # Watch mode
# Publishing
npm run publish-all # Publish all packages
Version Management Workflow
Quick Start: New Release
# 1. Update version.json
echo '{"version": "1.1.0"}' > version.json
# 2. Sync and build
npm run version:sync
npm run version:check-shared
npm test
npm run build
# 3. Publish
npm run publish-all
cd installer && npm publish && cd ..
# 4. Git operations
git add . && git commit -m "release: v1.1.0"
git tag v1.1.0 && git push origin main --tags
For detailed release workflow with all steps:
cat .claude/skills/project-standardization/references/version-management-guide.md
Test Count Management
# After adding/removing tests
npm run update:test-count
# Updates 3 files automatically:
# - README.md badge
# - wiki/Home.md badge and table
# - CHANGELOG.md metrics
For test automation details and patterns:
cat .claude/skills/project-standardization/references/test-automation-guide.md
URL & Link Standards
Critical: GitHub uses j0KZ, npm uses @j0kz
For complete URL standards and examples:
cat .claude/skills/project-standardization/references/url-standards-guide.md
tools.json Management
Location: tools.json at repository root - Single source of truth for all MCP tool metadata
When to update:
- Adding new MCP tool
- Changing tool features/descriptions
- Adding new category
Structure includes: tool id, name, package, description, category, features, wikiPage
Workspace Management
Adding New Package
mkdir packages/new-tool
npm install # Auto-discovers workspace
npm ls --workspaces # Verify recognized
Dependency Installation
npm install typescript -w packages/new-tool # Specific workspace
npm install typescript --workspaces # All workspaces
npm install vitest -D # Root only
Common Mistakes and Quick Fixes
| Mistake | Fix |
|---|---|
| Manually edited package.json version | npm run version:sync |
| Hardcoded version instead of @latest | Use @latest in docs |
| Wrong URL casing (GitHub/npm) | GitHub: j0KZ, npm: @j0kz |
| Manually updated test count | npm run update:test-count |
| Forgot to sync after version.json change | Always run version:sync first |
Validation & Checklists
For complete validation checklists (pre-commit, pre-publish, post-publish):
cat .claude/skills/project-standardization/references/validation-checklists.md
Key File Locations
version.json # Single source of truth for versions
tools.json # MCP tool metadata
scripts/sync-versions.js # Version sync automation
scripts/update-test-count.js # Test count automation
scripts/enforce-shared-version.js # Shared version validation
Getting Help
# Check current state
cat version.json # Current version
npm run version:check-shared # Package consistency
git status # Uncommitted changes
# Review scripts
ls scripts/ # List all automation
cat scripts/sync-versions.js # Read script details
Related Skills
- monorepo-package-workflow: Creating new MCP packages
- release-publishing-workflow: Complete release process
- git-pr-workflow: Git operations and PR creation
Additional Resources
- CLAUDE.md: Repository-wide standards and patterns
- Wiki: https://github.com/j0KZ/mcp-agents/wiki
Converted and distributed by TomeVault — claim your Tome and manage your conversions.