MCP Serverjosharshpublic
mcp jest
Automated testing for Model Context Protocol servers. Ship MCP Servers with confidence.
Repository Info
4
Stars
0
Forks
4
Watchers
2
Issues
JavaScript
Language
MIT License
License
About This Server
Automated testing for Model Context Protocol servers. Ship MCP Servers with confidence.
Model Context Protocol (MCP) - This server can be integrated with AI applications to provide additional context and capabilities, enabling enhanced AI interactions and functionality.
Documentation
MCP-Jest
The first (and perhaps only) testing framework for Model Context Protocol (MCP) servers - like Jest, but for MCP
🚀 Finally! Test your MCP servers with confidence. No more manual verification, no more broken deployments.
The Problem
You built an MCP server that connects AI assistants to your database, file system, or API. But how do you know it actually works?
npm install mcp-jest
Why mcp-jest?
The Problem 😤
Building MCP servers? You've probably experienced this:
- ❌ Manual Testing Hell: Manually connecting clients to test every change
- ❌ Silent Failures: Servers break and you don't know until Claude Code crashes
- ❌ No CI/CD: Can't automate MCP server testing in pipelines
- ❌ Debugging Nightmare: When things break, you have no idea what went wrong
- ❌ Fear of Deployment: Every update is a gamble
The Solution ✨
mcp-jest is the missing piece of the MCP ecosystem:
- ✅ Automated Testing: Write tests once, run them everywhere
- ✅ Instant Feedback: Know immediately when something breaks
- ✅ CI/CD Ready: Integrate seamlessly into any build pipeline
- ✅ Crystal Clear Results: Detailed reports show exactly what works and what doesn't
- ✅ Deploy with Confidence: Comprehensive testing before production
📋 Table of Contents
- Quick Start
- Features
- Documentation
- API Reference
- Examples
- Contributing
- Security
- License
⚡ Quick Start (30 seconds)
1. Install
npm install mcp-jest # As dependency
npm install -g mcp-jest # Or globally for CLI
2. Test Your Server
import { mcpTest } from 'mcp-jest';
const results = await mcpTest(
{ command: 'node', args: ['./server.js'] },
{ tools: ['search', 'email'] }
);
console.log(`${results.passed}/${results.total} tests passed`);
3. Or Use CLI
mcp-jest node ./server.js --tools search,email
That's it! Your MCP server is now tested. 🎉
🔥 Features That Matter
🧪 Dead Simple API
One function call tests your entire server. No complex setup, no boilerplate.
📝 Declarative Testing
Describe what to test, not how. Focus on your server logic, not test infrastructure.
🔍 Comprehensive Coverage
- Connection Testing: Server starts and responds
- Capability Discovery: Tools/resources/prompts exist
- Functional Testing: Everything actually works
- Validation: Results match expectations
🚀 Built for Production
- CI/CD Integration: Works with GitHub Actions, Jenkins, etc.
- Fast Execution: Complete test suites in under 500ms
- Detailed Reporting: Know exactly what failed and why
- Zero Dependencies: Uses official MCP SDK only
🛠️ Flexible Usage
- Library: Integrate into existing test suites
- CLI: Perfect for scripts and pipelines
- Config Files: Complex test scenarios
- TypeScript: Full type safety included
📸 Snapshot Testing (NEW!)
- Capture Outputs: Save MCP responses as snapshots
- Detect Changes: Know when outputs change unexpectedly
- Easy Updates: Update snapshots with a single flag
- Selective Snapshots: Choose specific fields to track
🎯 Real-World Examples
Testing a Search Server
const results = await mcpTest(
{ command: 'python', args: ['search-server.py'] },
{
tools: {
search: {
args: { query: 'artificial intelligence' },
expect: result => result.results.length > 0
},
autocomplete: {
args: { partial: 'artif' },
expect: 'suggestions.length >= 3'
}
}
}
);
CI/CD Integration
# .github/workflows/test.yml
- name: Test MCP Server
run: |
npm install -g mcp-jest
mcp-jest node ./dist/server.js --tools "search,analyze"
Development Workflow
{
"scripts": {
"test": "jest && npm run test:mcp",
"test:mcp": "mcp-jest node ./server.js --tools search,email",
"dev": "concurrently 'npm run dev:server' 'npm run test:mcp:watch'"
}
}
Snapshot Testing (NEW!)
// Capture and compare MCP outputs over time
const results = await mcpTest(
{ command: 'node', args: ['./weather-server.js'] },
{
tools: {
getWeather: {
args: { city: 'London' },
snapshot: {
exclude: ['temperature', 'timestamp'], // Exclude changing data
properties: ['format', 'units', 'structure'] // Track structure
}
}
}
}
);
// Update snapshots when changes are intentional
// mcp-jest node ./server.js --update-snapshots
🚀 Ecosystem Integration
Works With Everything
- MCP Servers: Any language, any framework
- AI Clients: Claude Code, custom clients, SDKs
- CI/CD: GitHub Actions, GitLab CI, Jenkins, CircleCI
- Package Managers: npm, pnpm, yarn
- Test Runners: Jest, Vitest, Mocha (as library)
Popular Use Cases
- Development: Test changes instantly during development
- CI/CD: Automated testing in build pipelines
- Deployment: Verify servers work before going live
- Monitoring: Regular health checks in production
- Documentation: Ensure examples actually work
The Problem It Solves
┌─────────────────────┐ ┌─────────────────────┐
│ │ │ │
│ MCP Server Dev │ ??? │ How do I know my │
│ Implements Tool │ ──────> │ server works? │
│ │ │ │
└─────────────────────┘ └─────────────────────┘
Before MCP-JEST: Manual testing, no automation, no confidence
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ │ │ │ │ │
│ MCP Server Dev │ ──────> │ MCP-JEST │ ──────> │ ✓ Automated Tests │
│ Implements Tool │ │ Test Framework │ │ ✓ CI/CD Ready │
│ │ │ │ │ ✓ Snapshot Testing │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
With MCP-JEST: Automated, repeatable, confident testing
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP-JEST Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CLI │ │ Library │ │ Types │ │
│ │ (cli.ts) │ │ (index.ts) │ │ (types.ts) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────────┴────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ MCPTestRunner │ │
│ │ (runner.ts) │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ │
│ │ MCPTestClient│ │SnapshotManager│ │ Expectation │ │
│ │ (client.ts) │ │ (snapshot.ts) │ │ Evaluator │ │
│ └──────┬───────┘ └───────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ MCP Protocol Communication │ │
│ │ (via @modelcontextprotocol/sdk) │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
└─────────────────────────────┼──────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ Your MCP Server │
│ (Being Tested) │
└─────────────────┘
MCP-JEST is Unique for its Protocol-Specific Design
┌─────────────────────────────────────────────────────────┐
│ Generic Testing vs MCP-JEST │
├─────────────────────────────────────────────────────────┤
│ │
│ Generic Test Framework: │
│ ┌─────────┐ │
│ │ Test │──[HTTP/Function Call]──> Response │
│ └─────────┘ │
│ │
│ MCP-JEST: │
│ ┌─────────┐ │
│ │ Test │ │
│ └────┬────┘ │
│ │ │
│ ├──[1. Process Management] │
│ ├──[2. StdioTransport Setup] │
│ ├──[3. MCP Protocol Handshake] │
│ ├──[4. Capability Discovery] │
│ ├──[5. Tool/Resource/Prompt Execution] │
│ └──[6. Structured Validation] │
│ │
└─────────────────────────────────────────────────────────┘
MCP-JEST is Unique for Comprehensive Test Coverage
┌────────────────────────────────────────────────┐
│ MCP-JEST Test Coverage │
├────────────────────────────────────────────────┤
│ │
│ Connection Layer: │
│ • Server startup │
│ • Protocol handshake │
│ • Timeout handling │
│ │
│ Discovery Layer: │
│ • Available tools │
│ • Available resources │
│ • Available prompts │
│ • Capability matching │
│ │
│ Functional Layer: │
│ • Tool execution with arguments │
│ • Resource reading │
│ • Prompt generation │
│ • Error handling │
│ │
│ Validation Layer: │
│ • Response structure │
│ • Content validation │
│ • Snapshot comparison │
│ • Custom expectations │
│ │
└────────────────────────────────────────────────┘
3. MCP-JEST is Unique for its Developer Experience
┌─────────────────────────────────────────────────┐
│ Developer Experience Flow │
├──────────────────────────────────────────────────┤
│ │
│ 1. Write Test Config (JSON) │
│ Simple, declarative, no code needed │
│ │
│ 2. Run Tests │
│ $ mcp-jest test-config.json │
│ │
│ 3. See Results │
│ ✓ Connection test passed (50ms) │
│ ✓ Tool: calculate - passed (23ms) │
│ ✗ Resource: data - failed (15ms) │
│ Expected: "value" │
│ Received: "other" │
│ │
│ 4. Update Snapshots (if needed) │
│ $ mcp-jest test-config.json -u │
│ │
│ 5. Integrate with CI/CD │
│ Exit codes, JSON output, timing info │
│ │
└─────────────────────────────────────────────────┘
MCP-JEST Supports Snapshots
┌─────────────────────────────────────────────────────────┐
│ Snapshot Comparison Algorithm │
├───────────────────────────────────────────────────────── ┤
│ │
│ 1. Normalize Data: │
│ • Sort object keys alphabetically │
│ • Remove volatile fields (timestamps, IDs) │
│ • Apply inclusion/exclusion rules │
│ │
│ 2. Generate Hash: │
│ • Create deterministic string representation │
│ • Use SHA-256 for consistency │
│ │
│ 3. Compare: │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Current │ │ Stored │ │
│ │ Output │ <=> │ Snapshot │ │
│ └─────────────┘ └─────────────┘ │
│ │ │ │
│ └────────┬───────────┘ │
│ │ │
│ ┌────┴────┐ │
│ │ Equal? │ │
│ └────┬────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ │ │
│ [Yes] [No] │
│ │ │ │
│ ✓ Pass Check Update Mode │
│ │ │
│ ┌────────┴────────┐ │
│ │ │ │
│ [Update Mode] [Normal Mode] │
│ │ │ │
│ Update & Pass Show Diff & Fail │
│ │
└─────────────────────────────────────────────────────────┘
Comparison with Alternatives
What Exists Today vs MCP-JEST
┌─────────────────────────────────────────────────────────────┐
│ Testing Approach Comparison │
├───────────────────────────────────────────────────────────── ┤
│ │
│ Manual Testing: │
│ ─────────────── │
│ • Start server manually │
│ • Use Claude Desktop or terminal │
│ • Manually invoke each tool │
│ • Visually verify outputs │
│ • No automation, no CI/CD │
│ │
│ Custom Scripts: │
│ ─────────────── │
│ • Write custom Node.js/Python scripts │
│ • Implement MCP client from scratch │
│ • Handle all edge cases yourself │
│ • Maintain test infrastructure │
│ • Reinvent the wheel for each project │
│ │
│ Generic Test Frameworks (Jest/Mocha): │
│ ───────────────────────────────────── │
│ • Not designed for process communication │
│ • No MCP protocol understanding │
│ • Complex setup for stdio handling │
│ • No built-in capability discovery │
│ • Manual snapshot implementation │
│ │
│ MCP-JEST: │
│ ───────── │
│ ✓ Purpose-built for MCP │
│ ✓ Zero-config process management │
│ ✓ Protocol-aware testing │
│ ✓ Built-in expectations & snapshots │
│ ✓ CI/CD ready out of the box │
│ ✓ Minimal dependencies │
│ │
└─────────────────────────────────────────────────────────────┘
Feature Comparison Matrix
┌─────────────────────────────────────────────────────────────┐
│ Feature Comparison │
├─────────────────┬──────────┬─────────┬──────────┬────────── ┤
│ Feature │ MCP-JEST │ Manual │ Custom │ Generic │
│ │ │ Testing │ Scripts │ Frameworks│
├─────────────────┼──────────┼─────────┼──────────┼────────────┤
│ Process Mgmt │ ✓ │ ✗ │ ~ │ ✗ │
│ MCP Protocol │ ✓ │ ✓ │ ~ │ ✗ │
│ Auto Discovery │ ✓ │ ✗ │ ~ │ ✗ │
│ Snapshots │ ✓ │ ✗ │ ~ │ ~ │
│ CI/CD Ready │ ✓ │ ✗ │ ~ │ ✓ │
│ Type Safety │ ✓ │ ✗ │ ~ │ ~ │
│ Zero Config │ ✓ │ ✓ │ ✗ │ ✗ │
│ Timing Info │ ✓ │ ✗ │ ~ │ ✓ │
│ Expectations │ ✓ │ ✗ │ ~ │ ✓ │
│ JSON Reports │ ✓ │ ✗ │ ~ │ ~ │
└─────────────────┴──────────┴─────────┴──────────┴──────────┘
Legend: ✓ Full Support, ~ Partial/Manual Implementation, ✗ Not Supported
Why This Matters
1. For MCP Server Developers
┌─────────────────────────────────────────────────────────┐
│ Value for Server Developers │
├───────────────────────────────────────────────────────── ┤
│ │
│ Confidence: │
│ • Know your server works before shipping │
│ • Catch regressions immediately │
│ • Test edge cases systematically │
│ │
│ Productivity: │
│ • Fast feedback loop │
│ • No manual testing repetition │
│ • Focus on features, not testing infrastructure │
│ │
│ Quality: │
│ • Consistent behavior across updates │
│ • Document expected behavior via tests │
│ • Ensure protocol compliance │
│ │
└─────────────────────────────────────────────────────────┘
2. For the MCP Ecosystem
┌─────────────────────────────────────────────────────────┐
│ Ecosystem Benefits │
├─────────────────────────────────────────────────────────┤
│ │
│ Standardization: │
│ • Common testing patterns │
│ • Shared quality bar │
│ • Consistent user experience │
│ │
│ Trust: │
│ • Users can trust tested servers │
│ • "MCP-JEST tested" badge │
│ • Reduced bugs in production │
│ │
│ Growth: │
│ • Lower barrier to entry │
│ • Faster development cycles │
│ • More reliable servers → more adoption │
│ │
└─────────────────────────────────────────────────────────┘
🤝 Contributing
We love contributions! Here's how to get started:
Quick Development Setup
# Clone the repository
cd mcp-jest
npm install
npm run dev # Start development mode
npm test # Run tests
npm run build # Build for production
Ways to Contribute
- 🐛 Bug Reports: Found an issue? Report it in the issue tracker
- 💡 Feature Requests: Have an idea? We'd love to hear it
- 📝 Documentation: Help improve our docs
- 🧪 Test Cases: Add tests for edge cases
- 🔧 Code: Submit pull requests
Development Guidelines
- Follow existing code style
- Add tests for new features
- Update documentation
- Be kind and respectful
🆘 Troubleshooting
Common Issues
Server won't start?
# Use absolute paths
mcp-jest /usr/bin/node ./server.js
# Check server logs
DEBUG=mcp-jest* mcp-jest node ./server.js
Connection timeout?
# Increase timeout
mcp-jest node ./server.js --timeout 60000
Tool execution fails?
// Add detailed logging
expect: (result) => {
console.log('Result:', JSON.stringify(result, null, 2));
return result.success === true;
}
Get Help
- 📖 Full Documentation: Comprehensive guides and examples
- 💬 Community Q&A: Join the community discussions
- 🐛 Issues: Bug reports and feature requests
- 📧 Email: For private inquiries
📋 Requirements
- Node.js: 18+ (for ESM and modern features)
- MCP Server: Any server implementing Model Context Protocol
- Optional: TypeScript 5+ for full type safety
🎉 Join the Community
- ⭐ Show your support: Give us a star
- 🐦 Follow Updates: Get the latest news
- 💬 Join Discussions: Connect with other developers
- 🔄 Share: Help others discover mcp-jest
📄 License
MIT License - Use freely in commercial and open source projects.
🙏 Acknowledgments
- Anthropic: For creating the Model Context Protocol
- MCP Community: For building the ecosystem
- Contributors: Everyone who makes this project better
Built with ❤️ for the MCP ecosystem
Get Started • Documentation • Examples • Contributing
Make your MCP servers bulletproof. Start testing today! 🚀
Documentation
Comprehensive documentation is available to help you get the most out of mcp-jest:
- Getting Started Guide - Step-by-step guide to get up and running quickly
- API Reference - Complete API documentation with detailed examples
- Examples - Real-world examples and use cases
- Guides - In-depth guides for advanced usage patterns
Contributing
We welcome contributions from the community! Your input helps make mcp-jest better for everyone.
Thank you to all our contributors who have helped shape this project. Every contribution, no matter how small, is valued and appreciated.
- Contributing Guidelines - Learn how to contribute to the project
- Code of Conduct - We maintain a welcoming and inclusive environment for all contributors
- Getting Started - Fork the repo, make your changes, and submit a pull request
We encourage contributions of all kinds:
- Bug fixes and feature implementations
- Documentation improvements
- Test coverage enhancements
- Performance optimizations
- Community support and engagement
Security
Security is a top priority for mcp-jest. We take the security of our code and our users seriously.
- Security Policy - View our security policy and vulnerability reporting process
- Responsible Disclosure - Please report security vulnerabilities responsibly through our security policy
If you discover a security vulnerability, please follow our responsible disclosure process outlined in the security policy.
License
mcp-jest is released under the MIT License. This means you can use it freely in both commercial and open-source projects.
See the LICENSE file for the full license text.
Support
Need help? We're here to support you:
- GitHub Issues - Report bugs or request features
- GitHub Discussions - Ask questions and share ideas with the community
- Email - For private inquiries, reach out to support@mcp-jest.dev
Before opening an issue, please check if your question has already been answered in the documentation or existing issues.
Quick Start
1
Clone the repository
git clone https://github.com/josharsh/mcp-jest2
Install dependencies
cd mcp-jest
npm install3
Follow the documentation
Check the repository's README.md file for specific installation and usage instructions.
Repository Details
Ownerjosharsh
Repomcp-jest
LanguageJavaScript
LicenseMIT License
Last fetched8/10/2025
Recommended MCP Servers
💬
Discord MCP
Enable AI assistants to seamlessly interact with Discord servers, channels, and messages.
integrationsdiscordchat
🔗
Knit MCP
Connect AI agents to 200+ SaaS applications and automate workflows.
integrationsautomationsaas
🕷️
Apify MCP Server
Deploy and interact with Apify actors for web scraping and data extraction.
apifycrawlerdata
🌐
BrowserStack MCP
BrowserStack MCP Server for automated testing across multiple browsers.
testingqabrowsers
⚡
Zapier MCP
A Zapier server that provides automation capabilities for various apps.
zapierautomation