gateway
MCP Gateway for exposing VAT agents through Model Context Protocol
Installation
npx @vibe-agent-toolkit/gateway-mcpAsk AI about gateway
Powered by Claude Β· Grounded in docs
I know everything about gateway. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Vibe Agent Toolkit
A toolkit for testing and packaging portable AI agents that work across various LLMs, frameworks, deployment targets, and orchestrators.
Features
Agent Development
- π€ Multi-LLM Support - Build agents that work with Claude, GPT, and other LLMs
- π Framework Agnostic - Support for various agent frameworks
- π¦ Portable Packaging - Deploy across different orchestrators and platforms
- β Agent Testing - Comprehensive testing for agent behaviors and interactions
- π Agent Skills Validation - Audit skills for quality, compatibility, and best practices
- π©Ί Environment Diagnostics - Doctor command checks setup and health
Skills Distribution
- π¦ VAT Distribution Standard - Package-based distribution for skills, agents, and tools
- π¨ Build Infrastructure -
vat skills buildcreates distributable skill packages - β¬οΈ Smart Installation - Install skills from npm, local directories, or zip files
- π Registry Tracking - Track installed skills for updates and management
- π― Multi-Artifact Support - Distribute skills, agents, pure functions, and runtimes together
Install skills:
vat skills install npm:@vibe-agent-toolkit/vat-example-cat-agents
vat skills install ./path/to/local/package
vat skills list --installed
See Distributing VAT Skills Guide for creating your own distributable packages.
Claude Plugin Marketplace
VAT skills are available as a Claude Code plugin β install them directly from GitHub, no npm needed:
claude plugin marketplace add jdutton/vibe-agent-toolkit#claude-marketplace
claude plugin install vibe-agent-toolkit@vat-skills
Or from within a Claude Code session:
/plugin marketplace add jdutton/vibe-agent-toolkit#claude-marketplace
/plugin install vibe-agent-toolkit@vat-skills
For project-scope (shared with team via .claude/settings.json), add --scope project:
claude plugin marketplace add jdutton/vibe-agent-toolkit#claude-marketplace --scope project
This gives Claude Code 8 skills for building, packaging, and distributing agent skills. See the marketplace branch for the full skill list.
Pre-release channel: To track the latest pre-release builds, use #claude-marketplace-next instead.
Build your own marketplace: VAT can publish your skills as a Claude plugin marketplace too. See the Marketplace Distribution Guide for how marketplace publishing works β from project structure through build, validation, publishing, and testing.
Plugin & Marketplace Audit
Comprehensive validation for Claude plugins, marketplaces, and configurations:
# Audit user-level Claude plugins
vat audit --user
# Audit specific plugin
vat audit ./my-plugin
# Recursive scan for all resources
vat audit ./resources --recursive
Features:
- Auto-detects resource type (plugin, marketplace, skill, registry)
- Schema validation using Zod
- Cache staleness detection using checksums
- Hierarchical output showing relationships
- Cross-platform support
See Audit Documentation for complete reference.
Development Infrastructure
- π Bun - Fast package manager and runtime
- π¦ Monorepo - Workspace-based package management for agent components
- π TypeScript - Strict type checking with composite projects
- β Vitest - Fast unit, integration, and system testing
- π ESLint - Maximum strictness with sonarjs, unicorn, and security plugins
- π Code Coverage - 80% minimum threshold with Codecov integration
- π― vibe-validate - Git-aware validation orchestration
- π§ Cross-Platform - Tested on Windows, macOS, and Linux
- π€ CI/CD - GitHub Actions with Node 22/24 matrix testing
Quick Start
CLI Installation
Install the CLI globally:
npm install -g vibe-agent-toolkit
Scan and validate markdown resources:
vat resources scan docs/
vat resources validate docs/
Audit and import Agent Skills:
vat agent audit my-skill/SKILL.md
vat agent import my-skill/SKILL.md
Diagnose project setup:
vat doctor
See CLI Reference for complete documentation (or run vat --help --verbose).
Development Setup
Prerequisites:
- Bun (latest version)
- Node.js 22 or 24
- Git
Installation:
# Clone the repository
git clone https://github.com/jdutton/vibe-agent-toolkit.git
cd vibe-agent-toolkit
# Install dependencies
bun install
# Build all packages
bun run build
Development
# Run full validation (recommended)
bunx vv validate
# Or run test suites individually:
bun run test:unit # Unit tests only
bun run test:watch # Watch mode for development
bun run test:integration # Integration tests
bun run test:system # System/e2e tests
# Lint code
bun run lint
# Type check
bun run typecheck
# Validate all markdown links (dogfooding)
bun run validate-links
π Dogfooding: Link Validation
This project uses its own @vibe-agent-toolkit/resources package to validate all markdown links in the repository. This ensures our documentation stays accurate and all links remain valid.
Run link validation:
bun run validate-links
What it checks:
- β All local file links (relative paths to other markdown files)
- β All heading anchor links (links to sections within files)
- βΉοΈ External URLs are noted but not validated
- π« Test fixtures with intentionally broken links are excluded
Runs automatically in CI/CD as part of the System Tests phase, ensuring broken links are caught before merge.
External URL Validation
Optionally validate external URLs with caching:
vat resources validate docs/ --check-external-urls
See External URL Validation for details.
Project Structure
vibe-agent-toolkit/
βββ packages/ # Published packages
β βββ example-utils/ # Example package (replace with your packages)
β βββ src/ # Source code
β βββ test/ # Tests
β βββ package.json
β βββ tsconfig.json
βββ tools/ # Development tools (TypeScript)
β βββ common.ts # Shared utilities
β βββ duplication-check.ts
β βββ jscpd-check-new.ts
β βββ jscpd-update-baseline.ts
βββ docs/ # Documentation
βββ .github/ # CI/CD workflows
β βββ workflows/
β βββ validate.yml # Validation pipeline
βββ eslint.config.js # ESLint configuration (strict!)
βββ vitest.config.ts # Unit test configuration
βββ vitest.integration.config.ts # Integration test config
βββ vitest.system.config.ts # System test config
βββ tsconfig.json # Root TypeScript config
βββ tsconfig.base.json # Base config for packages
βββ vibe-validate.config.yaml # Validation orchestration
βββ package.json # Root package.json
βββ CLAUDE.md # AI assistant guidelines
βββ README.md # This file
Adding a New Package
- Create the package directory:
mkdir -p packages/my-package/src packages/my-package/test
- Create
packages/my-package/package.json:
{
"name": "@your-org/my-package",
"version": "0.1.0",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"scripts": {
"build": "tsc",
"test": "vitest run",
"test:watch": "vitest",
"typecheck": "tsc --noEmit",
"clean": "rm -rf dist *.tsbuildinfo"
},
"devDependencies": {
"typescript": "^5.9.3",
"vitest": "^3.2.4"
}
}
- Create
packages/my-package/tsconfig.json:
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}
- Add to root
tsconfig.jsonreferences:
{
"references": [
{ "path": "./packages/example-utils" },
{ "path": "./packages/my-package" } // Add this
]
}
- Create source and tests:
# Create your source files
touch packages/my-package/src/index.ts
# Create tests
touch packages/my-package/test/index.test.ts
- Install and build:
bun install
bun run build
Testing Strategy
Test Types
The toolkit supports three levels of testing:
Unit Tests (*.test.ts)
- Test individual functions/classes
- Fast execution (< 100ms)
- Mock external dependencies
- Run with:
bun test
Integration Tests (*.integration.test.ts)
- Test multiple modules together
- May use real dependencies
- Medium execution (< 5s)
- Run with:
bun test:integration
System Tests (*.system.test.ts)
- End-to-end workflows
- Real external services
- Longer execution (< 30s)
- Run with:
bun test:system
Test File Organization
packages/my-package/
βββ src/
β βββ utils.ts
β βββ utils.test.ts # Unit tests (co-located)
βββ test/
βββ api.test.ts # Unit tests
βββ integration/
β βββ workflow.integration.test.ts
βββ system/
βββ e2e.system.test.ts
Quality Standards
ESLint
The toolkit enforces strict linting rules:
- Zero warnings policy:
--max-warnings=0 - SonarJS: Catches code smells and bugs
- Unicorn: Modern JavaScript patterns
- Security: Prevents common vulnerabilities
- Import organization: Alphabetical with groups
All code (src, tests, tools) is held to the same standards.
Code Coverage
Minimum thresholds enforced:
- Statements: 80%
- Branches: 80%
- Functions: 80%
- Lines: 80%
Code Duplication
Uses jscpd with a baseline approach:
- Existing duplication is baselined
- New duplication blocks commits
- Update baseline:
bun run duplication-update-baseline
TypeScript
Strict mode enabled with additional checks:
noUncheckedIndexedAccessnoImplicitOverrideexactOptionalPropertyTypes
Validation Pipeline
The toolkit uses vibe-validate for git-aware validation:
# Run all validation checks
bun run validate
# Pre-commit check (fast)
bun run pre-commit
Validation runs:
- TypeScript type checking
- ESLint (strict)
- Code duplication check
- Build
- Unit tests
- Integration tests (optional)
- Coverage report
- System tests (optional)
CI/CD
GitHub Actions workflows run on every push/PR:
Validation Pipeline
- Matrix Testing: Node 22/24 Γ Ubuntu/Windows
- Full Validation: All checks must pass
- Parallel Execution: Faster feedback
- See
.github/workflows/validate.yml
Coverage Reporting
- Codecov Integration: Automatic coverage upload
- 80% Threshold: Project and patch coverage targets
- PR Comments: Coverage diff on pull requests
- See
.github/workflows/coverage.yml
Setting up Codecov
- Sign up at codecov.io with your GitHub account
- Enable your repository
- Add
CODECOV_TOKENto GitHub repository secrets - Coverage reports will be uploaded automatically on push/PR
- Update badge URLs in README.md with your repository details
Pre-commit Hooks
Husky is configured to run validation before commits:
# Install hooks
bun install # Runs automatically via "prepare" script
# Manually run pre-commit checks
bun run pre-commit
Publishing Packages
When you're ready to publish to npm:
- Update package versions
- Build packages:
bun run build - Test thoroughly:
bun run validate - Publish:
npm publish(or create publish scripts)
Customization
Changing the Organization Scope
Replace @vibe-agent-toolkit with your org name:
# Update package names in:
# - packages/*/package.json
# - Import statements
Adjusting Quality Thresholds
Edit these files:
vitest.config.ts- Coverage thresholdseslint.config.js- Linting rulesvibe-validate.config.yaml- Validation steps
Adding Tools
Add scripts to packages/dev-tools/src/ directory:
- Use TypeScript (cross-platform)
- Import from
common.ts - Add to package.json scripts
Validation
The project includes comprehensive validation checks:
# Run all validation checks
bun run validate
# Run pre-commit checks
bun run pre-commit
The example package (packages/example-utils/) demonstrates testing patterns and will be replaced with agent-specific packages.
Learn More
- Getting Started - Detailed setup guide
- Documentation - Full documentation index
- Bun Documentation
- Vitest Documentation
- vibe-validate
- TypeScript
License
MIT - see LICENSE file
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run
bun run validateto ensure quality - Submit a pull request
Built with β€οΈ using Bun, TypeScript, and modern tooling
