{
"markdown": "# DebugBundle\n\nProduction debugging bundles for AI agents, with runtime error reporting and incident response.\n\n\n\n\n\n\nDebugBundle provides runtime error reporting, crash reporting, incident response, endpoint health checks, and product analytics for humans and AI agents. It captures runtime failures, groups them into incidents, and publishes deterministic debug bundles. Its monitoring scope is customer-facing runtime behavior and endpoint health, not generic infrastructure metrics.\n\n## Why DebugBundle?\n\nModern AI agents are useful only when they get enough trustworthy context. DebugBundle packages the facts around a production incident into a versioned bundle instead of leaving agents to scrape dashboards, logs, traces, and chat threads.\n\nKey properties:\n\n- **Agent-native bundles:** deterministic failure and improvement bundles with errors, requests, responses, logs, frontend context, deploy metadata, runtime details, and reproduction hints.\n- **Interface parity:** API, CLI, and MCP expose the same incident, bundle, probe, webhook, alert, project, and automation workflows.\n- **Local-first setup:** start without a cloud account by writing events to `.debugbundle/local/events/`, then connect to DebugBundle Cloud when ready.\n- **Safe SDKs:** SDK failures are swallowed internally, sensitive fields are redacted before transport, and duplicate storms are suppressed locally.\n- **Self-hostable core:** Compose-based stack for the web app, API, worker, Postgres, Redis, and S3-compatible object storage.\n\n## AnalyticsBundle\n\nAnalyticsBundle extends debugging from incident evidence to product-usage evidence without turning DebugBundle into a long-term raw-event store. It is opt-in browser analytics for the questions a human or agent needs to improve a product: visits and active users, routes and funnels, device/browser/OS/language segments, feature use, friction markers, incident impact, and bounded structured journey replay.\n\n- **Ask directly:** API, CLI, and MCP expose aggregate metrics, journey patterns, opportunities, and generated AnalyticsBundles through the same project-authorized surface.\n- **Generate by analysis unit:** bundles describe a usage, funnel, route, friction, conversion, deploy, or incident-impact question. DebugBundle does not create one AnalyticsBundle per visit.\n- **Keep evidence explainable:** a generated bundle includes aggregate metrics, linked incidents/deploys, privacy-safe journey timelines, and deterministic journey-selection rank/basis for agent review.\n- **Stay privacy- and cost-conscious:** raw analytics inputs and retained journey samples expire; long-lived usage is aggregate rollups. Debug capture remains independent when analytics is disabled, unavailable, sampled out, quota-limited, or unhealthy.\n\nSee the repository [public interface contract](contracts/public-interfaces.md#12b-analyticsbundle-and-product-analytics) for API/CLI/MCP parity and the [self-host guide](deploy/selfhost/README.md#analyticsbundle-operations) for retention and upgrade behavior.\n\n## Quick Start\n\nChoose the path that matches how you want to evaluate DebugBundle.\n\n### Cloud\n\nUse Cloud when you are preparing a hosted deployment or want team-visible incidents, alerts, webhooks, GitHub automation, API access, and MCP access.\n\n```bash\nnpm install -g @debugbundle/cli\ndebugbundle setup\ndebugbundle login\ndebugbundle connect\n```\n\n`debugbundle connect` creates or selects a cloud project, creates a write-only project token, and updates `.debugbundle/local/connection.json`. Put the shown project token in your hosted environment:\n\n```bash\nDEBUGBUNDLE_PROJECT_TOKEN=dbundle_proj_xxxxxxxxxxxx\n```\n\nAdd the smallest SDK or ingestion path that matches your app, deploy it with the token configured, then verify ingestion:\n\n```bash\ndebugbundle verify cloud --project-id proj_01HXYZ... --trigger-5xx\ndebugbundle incidents --source cloud\ndebugbundle inspect inc_01HXYZ...\n```\n\nSee the full [Cloud quickstart](https://debugbundle.com/docs/quickstart) and [connect-to-cloud guide](https://debugbundle.com/docs/project-setup/connect-to-cloud).\n\n### Local-only\n\nUse local-only mode when you want captured data and bundles to stay on the machine or storage volume where the SDK and CLI run.\n\n```bash\nnpm install -g @debugbundle/cli\ndebugbundle setup --project-mode local-only\n```\n\nInitialize an SDK in local mode where supported, or use `debugbundle watch` for existing logs. After triggering a test error:\n\n```bash\ndebugbundle process\ndebugbundle incidents --source local\ndebugbundle inspect inc_local_...\n```\n\nLocal events are written under `.debugbundle/local/events/`; generated bundles are written under `.debugbundle/bundles/`. See the [local-only guide](https://debugbundle.com/docs/project-setup/local-only).\n\n## Install an SDK\n\nAll SDKs follow the same universal interface: `init`, `captureException`, `captureError`, `captureLog`, `captureRequest`, `captureMessage`, `setContext`, `probe`, and `flush`.\n\n| Runtime | Package | Install | Main docs |\n| ------------ | ------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |\n| Node.js | `@debugbundle/sdk-node` | `npm install @debugbundle/sdk-node` | [Node.js SDK](https://debugbundle.com/docs/sdks/node) |\n| Browser | `@debugbundle/sdk-browser` | `npm install @debugbundle/sdk-browser` | [Browser SDK](https://debugbundle.com/docs/sdks/browser) |\n| Python | `debugbundle-python` | `pip install debugbundle-python` | [Python SDK](https://debugbundle.com/docs/sdks/python) |\n| PHP | `debugbundle/sdk-php` | `composer require debugbundle/sdk-php` | [PHP SDK](https://debugbundle.com/docs/sdks/php) |\n| Java | `com.debugbundle:debugbundle-spring-boot-starter` | Maven or Gradle dependency | [Java SDK](https://debugbundle.com/docs/sdks/java) |\n| .NET | `DebugBundle.AspNetCore` / `DebugBundle.Sdk` | `dotnet add package DebugBundle.AspNetCore` | [.NET SDK](https://debugbundle.com/docs/sdks/dotnet) |\n| Go | `github.com/debugbundle/debugbundle-go` | `go get github.com/debugbundle/debugbundle-go` | [Go SDK](https://debugbundle.com/docs/sdks/go) |\n| Ruby | `debugbundle` | `gem install debugbundle` | [Ruby SDK](https://debugbundle.com/docs/sdks/ruby) |\n| Android | `com.debugbundle:debugbundle-android` | Maven or Gradle dependency | [Android SDK](https://debugbundle.com/docs/sdks/android) |\n| iOS | `DebugBundle` | Swift Package Manager or CocoaPods | [iOS SDK](https://debugbundle.com/docs/sdks/swift) |\n| React Native | `@debugbundle/sdk-react-native` | `npm install @debugbundle/sdk-react-native` | [React Native SDK](https://debugbundle.com/docs/sdks/react-native) |\n| WordPress | `debugbundle-wordpress` | WordPress.org plugin directory | [WordPress plugin](https://debugbundle.com/docs/integrations/wordpress) |\n\n### Node.js\n\n```bash\nnpm install @debugbundle/sdk-node\n```\n\n```typescript\nimport { debugbundle } from \"@debugbundle/sdk-node\";\n\ndebugbundle.init({\n projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,\n environment: \"production\",\n service: \"api\"\n});\n\ndebugbundle.captureExceptions();\ndebugbundle.captureRejections();\n```\n\nExpress, Fastify, Next.js, pino, winston, bunyan, local file transport, remote capture policy, probes, and browser relay handlers are supported.\n\n### Browser\n\n```bash\nnpm install @debugbundle/sdk-browser\n```\n\n```typescript\nimport { createDebugBundleBrowserSdk } from \"@debugbundle/sdk-browser\";\n\nconst debugbundle = createDebugBundleBrowserSdk();\n\ndebugbundle.init({\n transportMode: \"relay\",\n endpoint: \"/debugbundle/browser\",\n environment: \"production\",\n service: \"web\"\n});\n```\n\nFor full-stack apps, prefer a backend browser relay so project tokens stay server-side. Same-origin relay paths are simplest; split frontend/backend deployments can use explicit browser relay mode with an absolute backend relay URL and backend origin allowlisting. Frontend-only deployments can send directly to DebugBundle Cloud with a dedicated public write-only token and an allowed-origin restriction. See [Browser Relay Setup](https://debugbundle.com/docs/sdks/browser-relay).\n\n### Python\n\n```bash\npip install debugbundle-python\n```\n\n```python\nimport os\nimport debugbundle\n\ndebugbundle.init(\n project_token=os.environ[\"DEBUGBUNDLE_PROJECT_TOKEN\"],\n environment=\"production\",\n service=\"api\",\n)\n\ndebugbundle.capture_exceptions()\ndebugbundle.capture_logging()\n```\n\nDjango, Flask, FastAPI, Python logging, structlog, loguru, local file transport, remote capture policy, probes, and browser relay helpers are supported.\n\n### PHP\n\n```bash\ncomposer require debugbundle/sdk-php\n```\n\n```php\n getenv('DEBUGBUNDLE_PROJECT_TOKEN'),\n 'environment' => 'production',\n 'service' => 'api',\n]);\n\nDebugBundle::captureErrors();\nDebugBundle::captureExceptions();\nDebugBundle::captureShutdown();\n```\n\nLaravel, Symfony, Monolog, local file transport, remote capture policy, probes, and browser relay adapters are supported.\n\n### Ruby\n\n```bash\ngem install debugbundle\n```\n\n```ruby\nrequire \"debugbundle\"\n\nDebugBundle.init(\n project_token: ENV[\"DEBUGBUNDLE_PROJECT_TOKEN\"],\n environment: \"production\",\n service: \"api\"\n)\n\nDebugBundle.capture_exceptions\n```\n\nRails, Rack, Sidekiq, Ruby Logger, Semantic Logger, local file transport, remote capture policy, probes, and browser relay handlers are supported.\n\n### Java\n\n```xml\n\n com.debugbundle\n debugbundle-spring-boot-starter\n 0.1.0\n\n```\n\n```yaml\ndebugbundle:\n project-token: ${DEBUGBUNDLE_PROJECT_TOKEN}\n environment: production\n service: api\n project-mode: connected\n```\n\nThe Spring Boot starter supports servlet request capture, MVC exception capture, Logback capture, remote config, probes, and an optional browser relay route.\n\n### Go\n\n```bash\ngo get github.com/debugbundle/debugbundle-go\n```\n\n```go\nclient := debugbundle.New(debugbundle.Config{\n ProjectToken: os.Getenv(\"DEBUGBUNDLE_PROJECT_TOKEN\"),\n Environment: \"production\",\n Service: \"api\",\n})\ndefer func() { _ = client.Flush(context.Background()) }()\n```\n\nnet/http, Gin, Echo, slog, zap, zerolog, local file transport, remote capture policy, probes, and browser relay handlers are supported.\n\n### WordPress\n\nInstall **DebugBundle** from the [WordPress.org plugin directory](https://wordpress.org/plugins/debugbundle/), then open **Settings -> DebugBundle** and save your project token. The plugin bundles backend PHP capture, frontend browser capture, and a WordPress REST relay so the project token stays server-side.\n\n## CLI, API, and MCP\n\nThe CLI is the daily operational entry point:\n\n```bash\nnpm install -g @debugbundle/cli\ndebugbundle setup\ndebugbundle doctor\ndebugbundle verify local\ndebugbundle verify cloud --trigger-5xx\ndebugbundle incidents\ndebugbundle inspect \n```\n\nAutomation can use the HTTP API directly or the MCP server for agent workflows:\n\n- API reference: \n- CLI reference: \n- MCP docs: \n- MCP distribution channels: \n- OpenAI Plugin candidate: \n- Bundle schema: \n\nMarketplace-managed MCP clients can run `npx @debugbundle/mcp` and provide `DEBUGBUNDLE_MEMBER_TOKEN` in the MCP server environment. The official MCP Registry name is `com.debugbundle/mcp`; project tokens are SDK write-only ingestion credentials and must not be used for MCP retrieval or management.\n\nThe separate OpenAI Plugin `1.0.0` production candidate combines a tailored skill with an OAuth-protected twenty-three-tool read-only remote projection plus the owner-approved existing-app consent, synthetic-reviewer, and Settings revocation surfaces. Its nine analytics tools expose bounded aggregate usage, route, device, acquisition, action, funnel, journey-pattern, and incident-impact metrics while excluding individual journeys, custom dimensions, analytics bundles/opportunities, and mutations. It is active at the permanent `https://mcp.debugbundle.com/mcp` origin for owner-approved Developer Mode validation, preserves the stdio/OpenClaw surface, and is not submitted, published, or publicly installable.\n\nFor local visual review without a real provider interaction, run `make dev-openai-plugin-preview` and open . The opt-in development route uses the production UI components with deterministic synthetic data and provides every consent/reviewer/Settings state, all 64 scope subsets, and 390 px, 768 px, and 1280 px iframe viewports. Its actions stay in browser memory and never call OAuth, reviewer, grant, or revocation APIs. The route is absent from production builds, and preview evidence does not replace manual accessibility, MCP Inspector, outside-network reviewer, ChatGPT Developer Mode, deployed, submission, or publication validation.\n\n## Repository Layout\n\n```text\napps/\n api/ Fastify ingestion and retrieval API\n worker/ BullMQ processing worker for normalization, grouping, bundles, alerts, and webhooks\n cli/ @debugbundle/cli command-line interface\n mcp/ @debugbundle/mcp server for agent workflows\n web/ React/Vite app for interactive project and incident management\npackages/\n auth/ Auth, sessions, token generation, token hashing\n bundle-engine/ Deterministic bundle assembly\n event-normalizer/ Event validation, normalization, classification, fingerprinting\n log-parser/ CLI log ingestion parser registry\n redaction/ Sensitive data scrubbing\n retrieval-client/ Shared retrieval API client used by CLI and MCP\n shared-types/ Zod schemas, TypeScript types, bundle/event contracts\n storage/ Postgres, Redis, S3-compatible storage adapters and migrations\nsdks/\n debugbundle-js/ Local clone of the JS SDK repo\n debugbundle-python/ Local clone of the Python SDK repo\n debugbundle-php/ Local clone of the PHP SDK repo\n debugbundle-java/ Local clone of the Java SDK repo\n debugbundle-go/ Local clone of the Go SDK repo\n debugbundle-wordpress/ Local clone of the WordPress plugin repo\n debugbundle-ruby/ Local clone of the Ruby SDK repo\nsite/\n Public docs, marketing, reference, and blog site clone\n```\n\nThe SDKs are standalone repositories under the `debugbundle` GitHub organization. This core repository owns the product services, shared contracts, CLI/MCP surfaces, and core-owned shared JS packages.\n\n## Local Development\n\nUse the Make targets so routine commands run in Docker-scoped environments.\n\n```bash\nmake install\nmake infra-up\nmake infra-bootstrap\nmake dev\n```\n\nLocal services:\n\n| Service | Default |\n| ------------- | ----------------------- |\n| Web app | `http://localhost:5291` |\n| API | `http://localhost:3003` |\n| Postgres | `localhost:5434` |\n| Redis | `localhost:6380` |\n| LocalStack S3 | `localhost:4567` |\n\nUseful checks:\n\n```bash\nmake lint\nmake typecheck\nmake test\nmake build\nmake ci\n```\n\n`make dev` requires `DEBUGBUNDLE_PROBE_TRIGGER_SECRET` and `ANALYTICS_HASH_SECRET` in `.env`. Start from `.env.example`, then keep local-only overrides in `.env.local` when needed.\n\n## Self-Hosting\n\nThe supported self-host bootstrap lives in `deploy/selfhost/`.\n\n```bash\ngit clone https://github.com/debugbundle/debugbundle.git\ncd debugbundle/deploy/selfhost\ncp .env.example .env\ndocker compose up -d\n```\n\nThe self-host stack includes the web app, API, worker, PostgreSQL, Redis, and LocalStack S3. See [Self-Hosting](https://debugbundle.com/docs/self-hosting) and [deploy/selfhost/README.md](deploy/selfhost/README.md).\n\n## Documentation\n\n- Public docs: \n- Quickstart: \n- Installation: \n- SDKs: \n- Agent workflows: \n- System overview: [SYSTEM_OVERVIEW.md](SYSTEM_OVERVIEW.md)\n- Architecture map: [ARCHITECTURE_MAP.md](ARCHITECTURE_MAP.md)\n- Requirements: [spec/requirements.md](spec/requirements.md)\n- Acceptance criteria: [spec/acceptance.md](spec/acceptance.md)\n- Public interfaces: [contracts/public-interfaces.md](contracts/public-interfaces.md)\n\n## Release Model\n\nThe canonical public product release is the root `debugbundle` repository tag and GitHub Release (`v*`). Package-specific releases are separate:\n\n- `cli-v*` for `@debugbundle/cli`\n- `mcp-v*` for `@debugbundle/mcp`\n- `shared-js-v*` for `@debugbundle/shared-types` and `@debugbundle/redaction`\n\nStandalone SDK repositories publish and version their own release surfaces independently:\n\n- `debugbundle-js` for `@debugbundle/sdk-node` and `@debugbundle/sdk-browser`\n- `debugbundle-python` for `debugbundle-python`\n- `debugbundle-php` for `debugbundle/sdk-php`\n- `debugbundle-java` for Maven artifacts\n- `debugbundle-go` for Go modules\n- `debugbundle-wordpress` for the WordPress plugin\n\nThe v1 release train publishes dependency roots before dependent wrappers:\n\n1. Publish `@debugbundle/shared-types` and `@debugbundle/redaction` from the core repo first.\n2. Publish `@debugbundle/sdk-node` and `@debugbundle/sdk-browser` from `debugbundle-js` after the matching shared-package version exists on npm.\n3. Publish independent SDK and package families whose artifacts do not bundle another DebugBundle SDK.\n4. Publish React Native after the Android and iOS native SDK versions it delegates to are live and smoke-tested.\n5. Publish WordPress after the PHP SDK and browser SDK versions it requires are live and smoke-tested, then rebuild the bundled browser asset.\n6. Bump hosted dogfooding manifests only after the referenced registry versions exist.\n7. Create the canonical core GitHub Release after package-specific release workflows pass.\n\nOur own hosted/source-deployed dogfooding surfaces intentionally consume published packages rather than implicit workspace links. After a successful registry publish, bump the pinned versions in the root `package.json`, hosted app `apps/web/package.json`, and public-site `site/package.json` before running hosted validation or deployment.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The short version:\n\n- Keep app/package boundaries strict.\n- Add or update tests for behavior changes.\n- Run `make lint`, `make typecheck`, `make test`, and `make build` before asking for review.\n- Update docs, contracts, and public interface references when behavior changes.\n\n## Security\n\nDo not report vulnerabilities in public issues. Use GitHub private vulnerability reporting for this repository:\n\n\n\nSee [SECURITY.md](SECURITY.md) for scope and response expectations.\n\n## License\n\nDebugBundle is licensed under AGPL-3.0-only. See [LICENSE](LICENSE).\n",
"bytes": 20251,
"sha": "c20d4b0f99758488691df570c0e11e8882158ffa660c346000e1de4432238689",
"repo_slug": "debugbundle/debugbundle",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_com_debugbundle_mcp_ebd2520a/readme"
}