Forem: Shadab Khan

Turn Any OpenAPI Spec into Safe MCP Tools for Claude in Seconds

Shadab Khan — Wed, 06 May 2026 02:38:49 +0000

If you've tried connecting REST APIs to AI agents, you've probably hit this moment:

The MCP server starts. Claude sees the tools. You ask it to fetch some data.

And it calls the wrong endpoint. Or fires a DELETE it shouldn't. Or gets confused between two tools that look similar and just... picks one.

Your spec passed every linter. The conversion worked fine.

The agent still broke.

This is the gap nobody talks about. OpenAPI specs were designed for human developers who can read vague documentation, infer intent, and apply common sense. AI agents can't do any of that. They need:

Every endpoint to have a clear, unambiguous name (operationId)
Descriptions that say when to call a tool, not just what it does
Explicit safety signals on destructive operations
No two tools that look similar enough to cause confusion

Standard linters don't check for any of this. So the spec looks clean, the linter passes green, and the agent quietly makes bad decisions.

That's the problem I kept hitting. So I built mcp-openapi-doctor to fix it.

What mcp-openapi-doctor Does

It's a CLI tool with four commands that take a raw OpenAPI or Swagger spec and make it genuinely agent-ready.

OpenAPI spec → mcp-openapi-doctor → cleaned spec + MCP overlay → your MCP server → Claude

It's a preprocessor, not a replacement. It fits in front of whatever MCP tooling you're already using — AWS OpenAPI MCP, FastMCP, Tyk, or your own server.

Step 1: Inspect — See Your Agent-Readiness Score

The first thing you want to know is how broken your spec actually is for agent use.

npx mcp-openapi-doctor inspect https://petstore3.swagger.io/api/v3/openapi.json

You get a score from 0–100 broken into three dimensions:

MCP OpenAPI Doctor 🩺
─────────────────────────────────────
API:        Petstore API v1.0.0
Operations: 19 across 9 paths
Version:    OpenAPI 3.0.3

Agent-readiness score: 61/100

Safety       ████░░░░░░  24/40
Clarity      ███░░░░░░░  21/35
Efficiency   █████░░░░░  16/25

Issues found:
  ✗ error   6x missing operationId
  ✗ error   3x destructive endpoint without warning
  ⚠ warn    8x vague or missing description
  ⚠ warn    1x response schema exceeds 30 fields

These aren't style issues. Each one is a real agent failure mode:

Issue	What actually happens
Missing `operationId`	Agent has no stable tool name to reference
Destructive endpoint without warning	Agent fires DELETE with no hesitation
Tool name collision	LLM picks between two similar tools arbitrarily
Vague description	Agent calls the wrong tool because intent isn't clear
Response schema bloat (80+ fields)	Burns context window, degrades reasoning quality

Step 2: Generate — Preview Exactly What Claude Will See

Before running a server, generate shows you the exact tools Claude will have access to — names, descriptions, inputs, and safety classification.

npx mcp-openapi-doctor generate ./openapi.yaml

Generated tools: 4

✓ list_users
  Operation: GET /users
  Safety:    SAFE_READ
  Inputs:    none

✓ get_user
  Operation: GET /users/{id}
  Safety:    SAFE_READ
  Inputs:    id*

⚠ update_user
  Operation: PUT /users/{id}
  Safety:    WRITE
  Inputs:    id*, body

✗ delete_user
  Operation: DELETE /users/{id}
  Safety:    DESTRUCTIVE
  Inputs:    id*

Use --read-only to see only the tools that would be exposed in safe mode:

npx mcp-openapi-doctor generate ./openapi.yaml --read-only
# Only SAFE_READ tools appear — WRITE and DESTRUCTIVE are hidden from the agent

This is useful when you're scoping what you want Claude to access before you open up write operations.

Step 3: Fix — Auto-Fix What's Safe to Fix

fix generates a cleaned spec in an output folder. It never modifies your original file.

npx mcp-openapi-doctor fix ./openapi.yaml --out ./output/ --diff

What gets generated:

output/
├── cleaned-openapi.yaml    ← patched spec with fixes applied
├── mcp-overlay.yaml        ← x-mcp-* metadata for downstream MCP servers
├── doctor-report.json      ← structured issues + score
├── fixes.md                ← human-readable log of every change
├── summary.md              ← before/after score + remaining actions
├── diff.md                 ← readable diff of every change
└── diff.json               ← structured diff for tooling

What the fixer will safely change:

Generate missing operationId from method + path, slugified and deduplicated
Normalize all operationId values to snake_case
Add fallback summaries where missing
Inject x-mcp-destructive: true on DELETE endpoints
Add placeholder schemas for missing request bodies and responses

What it will never do:

Remove any endpoint
Change runtime behavior
Touch your source file
Use AI to rewrite anything (all fixes are deterministic)

The summary.md shows you the before/after score and what still needs a human:

Before: 61/100
After:  88/100

Fixed automatically:
  ✓ 6 missing operationIds generated
  ✓ 3 destructive endpoints flagged with x-mcp-destructive
  ✓ 4 missing summaries added

Still needs your attention:
  ⚠ 8 vague descriptions — these need human context to fix well
  ⚠ 1 response schema with 87 fields — consider a filtered endpoint

Step 4: Serve — Connect Directly to Claude Desktop

Once your spec is clean, serve starts an MCP stdio server that Claude Desktop connects to directly.

npx mcp-openapi-doctor serve ./openapi.yaml --read-only

The terminal will look idle — that's expected. It's waiting for an MCP client over stdio.

Add it to your Claude Desktop config:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "mcp-openapi-doctor",
        "serve",
        "/absolute/path/to/openapi.yaml",
        "--read-only"
      ],
      "env": {
        "API_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop and ask: What tools do you have available?

The tools from your spec appear. Claude can call your actual REST API through them.

The Safety Model

Every endpoint is classified before it's exposed:

GET                          →  SAFE_READ    ✓ exposed in --read-only
POST / PUT / PATCH           →  WRITE        ✗ hidden in --read-only  
DELETE                       →  DESTRUCTIVE  ✗ hidden in --read-only
Paths with admin/billing/
payment/secret/token/
credential                   →  SENSITIVE    ✗ hidden in --read-only

--read-only is the recommended mode when you're first exposing an API to an agent. Let Claude explore and read before you decide which write operations to open up.

Works With Your Existing MCP Stack

Because it outputs a standard cleaned OpenAPI spec, the output drops straight into whatever you're already using:

# Clean first
npx mcp-openapi-doctor fix ./stripe.yaml --out ./output/

# Then feed cleaned spec to your preferred MCP server
npx @aws/openapi-mcp-server --spec ./output/cleaned-openapi.yaml
# or fastmcp, tyk, your own server

The mcp-overlay.yaml contains x-mcp-* extensions that compatible servers can read for additional agent hints.

Try It Now — Five Real Examples

The repo ships with five fixture specs covering a range of quality levels:

git clone https://github.com/yourname/mcp-openapi-doctor
cd mcp-openapi-doctor
pnpm install && pnpm build

# A clean, well-described read-only API — should score 90+
pnpm start -- inspect ./examples/clean-read-api.yaml

# An intentionally broken CRM API — good for seeing all the checks fire
pnpm start -- inspect ./examples/risky-crm-api.yaml
pnpm start -- fix ./examples/risky-crm-api.yaml --out .output/ --diff

# Swagger 2.0 compatibility
pnpm start -- inspect ./examples/swagger-2-api.json

# The classic Petstore
pnpm start -- serve ./examples/simple-openapi.yaml --read-only

Or just run it against any public API right now:

# GitHub API
npx mcp-openapi-doctor inspect https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

# Petstore
npx mcp-openapi-doctor inspect https://petstore3.swagger.io/api/v3/openapi.json

What's Coming Next

Phase 1 is shipped. On the roadmap for Phase 2:

Web UI — paste a spec URL, see issues highlighted inline, download the fixed spec
AI-powered description hints — --ai-hints flag that uses an LLM to suggest better agent-oriented descriptions for vague endpoints
GitHub Action — gate your CI on a minimum agent-readiness score
VS Code extension — inline diagnostics while editing a spec file
Custom rule plugins — bring your own rules as JS modules for internal API conventions

The One-Line Summary

Your API spec passes Spectral. But will Claude use it safely?

mcp-openapi-doctor finds what linters miss.

If you're building anything in the MCP or AI agent space, give it a try and let me know what you find — especially if you hit a spec it handles badly or a check it's missing.

GitHub: github.com/yourname/mcp-openapi-doctor

If this saves you from a broken agent call, a ⭐ on the repo goes a long way. It helps other developers find it when they hit the same wall.

Built in TypeScript. Zero install via npx. MIT licensed.

LifeOps: An AI System That Aligns Your Daily Actions with Your Future Self

Shadab Khan — Mon, 27 Apr 2026 07:40:59 +0000

Why I Built LifeOps — A Personal OS for Becoming Your Future Self

The app most productivity tools never thought to build

There's a moment most self-improvement people know well.

You download a new app. You set up your habits. You add your goals. You feel organised, motivated, maybe even a little excited. And then — slowly — it becomes just another list you feel guilty about not opening.

I've been through that cycle more times than I'd like to admit.

Not because I lacked discipline. Not because the apps were bad. But because every single one of them asked the wrong question.

They asked: "Did you finish the task?"

Nobody asked: "Is today helping you become the person you want to be?"

That one question changed how I thought about productivity. And it's the reason I spent months building LifeOps.

The Problem With Productivity Apps

I'm a developer. I've tried everything — Notion, Todoist, Habitica, Obsidian, Roam, Reflect, Monday, TickTick, even my own custom Airtable setups. And I have nothing against any of them. They're well-built tools.

But they all share the same fundamental flaw: they treat your life as a collection of isolated systems.

Your habit tracker doesn't know about your goals.
Your task list doesn't know about your identity.
Your notes app is a graveyard of half-formed thoughts.
Your goal planner collects dust after the first week of January.
Your AI assistant gives generic advice because it doesn't actually know you.

I was running five different apps for five different slices of my life — and none of them talked to each other. There was no thread connecting what I did today to who I'm trying to become.

The result? A lot of activity. Very little alignment.

The Insight That Started Everything

One evening I sat down and wrote out what I actually wanted my life to look like in five years. Not in a vague "I want to be successful" way — but specifically. The kind of person I wanted to be. The habits I'd have built. The work I'd be doing. The relationships I'd have deepened.

I called this my Future Self.

And then I looked at my task list for that week.

Almost none of it connected to that person.

I was busy. I was productive by any conventional measure. But I wasn't aligned. The gap between my daily actions and my future identity was enormous — and invisible, because no tool was showing it to me.

That's the insight that started LifeOps.

What if there was a system that started with your identity — the person you want to become — and worked backwards to your daily actions? What if every habit, every task, every plan was explicitly connected to that future version of you?

Building the Loop

I started sketching the core loop on paper.

It looked like this:

Future Self → Life Areas → Goals → Habits + Tasks → Daily Execution → Weekly Review → back to Future Self

Each layer feeds the next. Your Future Self defines your life areas — health, relationships, career, creativity, whatever matters to you. Your life areas inform your goals. Your goals generate habits and tasks. Your habits and tasks shape your daily plan. Your daily execution feeds into a weekly review. And your weekly review updates your understanding of your future self.

It's a closed loop. Everything is connected. Nothing is isolated.

This is what LifeOps is built around.

What I Built

LifeOps is an AI-powered personal operating system. Here's what it includes at MVP:

Future Self — You define (or AI-generate) a profile of who you're building toward. Not a vision board. A structured identity: the values you're embodying, the person you're becoming, the life you're designing.

Goals — Measurable outcomes connected to your life areas. Not floating abstractions — goals anchored to the future self you've defined.

Habits — Repeatable actions linked directly to goals. The AI can suggest habits based on a goal you've set. You review them before saving.

Tasks — Concrete work, with due dates, priorities, and a link to the goal it serves. Not just a flat list.

Notes — Quick capture for reflections, ideas, and context. The AI can summarise a note or extract next actions from it.

Dashboard — Everything in one calm view. Today's habits, active goals, tasks due, recent notes, and your progress.

AI Daily Planner — Each morning, LifeOps generates a structured day plan using your actual goals, tasks, and habits as context. You review it. You edit it. You approve it. Then you execute.

Weekly Review — Every week, LifeOps pulls your completed tasks, habit logs, and notes — and generates a summary: what you won at, where the gaps were, what patterns it sees, and what to focus on next week.

Why AI — But Not in the Way You Think

When people hear "AI-powered productivity app" they probably imagine a chatbot. A generic assistant that says things like "Great job completing your tasks this week! Here are some tips for better time management 🌟"

That's not what I built.

The AI in LifeOps is deeply contextual. It knows your Future Self profile. It knows your active goals. It knows your current habits and open tasks. When it generates a daily plan or a weekly review, it's using your specific life context — not generic templates.

But more importantly: every AI output is review-before-save.

I made this a hard design decision early on. I don't want an AI making decisions for me. I want it to do the heavy lifting of synthesis and pattern recognition — and then show me the result so I can think about it, edit it, and own it.

The AI surfaces. The human decides.

The Design Philosophy

I had a few principles I kept coming back to while building:

Calm, not noisy. Productivity apps are often anxiety machines. Overdue tasks in red. Notification badges. Streak counters. LifeOps is designed to feel like a quiet workspace, not a dashboard screaming at you.

Guided, not overwhelming. Most productivity systems collapse under their own weight. LifeOps is opinionated about what matters — the Future Self loop — so you're never staring at a blank canvas wondering what to do.

Focused on becoming, not completing. The question isn't whether you ticked the box. It's whether the day moved you closer to the person you said you want to be.

Honest about progress. The weekly review doesn't celebrate fake streaks. It shows you the real picture — wins and gaps — so you can adjust.

Who This Is For

LifeOps is for people who feel productive but not aligned.

You know the type — maybe you are the type. Smart, driven, organised. Always working on something. But occasionally you stop and ask: is all this activity actually taking me somewhere?

It's for people who've tried every productivity app and found them useful but incomplete. Who want one system instead of five. Who want their daily actions to mean something beyond a completed checkbox.

It's especially for people drawn to ideas like identity-based habits, future self journaling, life design, and personal operating systems — but who want something more structured and AI-assisted than a paper journal.

What's Next

LifeOps is at MVP stage right now. The core loop is complete. The AI features work. The codebase is clean, well-structured, and fully open source on GitHub (MIT licence).

Future phases on the roadmap include mobile support, deeper integrations, automation workflows, and community features. But I'm intentionally not rushing. The MVP does one thing: helps you stay aligned with your future self, every single day. That's enough to start.

If you want to try it, self-host it, or contribute — the repo is open.

And if you've ever felt that nagging disconnect between your daily hustle and the person you're actually trying to become — LifeOps was built for that exact feeling.

One Last Thing

After I built the first working version and used it for a week, I had a moment I didn't expect.

I opened the dashboard on a Tuesday morning and looked at my tasks, my habits, and my goals — all connected, all pointing toward the same Future Self I'd defined. And for the first time in years of using productivity tools, I didn't feel organised. I felt aligned.

That's the difference I was chasing.

That's what I hope LifeOps gives you too.

LifeOps is open source. You can find the repo, self-host instructions, and full documentation at github.com/shadkhan/LifeOps.

If this resonated, share it with someone who's been chasing the right productivity tool for years. They might have just found it.

I built a shell script that sets up your entire AI coding agent workspace in 2 minutes

Shadab Khan — Sat, 25 Apr 2026 02:52:00 +0000

Every time I started a new project with an AI coding agent, I was doing the same thing.

Opening a blank repo. Writing CLAUDE.md from scratch. Explaining my stack again. Explaining my conventions again. Explaining what NOT to do — again. By the time I had the agent actually doing useful work, I'd already spent two hours just setting up context.

Then I'd switch projects, and repeat everything from scratch.

There had to be a better way.

The problem with AI coding agents and new projects

If you've used Claude Code or Codex CLI, you already know how much these tools depend on good project context. The agent doesn't know your stack. It doesn't know you prefer pnpm over npm. It doesn't know that you never want raw SQL, or that every Prisma query needs a userId filter to prevent IDOR vulnerabilities, or that your commit messages follow Conventional Commits.

Without that context, you spend the first hour of every session correcting the agent instead of building.

The solution everyone discovers eventually is CLAUDE.md for Claude Code and AGENTS.md for Codex — instruction files the agent reads at the start of every session. But writing these well takes time, and the best ones include:

Your exact tech stack with version numbers
What NOT to do (as important as what to do)
Security rules baked in from day one
A testing strategy covering unit, integration, security, adversarial, and performance tests
Module specs the agent reads before implementing anything

Writing all of that properly for every new project is genuinely tedious. So I automated it.

What I built: AI Agents Template Builder

github.com/shadkhan/AI-agents-template-builder

It's a GitHub Template Repository with a shell script that turns the template into a fully configured agent workspace for your specific project in about 2 minutes.

Here's what you do:

# Use the template on GitHub, then clone your new repo
git clone https://github.com/shadkhan/AI-agents-template-builder
cd AI-agents-template-builder

chmod +x scripts/init-project.sh
./scripts/init-project.sh

The script asks you six questions:

Project name and description
Language (TypeScript, Python, Go, JavaScript, or custom)
Framework and database
Package manager
Your modules (Notes, Tasks, Auth — whatever your app has)
Security profile (user-facing web app, API, static site, CLI tool)

Then it generates everything.

What gets generated

`CLAUDE.md` and `AGENTS.md` — filled in for your stack

Both files get your actual project name, tech stack, repo structure, and commands injected. No more {{placeholders}} — just ready-to-use instructions.

CLAUDE.md is read by Claude Code automatically. AGENTS.md is read by Codex CLI, Cursor, Aider, and Amp — it's now an open standard stewarded by the Linux Foundation with 60,000+ open-source projects using it.

`SECURITY.md` — security rules the agent enforces

This is the file I'm most proud of. It covers eight layers of security baked into every project from day one:

Input validation with Zod on every route — patterns and examples included
IDOR prevention — every Prisma query must include userId from the JWT, not from the request body
JWT verification patterns and refresh token rotation
HTTP security headers via @fastify/helmet
Rate limiting rules per endpoint type
File upload security — MIME type allowlists, path traversal prevention, UUID-based storage
Database security — parameterized queries, field exclusion patterns
Logging rules — what to log, what never to log

The agent reads this alongside CLAUDE.md and applies these rules on every route it writes. I stopped getting auth-less routes and missing userId filters in PR reviews.

`docs/testing/` — five-layer testing strategy

Four files covering every testing layer the agent needs to know about:

TESTING.md — the master strategy. Unit tests, integration tests, security tests, adversarial tests, and performance evaluation tests. Includes the complete CI/CD pipeline config for GitHub Actions.

VALIDATION.md — "validation loops." Every Zod schema gets tested for both valid and invalid inputs, for every field, for every constraint. The pattern that ensures schema drift never silently lets bad data through.

ADVERSARIAL.md — deliberately acting like a malicious user. IDOR attacks, mass assignment, SQL injection payloads, file upload attacks, JWT forgery, property-based fuzzing with fast-check. The agent writes these tests for every new module.

PERFORMANCE.md — k6 baseline tests that run before every release. Catches N+1 Prisma queries and missing PostgreSQL indexes before they hit production.

`docs/specs/` — one spec stub per module

For every module you listed during setup, you get a spec file with the structure already in place: data model, API endpoints, request/response schemas, business rules, and acceptance criteria. Fill in the content, hand it to the agent, and it implements the whole module end-to-end without asking clarifying questions.

Everything else

docs/PRD.md — product requirements doc with your modules listed
docs/ARCHITECTURE.md — architecture stub
docs/adr/ADR-001.md — first architecture decision record
CONTRIBUTING.md — with your actual commands
.env.example — skeleton based on your stack (Postgres URL, JWT secrets, Redis, etc.)
.gitignore — standard, generated if not present
.github/workflows/validate-agent-files.yml — CI that fails if you commit .env, leave unfilled placeholders, or reference a spec that doesn't exist

Two more scripts for ongoing use

new-module.sh — add a new module to an existing project:

./scripts/new-module.sh "Notes"
# → generates docs/specs/notes.spec.md with full template
# → adds Notes to CLAUDE.md module table automatically

Fill in the spec, then tell the agent:

"Read docs/specs/notes.spec.md and implement the Notes module end-to-end"

update-module-status.sh — keep CLAUDE.md current as you ship:

./scripts/update-module-status.sh "Notes" done
./scripts/update-module-status.sh "Tasks" in-progress

The agent reads the module status table at the start of every session. Keeping it accurate prevents it from re-implementing something that already exists.

The global file — the part most people miss

Both Claude Code and Codex support a global instruction file that applies to every project:

# For Codex — applies to every repo you work in
~/.codex/AGENTS.md

# For Claude Code
~/.claude/CLAUDE.md

Put your universal personal preferences there once — pnpm over npm, no any in TypeScript, Conventional Commits — and never repeat them in any project file again. Project-level files inherit and can override.

This is the layer that truly makes the workflow feel automatic. New project, run the script, and the agent already knows your personal defaults before it even reads the project files.

Works with every major coding agent

Agent	File it reads
Claude Code	`CLAUDE.md` (falls back to `AGENTS.md`)
Codex CLI	`AGENTS.md`
Cursor	`AGENTS.md` + `.cursor/rules`
Aider	`AGENTS.md`
Amp	`AGENTS.md`
GitHub Copilot	`.github/copilot-instructions.md`

The template generates CLAUDE.md and AGENTS.md. For Copilot, symlink or copy AGENTS.md content into .github/copilot-instructions.md.

The workflow in practice

Once this is set up, my per-project flow looks like this:

Day 1:

clone template → run init-project.sh → fill TODO sections → commit

About 20 minutes total.

Per module:

./scripts/new-module.sh "ModuleName"
Fill docs/specs/modulename.spec.md (15 min)
Tell agent: "Read docs/specs/modulename.spec.md and implement end-to-end"
Review diffs → merge
./scripts/update-module-status.sh "ModuleName" done

Before release:

pnpm test:security
pnpm test:adversarial  
pnpm test:perf

The agent handles implementation. I handle architecture decisions and code review. The instruction files make sure we're always speaking the same language.

Try it

The repo is at github.com/shadkhan/AI-agents-template-builder.

Click "Use this template" to create your own copy, run the init script, and you're set up in under two minutes.

If you find it useful, a GitHub star helps other developers find it. And if you add support for new stacks or languages in the init script, PRs are very welcome — the more stacks covered, the more useful it gets for everyone.

Built this while setting up LifeOps, my personal organization platform that I'm also open-sourcing. More on that soon.