Monorepo Package Creation for @j0kz/mcp-agents

Create new MCP tool packages following established patterns from the 9 existing tools.

Prerequisites Checklist

• Tool purpose clearly defined and unique
• No duplicate functionality in existing tools (check tools.json)
• Tool fits one category: analysis, generation, refactoring, design, orchestration
• Name follows pattern: @j0kz/{tool-name}-mcp

Quick Start: Create New Package

# 1. Create structure
cd packages
mkdir -p your-tool/src/{constants,helpers,utils}
mkdir your-tool/tests

# 2. Initialize package.json (copy template below)
# 3. Create thin mcp-server.ts (<150 LOC)
# 4. Implement main-logic.ts with @j0kz/shared
# 5. Register in tools.json
# 6. Sync version: npm run version:sync
# 7. Build and test

Package Structure (Modular Architecture)

your-tool/
├── src/
│   ├── mcp-server.ts      # Thin MCP layer (<150 LOC)
│   ├── main-logic.ts      # Core functionality
│   ├── types.ts           # TypeScript interfaces
│   ├── constants/         # Thresholds, patterns
│   ├── helpers/           # Complex logic (30+ LOC)
│   └── utils/             # Cross-cutting utilities
├── tests/                 # Vitest tests
├── package.json           # With "type": "module"
└── tsconfig.json

Target: All files <300 LOC (extract when exceeded)

For detailed structure guide:

cat .claude/skills/monorepo-package-workflow/references/package-structure-guide.md

Critical package.json Template

{
  "name": "@j0kz/your-tool-mcp",
  "version": "1.1.0",  // From version.json
  "type": "module",    // CRITICAL: ES modules
  "main": "./dist/index.js",
  "bin": {
    "your-tool-mcp": "dist/mcp-server.js"
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "test:coverage": "vitest run --coverage"
  },
  "dependencies": {
    "@j0kz/shared": "^1.1.0",  // Must match version
    "@modelcontextprotocol/sdk": "^1.19.1"
  }
}

MCP Server Pattern (Thin Orchestration)

// mcp-server.ts - ONLY protocol handling
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { handleYourTool } from './main-logic.js';  // .js extension!

// Setup server (thin, delegates all logic)
// Target: <150 LOC

For complete MCP patterns:

cat .claude/skills/monorepo-package-workflow/references/mcp-server-patterns.md

Using @j0kz/shared Utilities

import {
  FileSystemManager,   // File ops with caching
  AnalysisCache,       // LRU cache (30min TTL)
  PerformanceMonitor,  // Performance tracking
  MCPPipeline         // Tool chaining
} from '@j0kz/shared';

For shared utilities guide:

cat .claude/skills/monorepo-package-workflow/references/shared-utilities-guide.md

Registration & Version Sync

1. Register in tools.json

{
  "id": "your-tool",
  "name": "Your Tool Name",
  "package": "@j0kz/your-tool-mcp",
  "category": "analysis",
  "features": ["Feature 1", "Feature 2", "Feature 3"]
}

2. Sync Version (CRITICAL!)

# Never manually edit version in package.json!
npm run version:sync          # Updates all packages
npm run version:check-shared  # Verify consistency

Testing with Vitest

// tests/main-logic.test.ts
import { describe, it, expect } from 'vitest';
import { handleYourTool } from '../src/main-logic.js';

describe('YourTool', () => {
  it('should handle valid input', async () => {
    const result = await handleYourTool({ filePath: 'test.ts' });
    expect(result.success).toBe(true);
  });
});

Target: >70% coverage

For testing setup guide:

cat .claude/skills/monorepo-package-workflow/references/testing-setup-guide.md

Import Pattern (ES Modules)

// ✅ CORRECT - Always use .js
import { foo } from './bar.js';
import { helper } from './helpers/my-helper.js';

// ❌ WRONG - Will fail
import { foo } from './bar';
import { foo } from './bar.ts';

Build & Validation

# Build TypeScript
npm run build -w packages/your-tool

# Verify structure
ls dist/  # Should have .js files

# Run tests
npm test -w packages/your-tool

# Check file sizes
find src -name "*.ts" -exec wc -l {} \; | sort -n
# All should be <300 LOC

Complete Registration Checklist

For detailed checklist with all steps:

cat .claude/skills/monorepo-package-workflow/references/registration-checklist.md

Quick validation:

• Package name: @j0kz/{tool}-mcp
• Registered in tools.json
• Version synced from version.json
• mcp-server.ts <150 LOC
• All files <300 LOC
• Tests >70% coverage
• Imports use .js extension
• "type": "module" in package.json

Common Mistakes to Avoid

Mistake	Fix
Manually set version	Use npm run version:sync
Forget tools.json	Register before publishing
Fat mcp-server.ts	Keep <150 LOC, delegate to main-logic
Missing .js extension	Add to all relative imports
Files >300 LOC	Extract to constants/helpers/utils

Reference Examples

Study these well-structured packages:

1. security-scanner - Best modular refactoring (395→209 LOC)
2. smart-reviewer - AST analysis with fixers/
3. orchestrator-mcp - MCPPipeline usage
4. test-generator - Code generation patterns

Publishing Workflow

# 1. Build all
npm run build

# 2. Publish
npm run publish-all

# 3. Git operations
git add . && git commit -m "feat: add your-tool"
git tag v1.1.0 && git push --tags

Related Skills

• project-standardization: Version management and automation
• modular-refactoring-pattern: Reducing file complexity
• code-quality-pipeline: Ensuring code quality

Quick Commands

npm run version:sync       # Sync versions
npm run build              # Build all packages
npm test                   # Run tests
npm run publish-all        # Publish to npm

---

For modular refactoring: .claude/skills/modular-refactoring-pattern/SKILL.md For project standards: .claude/skills/project-standardization/SKILL.md