The Problem Every Developer Knows Too Well
You’re working on a project in Cursor with your carefully crafted coding rules and style guides. Everything’s perfect. Then you switch to Kiro for another project, and… your workspace is cluttered with duplicate .md files.
Sound familiar? This exact frustration led me to build the Agent Rules MCP Server – a solution that lets you store all your coding rules in GitHub and fetch them on-demand, no matter which AI tool you’re using.
What I Built: A Universal Rule Management System
The Agent Rules MCP Server transforms how developers handle coding standards by:
- Centralized Storage: Keep all coding rules in one GitHub repository
- On-Demand Access: Pull specific rules without cluttering your workspace
-
Multi-Format Support: Works with
.md,.mdc,.chatmode.md,.prompt.md, and.instructions.md - Smart Fallbacks: Automatically switches to direct GitHub access when API limits hit
- Zero Config: Works immediately with public repos – no GitHub token required
The server provides two core MCP tools:
-
get_rules: Fetch rules for specific rules (e.g. react, security, typescript, etc.) -
list_rules: Browse all available rule topics with descriptions
Try It Yourself
The Agent Rules MCP Server is available on NPM and works with any MCP-compatible AI tool. Check out the GitHub repository for setup instructions and example configurations.
The Architecture
Built with modern TypeScript and these key technologies:
- MCP TypeScript SDK: For seamless AI tool integration
- GitHub API: For reliable file access with smart fallbacks
- Node.js
The server implements intelligent caching and concurrent request handling, with automatic fallbacks to raw GitHub URLs when API limits are reached.
Overcoming Challenges
The MCP Schema Compatibility Issue
The biggest hurdle was discovering that MCP has strict JSON Schema limitations. My server worked perfectly with other IDEs but failed when connecting to Kiro. Through feedback, we identified and solved the schema compatibility issues, redesigning complex validation patterns.
GitHub API Rate Limiting
Rather than forcing users to manage API tokens, I built a smart fallback system that seamlessly switches to direct GitHub raw github content file access when rate limits are hit. This makes the tool accessible to everyone without needing for Github token.
What This Means for Developers
- No More Rules Duplication: One source of development rules for all your AI IDEs or CLIs
- Cross-Tool Compatibility: Use the same rules in Cursor, Copilot, Kiro, Windsurf, or any MCP-compatible AI tool
- Zero Maintenance: Rules live in GitHub where they belong, not scattered across local files
The Kiro Advantage: AI-Powered Development
What made this project special wasn’t just the end result – it was how I built it using Kiro’s Specs features. Here’s how Kiro transformed my development process:
1. Specs-Driven Development
I spent over an hour using Kiro’s Specs feature to plan everything before writing a single line of code. It was a collaborative architecture design session with Kiro:
- Defined the exact problem and solution approach
- Specified technical requirements (TypeScript, Node, MCP SDK, GitHub API)
- Mapped out tool functionality and error handling strategies
- Created a PRD that Kiro will follow
The result? When Kiro generated code, it perfectly matched our planned architecture. No confusion, no scope creep, just clean implementation.
2. Steering Rules for Consistency
Kiro’s steering system kept coding standards consistent throughout the project. Instead of repeatedly explaining my preferences, I set up steering rules that automatically guided every code generation session.
3. Kiro as a Debugging Partner
The most impressive moment came when my MCP server wouldn’t connect to Kiro itself due to JSON Schema compatibility issues. I simply copied the error messages and described the problem. Kiro immediately identified that MCP doesn’t support complex schema features like oneOf and anyOf, then rewrote my parameter schemas to use simpler patterns – saving me time.
Key Takeaways for AI-Assisted Development
Working with Kiro taught me that the future of coding isn’t about AI replacing developers – it’s about true collaboration:
- Plan First: Use specs to align on goals before coding
- Set Standards: Steering rules eliminate repetitive explanations
- Debug Together: AI can solve complex technical problems faster than solo research
- Stay Focused: One conversation, one specific goal at a time
What coding standards do you struggle to keep consistent across projects? How do you currently manage rules across different AI tools? Share your experiences in the comments below!
kiro #ai #mcp #productivity