DEV Community

Chrysostomos Koumides
Chrysostomos Koumides

Posted on

Building SpecSync: How I Extended Kiro with Custom MCP Tools

#kiro #mcp #api #testing

I Built a Tool That Stops Your Code and Docs From Lying to Each Other

Logo of SpecSync

Picture this: It's 2 AM. Production is down. Your frontend is calling GET /users/{id}/posts. The backend removed that endpoint three weeks ago. The tests? All green. The docs? Still show the endpoint exists.
Programmer without SpecSync holding its head in despair

How did this happen?

Someone updated the code. Forgot to update the tests. Definitely forgot the docs. The spec? Nobody's looked at that in months.

This is drift, when your code, tests, docs, and specs slowly become strangers to each other. And it's killing your velocity.

What if Your Git Commits Just... Refused to Lie?

That's SpecSync. It's a pre-commit hook on steroids that validates everything stays in sync, before the commit even happens.

Here's What Happens

You add a new endpoint:

git add backend/handlers/user.py
git commit -m "Add user posts endpoint.
"
Enter fullscreen mode Exit fullscreen mode

SpecSync blocks you:

❌ Hold up. You added an endpoint, but:
   - No spec for it
   - No tests for it  
   - No docs for it

Fix these and try again.
Enter fullscreen mode Exit fullscreen mode

You fix it. Commit succeeds. Zero lies in your git history.

The Microservices Problem

Your backend team ships a breaking change. Your frontend? Still calling the old endpoint. You find out in production.

SpecSync Bridge fixes this:

Backend:

specsync-bridge extract  # Extracts API contract
git push                 # Shares it
Enter fullscreen mode Exit fullscreen mode

Frontend (auto-syncs every hour):

specsync-bridge validate

❌ You're calling GET /users/{id}/posts
   Backend removed it last week.
Enter fullscreen mode Exit fullscreen mode

You find out in development, not production.

Three Things That Make This Actually Usable

1. Setup is One Command 

specsync-bridge setup
Enter fullscreen mode Exit fullscreen mode

It auto-detects everything, asks a few questions, and you're done. No YAML hell.

2. Auto-Sync Just Works 

specsync-bridge auto-sync --enable
Enter fullscreen mode Exit fullscreen mode

Contracts sync every hour automatically. Silent. In the background. You get notified only when something breaks.

3. It Uses Git (No New Infrastructure) 

specsync-bridge add-dependency backend \
  --git-url https://github.com/org/backend.git
Enter fullscreen mode Exit fullscreen mode

That's it. No Kafka. No service mesh. No databases. Just git.

Real Talk: Does This Actually Work?

I tested it on a microservices project with 5 services. Here's what happened:

Week 1: Found 23 drift issues we didn't know existed. Ouch.

Week 2: Caught 3 breaking changes before they hit staging.

Week 3: New developer onboarded. Trusted the docs. They were actually correct. Mind blown.

Week 4: Zero production incidents from API mismatches.

The team's reaction? "Why didn't this exist before?"

Try It (Takes 2 Minutes) 

pip install specsync-bridge
specsync-bridge setup
Enter fullscreen mode Exit fullscreen mode

Answer a few questions. Done.

It's open source: github.com/chryskoum/specsync

The Motto of SpecSync

Your code lies. Your docs lie. Your tests lie. They don't mean to, they just drift apart over time.

SpecSync makes them tell the truth. At commit time. Automatically. Forever.

No drift in git = no drift in production.

Questions? Roast my code? Let me know in the comments.

Top comments (0)