{
  "markdown": "# MQ-Sentinel\n\n<!-- mcp-name: io.github.pramodreddyboddu/mq-sentinel -->\n\n**Production-grade, read-only IBM MQ diagnostic MCP server that AI agents can safely use — with zero hallucinations.**\n\nI built this as a serious side project to solve a real, high-stakes problem in enterprise environments. It is now a strong public portfolio piece demonstrating systems engineering, security, observability, production deployment, and building safe infrastructure for AI agents.\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)\n[![mypy strict](https://img.shields.io/badge/mypy-strict-success.svg)](https://mypy.readthedocs.io/)\n[![ruff](https://img.shields.io/badge/lint-ruff-orange.svg)](https://docs.astral.sh/ruff/)\n[![tests 271 passing](https://img.shields.io/badge/tests-271%20passing-success.svg)]()\n[![Org-Ready](https://img.shields.io/badge/org--ready-✓-blue)](docs/ORG-READINESS-PLAN.md)\n\n> **0.3.0** — 8 diagnostic tools across all 10 IBM MQ flavors. Read-only by design. Prompt-injection firewall. OIDC + RBAC. Hash-chained audit. Verified IBM Knowledge Center citations (CI-enforced). Production Helm with HPA + air-gapped packaging.\n\n**GitHub:** https://github.com/pramodreddyboddu/mq-sentinel  \n**Live Demo:** https://mq-sentinel.io  \n**Get it in front of people:** [docs/LAUNCH.md](docs/LAUNCH.md)\n\n---\n\n## The Problem I Solved\n\nEnterprise IBM MQ teams waste hours diagnosing issues like:\n- 2035 NOT_AUTHORIZED storms\n- Exploding DLQs\n- Native HA replica lag and split-brain\n- Stale cluster members\n- z/OS mysteries\n\nTraditional tools require deep expertise and manual log diving. Handing an LLM raw MQ access is unacceptable for security and compliance teams.\n\n**MQ-Sentinel** gives Claude, Cursor, Grok, and other agents a safe MCP interface that returns accurate, cited diagnostics without ever hallucinating or executing destructive commands.\n\n---\n\n## The Problem\n\nIBM MQ teams (banks, telcos, insurance, gov) waste hours on:\n- `2035 NOT_AUTHORIZED` channel storms\n- Exploding DLQs\n- Native HA replica lag / split-brain\n- Stale cluster members\n- z/OS QSG mysteries\n\nTraditional tools require deep MQSC knowledge and grepping logs. Giving an LLM direct MQ access is a non-starter for security/compliance teams.\n\n**MQ-Sentinel solves this** by giving Claude, Cursor, Grok, etc. a safe, read-only MCP interface that returns **typed Root Cause + Fix Steps + verified IBM docs** — never fabricates, never executes destructive commands.\n\n---\n\n## 🎬 See it in 90 seconds\n\n```bash\ngit clone https://github.com/pramodreddyboddu/mq-sentinel.git\ncd mq-sentinel\nmake demo\n```\n\nWatch MQ-Sentinel diagnose a real `2035 NOT_AUTHORIZED`, an `INDOUBT` channel, a 1247-message DLQ, and a Native HA replica disconnect — all against the bundled fixture sandbox. No live IBM MQ required.\n\n[![asciicast](https://img.shields.io/badge/%E2%96%B6-watch%20the%20cast-9333ea?style=for-the-badge)](demo/README.md) &nbsp; [![Try live demo](https://img.shields.io/badge/%F0%9F%8C%90-try%20live%20demo-3b82f6?style=for-the-badge)](https://mq-sentinel.io)\n\n> Want to record it for sharing? `make demo-record` produces a browser-playable asciinema cast.\n\n**Quick self-check (no MQ needed):**\n\n```bash\nuv run mq-sentinel doctor\nuv run mq-sentinel tools     # list all diagnostics\nuv run mq-sentinel info      # overview + security highlights\n```\n\n### Use it from Claude, Grok, Cursor, Gemini, ChatGPT\n\nOne MCP server — not a per-vendor plugin. Copy-paste configs: **[docs/mcp-clients.md](docs/mcp-clients.md)**.\n\nList it where agents discover servers: official [MCP Registry](https://registry.modelcontextprotocol.io/) (`server.json`) + [Smithery](https://smithery.ai) (`smithery.yaml`). ChatGPT needs a **hosted HTTPS** endpoint, not local stdio.\n\n### Architecture at a Glance\n\n```mermaid\nflowchart TB\n    subgraph Client[\"MCP Client (Claude / Cursor / Grok)\"]\n        P[Prompt]\n    end\n\n    subgraph Sentinel[\"MQ-Sentinel (read-only)\"]\n        OIDC[OIDC + RBAC]\n        RL[Rate Limiter]\n        DISP[Tool Dispatcher]\n        ALLOW[MQSC Allowlist]\n        CONN[Connector<br/>(pymqi / fixture)]\n        RCS[RCS Engine +<br/>KC Registry]\n        SAN[Output Sanitizer]\n        AUDIT[Hash-chained<br/>Audit Log]\n    end\n\n    subgraph MQ[\"IBM MQ (read-only service account)\"]\n        QM[Queue Managers]\n    end\n\n    P -->|MCP stdio / HTTP| OIDC\n    OIDC --> RL --> DISP\n    DISP --> ALLOW\n    ALLOW --> CONN\n    CONN -->|raw output| RCS\n    RCS --> SAN\n    SAN --> AUDIT\n    CONN --> QM\n    QM -.->|DISPLAY only| CONN\n```\n\nSafe by design. No LLM inside the server. Every citation verified in CI.\n\n---\n\n## Why This Stands Out as a Portfolio Project\n\nThis is not a toy or weekend demo. It demonstrates real engineering depth:\n\n- **Systems + Security Engineering**: Full threat model, multi-layer read-only enforcement, prompt-injection firewall, OIDC+RBAC, tamper-evident audit, hardened containers, SBOM + signed images.\n- **Production Operations**: Production Helm (HPA, ServiceMonitor, NetworkPolicy), air-gapped packaging (RPM/DEB), observability out of the box.\n- **AI Agent Infrastructure**: A complete, safe MCP server (stdio + HTTP) designed for real use by agents like Claude, Cursor, and Grok.\n- **Enterprise Domain Expertise**: Deep coverage of IBM MQ across 10 topologies with version-aware, verified citations.\n- **Systematic Delivery**: Executed a full 7-phase org-readiness plan with compliance artifacts that actual organizations need.\n\n**Built with Grok Build** (primary coding partner) while maintaining strict engineering standards.\n\nFull journey and plan: [docs/ORG-READINESS-PLAN.md](docs/ORG-READINESS-PLAN.md)\n\nSee also: [VISION.md](VISION.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [DEVELOPMENT.md](DEVELOPMENT.md)\n\n---\n\n## The Journey (Portfolio Story)\n\nI built MQ-Sentinel to solve a painful, recurring problem in enterprise IBM MQ environments — and I treated the entire effort as a serious engineering and portfolio project.\n\nI used **Grok Build** (xAI) as my primary coding partner from architecture through implementation, docs, Helm, compliance artifacts, and polish. Every major decision was deliberate: read-only first, citations that can't go stale, defense-in-depth, production packaging.\n\nKey milestones:\n- Designed threat model + multi-layer security architecture before writing the first tool\n- Delivered 8 diagnostic tools across 10 MQ flavors with CI-enforced IBM Knowledge Center citations\n- Production deployment (Helm + HPA + ServiceMonitor, distroless, air-gapped RPM/DEB)\n- Full 7-phase org-readiness plan executed (see links above)\n- 271+ tests (including security-negative tests), strict mypy, comprehensive docs for platform teams\n\nThis shows end-to-end ownership: deep domain knowledge, security by design, production operations, and shipping artifacts that real organizations can actually use.\n\n**This is my public portfolio project.** It demonstrates systems engineering, security, observability, AI infrastructure, and disciplined delivery.\n\nBuilt with Grok Build while holding high standards throughout.\n\n## Security posture — baked in, not bolted on\n\n- **Read-only always.** Static MQSC allowlist (`DISPLAY` / `DIS` / `PING CHANNEL` only). Destructive verbs are rejected by three layers: tool, connector, MQ-side `setmqaut`.\n- **Prompt-injection firewall.** Every MQ-sourced string is sanitized (control chars, zero-width, ANSI, unicode tag chars, jailbreak markers) and wrapped in a quarantine envelope before leaving the server.\n- **URL allowlist + live verification.** Responses may only cite `www.ibm.com`; all other URLs are redacted. Every citation in the registry (20+ reason codes, 8 AMQ codes, 18 topic pages) is fetched daily in CI — a dead link fails the build, not the customer.\n- **Tamper-evident audit log.** Hash-chained JSONL; `mq-sentinel verify-audit` detects any retroactive edit.\n- **OIDC + RBAC.** Principals scoped to `nonprod-read` / `prod-read` / `admin-audit`. Cannot query prod QMs from a nonprod token.\n- **Hardened runtime.** Distroless image, non-root, read-only FS, dropped capabilities, seccomp, network egress allowlist.\n- **Supply chain.** SBOM, cosign-signed images, `pip-audit` + Trivy in CI, every PR security-gated.\n\nSee [SECURITY.md](SECURITY.md) and [docs/threat-model.md](docs/threat-model.md).\n\n**Org / Enterprise Ready?**  \nThis project was deliberately built for real organizations (banks, gov, large enterprises). See the complete journey:\n\nSee [VISION.md](VISION.md) for the owner product principles and long-term thinking.\n\n- [Org-Readiness Plan](docs/ORG-READINESS-PLAN.md) — 7-phase plan executed end-to-end\n- [Production Guide](docs/PRODUCTION.md) + [Platform Team Onboarding](docs/getting-started-platform-teams.md)\n- [Security Posture](docs/SECURITY_POSTURE.md) + [SOC2 Evidence Checklist](docs/compliance/soc2-evidence-checklist.md)\n- [RBAC & Auth Examples](docs/oidc-examples.md) (Okta, Entra ID, Keycloak)\n- Production Helm with HPA, ServiceMonitor, network policies, and fleet support\n- [Observability](observability/) — Grafana + Prometheus alerts ready to import\n\n---\n\n## Skills & Engineering Rigor (Portfolio Highlights)\n\n**What this project demonstrates:**\n\n- **Systems & Security Engineering** — Full threat model, prompt-injection defense, multi-layer read-only enforcement, OIDC+RBAC, hash-chained audit, distroless hardening.\n- **Observability & Production Operations** — Metrics, dashboards, alerts, runbooks, air-gapped packaging, Helm productionization.\n- **AI Agent Infrastructure** — Built a real, safe MCP server (stdio + HTTP) that LLMs can use without risk.\n- **Enterprise Systems** — Deep IBM MQ knowledge across 10 topologies + version-aware diagnostics.\n- **Software Craftsmanship** — 271+ tests (including security), strict mypy, ruff, CI-driven doc verification, SBOM + cosign signing.\n- **End-to-End Delivery** — From idea to org-ready artifacts, including comprehensive documentation that platform teams can actually use.\n\nBuilt iteratively using Grok Build as the primary coding partner while maintaining high engineering standards.\n\n## Supported IBM MQ flavors (Phase 1 complete)\n\nStandalone · Multi-Instance QM · RDQM · Native HA · Native HA + CRR · Uniform Cluster · Traditional Cluster · z/OS Queue Sharing Group · MQ Appliance · Containerized.\n\n## Diagnostic tools\n\n| Tool | Covers | Demo finding |\n|---|---|---|\n| `diagnose_failed_channels` | Distributed channels | 2035 NOT_AUTHORIZED, 2009/2059 connection errors, INDOUBT, AMQ9202/9208/9503 |\n| `analyze_dlq_and_suggest_reprocessing` | DLQ (headers only — never bodies) | Grouped by reason 2035/2080/2030/2051/2053/2079, backout-loop detection |\n| `check_cluster_health` | Traditional + uniform cluster | Partial repository, stale CLUSQMGR, suspended members, unhealthy cluster channels |\n| `diagnose_native_ha_issues` | K8s/OpenShift Native HA | Replica state, quorum, log replay lag, split-brain, CRR lag |\n| `diagnose_rdqm_issues` | On-prem RHEL RDQM | Pacemaker quorum, offline nodes, DRBD connection/disk, split-brain |\n| `diagnose_zos_qsg_issues` | z/OS Queue Sharing Group | QSG members, CHIN, page sets, buffer pools, CF structures |\n| `diagnose_multi_instance_issues` | Traditional MIQM | Active/standby state, dual-active split, standby permission, failover events |\n| `full_mq_health_check` | All of the above (composite) | Executive summary + ranked findings |\n\n## Supported MQ versions\n\n**9.2 LTS, 9.3, 9.4 (incl. 9.4.4+), z/OS.** Version is auto-detected at connect time; KC doc links are keyed to the detected version.\n\n## Install — pick your path\n\n| Scenario | Command | Time |\n|---|---|---|\n| **Solo / startup laptop (dev)** | `curl -fsSL https://raw.githubusercontent.com/pramodreddyboddu/mq-sentinel/main/scripts/install.sh \\| MQS_DEV_MODE=true MQS_DEV_MODE_ACK_INSECURE=yes bash` | 5 min |\n| **Solo / startup (prod)** | Same, with `MQS_AUTH_OIDC_*` env vars exported | 5 min |\n| **Mid-org Kubernetes** | `helm install mq-sentinel oci://ghcr.io/pramodreddyboddu/charts/mq-sentinel --set oidc.issuer=… --set oidc.audience=… --set oidc.jwksUrl=…` | 30 min |\n| **Local K8s POC (no live MQ)** | `cd examples/kind && ./install.sh` | 5 min |\n| **RHEL / Rocky / OEL** | `sudo dnf install https://github.com/pramodreddyboddu/mq-sentinel/releases/latest/download/mq-sentinel-0.1.0-1.x86_64.rpm` | 5 min |\n| **Debian / Ubuntu** | `sudo apt install ./mq-sentinel_0.1.0_amd64.deb` | 5 min |\n| **Air-gapped (banks/gov)** | Mirror RPM internally, sign with org GPG, deploy via Satellite / Aptly | 1 evening |\n\nFull guide: [docs/INSTALL.md](docs/INSTALL.md). For IBM MQ client libs: [docs/byom.md](docs/byom.md).\n\n## Quick start (developer / contributor)\n\n```bash\nmake install        # uv sync + editable install\nmake test           # pytest\nmake ci             # lint + type + tests + security suite (everything CI runs)\nmake docker         # build the production container image\nmake rpm deb        # build RPM + DEB packages (requires `gem install fpm`)\n```\n\nSee:\n- [DEVELOPMENT.md](DEVELOPMENT.md) — owner-level development guide\n- [docs/usage-with-ai.md](docs/usage-with-ai.md) — best prompts and patterns when using with Claude / Cursor / Grok\n- [docs/ORG-READINESS-PLAN.md](docs/ORG-READINESS-PLAN.md) — the full journey to org-ready\n\n## Transports\n\n```bash\n# stdio (default — for Claude Desktop, Cursor, Claude Code)\nuv run mq-sentinel serve\n\n# HTTP (production — OIDC bearer auth, /healthz, /readyz, /metrics)\nuv run mq-sentinel serve --transport http --host 0.0.0.0 --port 8080\n```\n\nSee [docs/http-transport.md](docs/http-transport.md) for the OIDC config,\nendpoint reference, and operational notes.\n\n## Repository layout\n\n```\nsrc/mq_sentinel/\n  security/     command allowlist, output sanitizer, rate limiter\n  audit/        hash-chained JSONL audit logger\n  auth/         OIDC + RBAC\n  inventory/    QM registry (pluggable)\n  secrets/      pluggable secrets backend (default: filesystem/K8s)\n  connectors/   MQ connection layer (pymqi + fixture)\n  rcs/          Root Cause Summary engine + KC doc registry\n  tools/        MCP tools (populated Phase 1+)\n  telemetry/    OpenTelemetry + structured logging\n  cli/          control-plane CLI\ndeploy/\n  Dockerfile    distroless, non-root, read-only FS\n  helm/         Kubernetes chart (security defaults on)\ntests/\n  security/     allowlist + injection firewall corpus (non-negotiable)\n  unit/\n```\n\n## Org-Readiness (7-Phase Plan Executed)\n\nThis project was deliberately taken through a complete org-readiness program (7 phases) so it is credible for real platform/SRE teams. See the full plan and status:\n\n- [docs/ORG-READINESS-PLAN.md](docs/ORG-READINESS-PLAN.md)\n- [docs/ORG-READINESS.md](docs/ORG-READINESS.md) — all 7 phases addressed (as of 2026-06-22)\n\nCurrent state: Ready for platform team evaluation.\n\n## Technical Roadmap\n\nPhase 1 (MCP diagnostic tools) is complete. See [CHANGELOG.md](CHANGELOG.md) for future technical items:\n\n- **0.4.0** — ServiceNow / Jira ticket auto-draft from RCS findings.\n- **0.5.0** — SOC 2 evidence-pack generator.\n- Historical telemetry, air-gapped improvements, etc.\n\nSafe remediation is intentionally **out of scope**. MQ-Sentinel only reports.\n\n## For Organizations\n\nMQ-Sentinel is designed from the ground up for enterprise use:\n\n- Read-only, prompt-injection resistant, OIDC + RBAC\n- Verifiable IBM Knowledge Center citations\n- Production deployment options (Kubernetes, RPM/DEB, air-gapped)\n- Full audit trail\n\n**Start here:**\n- [Org Readiness Plan](docs/ORG-READINESS-PLAN.md)\n- [Production Guide](docs/PRODUCTION.md)\n- [Getting Started for Platform Teams](docs/getting-started-platform-teams.md)\n- [OIDC Examples](docs/oidc-examples.md)\n- [Security Posture](docs/SECURITY_POSTURE.md)\n\nHelm chart includes production values, HPA, monitoring, and network policies.\n\n## License\n\nProprietary — © 2026 MG. See [LICENSE](LICENSE). IBM® and IBM MQ® are trademarks of IBM Corporation; MG is not affiliated with IBM.\n",
  "bytes": 15928,
  "sha": "e9aa4155911e4324259385939f93d06ebb67fa47bbb2e9f01d94f71fece58456",
  "repo_slug": "pramodreddyboddu/mq-sentinel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pramodreddyboddu_mq_sentinel_69674985/readme"
}