@kryptosai/mcp-observatory 0.20.3 → 0.22.0

package/docs/compatibility.md

@@ -0,0 +1,164 @@
+# MCP Server Compatibility
+
+MCP Observatory supports two transport adapters — **local-process (stdio)** and **HTTP (Streamable HTTP + SSE)** — which together cover ~95% of the MCP server ecosystem.
+
+This document tracks which servers work, how to configure them, and what patterns are not yet supported.
+
+## Tested and Passing
+
+These servers have been tested directly with MCP Observatory and produce valid results.
+
+| Server | Package | Transport | Setup | Tools | Prompts | Resources |
+|--------|---------|-----------|-------|-------|---------|-----------|
+| Everything | [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) | stdio | Zero-config | ✅ pass | ✅ pass | ✅ pass |
+| Filesystem | [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) | stdio | Path args | ✅ pass | — unsupported | — unsupported |
+| Context7 | [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp) | stdio | Zero-config | ✅ pass | — unsupported | — unsupported |
+| Puppeteer | [`puppeteer-mcp-server`](https://www.npmjs.com/package/puppeteer-mcp-server) | stdio | Zero-config | ✅ pass | — unsupported | ✅ pass |
+| OpenTofu | [`@opentofu/opentofu-mcp-server`](https://www.npmjs.com/package/@opentofu/opentofu-mcp-server) | stdio | Zero-config | ✅ pass | — unsupported | ✅ pass |
+| Ref Tools | [`ref-tools-mcp`](https://www.npmjs.com/package/ref-tools-mcp) | stdio | Zero-config | ✅ pass | ✅ pass | — unsupported |
+| Promptopia | [`promptopia-mcp`](https://www.npmjs.com/package/promptopia-mcp) | stdio | Zero-config | ✅ pass | ✅ pass | — unsupported |
+| GitHub MCP | Docker-based | stdio | `GITHUB_PERSONAL_ACCESS_TOKEN` | ✅ pass | ✅ pass | ✅ pass |
+
+## Compatible (stdio, zero-config or env vars only)
+
+These servers use standard stdio transport and should work with MCP Observatory. Most just need an API key as an env var.
+
+### Zero-config (just `npx`)
+
+| Server | Package | Command |
+|--------|---------|---------|
+| Sequential Thinking | [`@modelcontextprotocol/server-sequential-thinking`](https://www.npmjs.com/package/@modelcontextprotocol/server-sequential-thinking) | `npx -y @modelcontextprotocol/server-sequential-thinking` |
+| Memory | [`@modelcontextprotocol/server-memory`](https://www.npmjs.com/package/@modelcontextprotocol/server-memory) | `npx -y @modelcontextprotocol/server-memory` |
+| ESLint | [`@eslint/mcp`](https://www.npmjs.com/package/@eslint/mcp) | `npx -y @eslint/mcp` |
+| SAP UI5 | [`@ui5/mcp-server`](https://www.npmjs.com/package/@ui5/mcp-server) | `npx -y @ui5/mcp-server` |
+
+### API key via env var
+
+| Server | Package | Env Var | Command |
+|--------|---------|---------|---------|
+| Brave Search | [`@modelcontextprotocol/server-brave-search`](https://www.npmjs.com/package/@modelcontextprotocol/server-brave-search) | `BRAVE_API_KEY` | `npx -y @modelcontextprotocol/server-brave-search` |
+| Sentry | [`@sentry/mcp-server`](https://www.npmjs.com/package/@sentry/mcp-server) | `SENTRY_AUTH_TOKEN` | `npx -y @sentry/mcp-server` |
+| Tavily | [`tavily-mcp`](https://www.npmjs.com/package/tavily-mcp) | `TAVILY_API_KEY` | `npx -y tavily-mcp` |
+| Firecrawl | [`firecrawl-mcp`](https://www.npmjs.com/package/firecrawl-mcp) | `FIRECRAWL_API_KEY` | `npx -y firecrawl-mcp` |
+| HubSpot | [`@hubspot/mcp-server`](https://www.npmjs.com/package/@hubspot/mcp-server) | API key | `npx -y @hubspot/mcp-server` |
+| LaunchDarkly | [`@launchdarkly/mcp-server`](https://www.npmjs.com/package/@launchdarkly/mcp-server) | API key | `npx -y @launchdarkly/mcp-server` |
+| Notion | [`@notionhq/notion-mcp-server`](https://www.npmjs.com/package/@notionhq/notion-mcp-server) | `OPENAPI_MCP_HEADERS` | `npx -y @notionhq/notion-mcp-server` |
+| Stripe | [`@stripe/mcp`](https://www.npmjs.com/package/@stripe/mcp) | `--api-key` arg | `npx -y @stripe/mcp --api-key ${STRIPE_API_KEY}` |
+
+Target config example with env vars:
+
+```json
+{
+  "targetId": "brave-search",
+  "adapter": "local-process",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+  "env": { "BRAVE_API_KEY": "your-key-here" },
+  "timeoutMs": 15000
+}
+```
+
+### Positional args required
+
+| Server | Package | Args | Command |
+|--------|---------|------|---------|
+| Filesystem | [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) | Directory paths | `npx -y @modelcontextprotocol/server-filesystem /path/to/dir` |
+| PostgreSQL | [`@modelcontextprotocol/server-postgres`](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres) | Connection URL | `npx -y @modelcontextprotocol/server-postgres postgres://...` |
+| SQLite | [`@modelcontextprotocol/server-sqlite`](https://www.npmjs.com/package/@modelcontextprotocol/server-sqlite) | `--db-path` | `npx -y @modelcontextprotocol/server-sqlite --db-path ./db.sqlite` |
+| Redis | [`@modelcontextprotocol/server-redis`](https://www.npmjs.com/package/@modelcontextprotocol/server-redis) | Redis URL | `npx -y @modelcontextprotocol/server-redis redis://localhost:6379` |
+| Git | [`mcp-server-git`](https://pypi.org/project/mcp-server-git/) | `--repository` | `uvx mcp-server-git --repository /path/to/repo` |
+| Nx | [`nx-mcp`](https://www.npmjs.com/package/nx-mcp) | Workspace path | `npx -y nx-mcp --workspace /path` |
+
+### Python servers (via `uvx`)
+
+Python-based MCP servers work with the `local-process` adapter as long as `uv` is installed:
+
+```json
+{
+  "targetId": "git-server",
+  "adapter": "local-process",
+  "command": "uvx",
+  "args": ["mcp-server-git", "--repository", "."],
+  "timeoutMs": 15000
+}
+```
+
+## Compatible (HTTP/SSE remote)
+
+These servers expose a hosted HTTP endpoint. Use the `http` adapter:
+
+| Server | URL | Auth |
+|--------|-----|------|
+| Cloudflare | `https://observability.mcp.cloudflare.com/mcp` | API token via `authToken` |
+| Exa | `https://mcp.exa.ai/mcp` | `EXA_API_KEY` via `authToken` |
+| Tavily (remote) | `https://mcp.tavily.com/mcp` | Bearer token via `authToken` |
+| Context7 (remote) | `https://mcp.context7.com/mcp` | Optional API key |
+
+Target config example:
+
+```json
+{
+  "targetId": "cloudflare",
+  "adapter": "http",
+  "url": "https://observability.mcp.cloudflare.com/mcp",
+  "authToken": "your-cloudflare-api-token",
+  "timeoutMs": 15000
+}
+```
+
+## Compatible (Docker)
+
+Many MCP servers ship Docker images. These work with the `local-process` adapter — Docker's `-i` flag attaches stdin/stdout, which is standard stdio transport.
+
+```json
+{
+  "targetId": "github-docker",
+  "adapter": "local-process",
+  "command": "docker",
+  "args": ["run", "-i", "--rm",
+    "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}",
+    "ghcr.io/github/github-mcp-server"],
+  "timeoutMs": 30000
+}
+```
+
+```bash
+mcp-observatory run -- docker run -i --rm ghcr.io/github/github-mcp-server
+```
+
+All official `@modelcontextprotocol/server-*` packages publish Docker images that work this way.
+
+## Known Incompatible
+
+These servers do not work with MCP Observatory due to transport or architecture constraints:
+
+| Server | Why | Workaround |
+|--------|-----|------------|
+| BrowserTools MCP | Custom WebSocket transport between Chrome extension, middleware, and MCP server | None — non-standard transport |
+| Google Drive | Requires interactive OAuth browser flow before first use | Pre-authenticate manually, then run Observatory |
+| `@modelcontextprotocol/server-map` | Times out under stdio harness | May need specific startup args |
+| `@modelcontextprotocol/server-threejs` | Closes connection before init | App-oriented, not a pure stdio server |
+| `@modelcontextprotocol/server-pdf` | Times out under probe setup | May need specific startup args |
+| `@jsonresume/mcp` | Closes connection before init | May expect different invocation |
+
+## Transport Coverage
+
+MCP Observatory covers both standard MCP transports:
+
+| Transport | Adapter | Status |
+|-----------|---------|--------|
+| **stdio** (subprocess, JSON-RPC over stdin/stdout) | `local-process` | ✅ Supported |
+| **Streamable HTTP** (POST to endpoint, SSE response) | `http` | ✅ Supported |
+| **HTTP+SSE** (deprecated, separate GET/POST endpoints) | `http` (fallback) | ✅ Supported |
+| WebSocket (non-standard) | — | ❌ Not supported |
+
+Per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), stdio and Streamable HTTP are the two standard transports. The deprecated HTTP+SSE transport is handled automatically via SDK fallback.
+
+## Ecosystem Stats
+
+Based on analysis of the top 30+ MCP servers by npm downloads:
+
+- **~85%** use stdio as primary transport → covered by `local-process` adapter
+- **~10%** are HTTP-only remote services → covered by `http` adapter
+- **~5%** support both stdio and HTTP → both adapters work
+- **<1%** use non-standard transports (WebSocket) → not supported

package/docs/decisions.md

@@ -0,0 +1,23 @@
+# Decisions
+
+These decisions exist so the repo does not drift into vague feature accumulation.
+
+## 2026-03-19: Semantics v1 stays intentionally narrow
+
+`semantics` only checks advertised capability, callable endpoint response, and minimal expected shape. The first job of MCP Observatory is to explain drift, not to claim semantic correctness it does not yet earn.
+
+## 2026-03-19: The project stays CLI-first
+
+The durable product surface is the artifact plus the report. A dashboard can wait. Until the evidence surface is boringly trustworthy, adding hosted UX would mostly be theater.
+
+## 2026-03-19: `unsupported` and `failed` remain separate
+
+`unsupported` means the target did not advertise the capability. `failed` means the capability path or startup path should have worked and did not. Collapsing those states would hide useful ecosystem truth.
+
+## 2026-03-19: installability is part of the credibility bar
+
+The package stays scoped as `@kryptosai/mcp-observatory`, and the release flow should be able to publish it. Until npm credentials are configured, GitHub release tarballs are the honest fallback. The repo should never imply a one-command install path that does not actually work.
+
+## 2026-03-19: Every release needs a reason to exist
+
+Packaging-only churn is not a release story. Every release should include at least one real-server learning, one report-quality improvement, or one schema trust improvement.

package/docs/demo.svg

@@ -0,0 +1,59 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="820" height="320" viewBox="0 0 820 320">
+  <defs>
+    <style>
+      .bg { fill: #1e1e2e; }
+      .title-bar { fill: #313244; }
+      .dot-red { fill: #f38ba8; }
+      .dot-yellow { fill: #f9e2af; }
+      .dot-green { fill: #a6e3a1; }
+      .text { fill: #cdd6f4; font-family: 'Menlo', 'Monaco', 'Courier New', monospace; font-size: 13px; }
+      .bold { fill: #cdd6f4; font-weight: bold; }
+      .dim { fill: #6c7086; }
+      .green { fill: #a6e3a1; }
+      .yellow { fill: #f9e2af; }
+      .prompt { fill: #89b4fa; }
+      .line { stroke: #45475a; stroke-width: 1; }
+    </style>
+  </defs>
+  <rect class="bg" width="820" height="320" rx="10"/>
+  <rect class="title-bar" width="820" height="36" rx="10"/>
+  <rect class="title-bar" x="0" y="26" width="820" height="10"/>
+  <circle class="dot-red" cx="20" cy="18" r="6"/>
+  <circle class="dot-yellow" cx="40" cy="18" r="6"/>
+  <circle class="dot-green" cx="60" cy="18" r="6"/>
+  <text class="dim" x="350" y="22" text-anchor="middle">mcp-observatory — scan</text>
+
+  <text class="prompt" x="20" y="65">$</text>
+  <text class="text" x="35" y="65">npx @kryptosai/mcp-observatory scan --invoke-tools</text>
+
+  <text class="bold" x="20" y="100">Discovered 2 MCP server(s):</text>
+  <text class="dim" x="30" y="118">github (from ~/.claude.json)</text>
+  <text class="dim" x="30" y="136">filesystem (from ~/.claude.json)</text>
+
+  <text class="bold" x="20" y="170">Scan Results:</text>
+
+  <text class="bold" x="20" y="195">Target</text>
+  <text class="bold" x="230" y="195">Gate</text>
+  <text class="bold" x="300" y="195">Tools</text>
+  <text class="bold" x="400" y="195">Prompts</text>
+  <text class="bold" x="510" y="195">Resources</text>
+  <text class="bold" x="630" y="195">Invoke</text>
+
+  <line class="line" x1="20" y1="203" x2="750" y2="203"/>
+
+  <text class="text" x="20" y="225">github</text>
+  <text class="green" x="230" y="225">pass</text>
+  <text class="green" x="300" y="225">pass</text>
+  <text class="green" x="400" y="225">pass</text>
+  <text class="green" x="510" y="225">pass</text>
+  <text class="yellow" x="630" y="225">partial</text>
+
+  <text class="text" x="20" y="250">filesystem</text>
+  <text class="green" x="230" y="250">pass</text>
+  <text class="green" x="300" y="250">pass</text>
+  <text class="dim" x="400" y="250">unsupported</text>
+  <text class="dim" x="510" y="250">unsupported</text>
+  <text class="green" x="630" y="250">pass</text>
+
+  <text class="dim" x="20" y="295">Checked 2 servers in 3.2s</text>
+</svg>

package/docs/directory-listing-copy.md

@@ -0,0 +1,78 @@
+# Directory And Marketplace Listing Copy
+
+## Standard Positioning
+
+MCP Observatory helps teams test, secure, and monitor MCP servers before agents depend on them.
+
+## Short Description
+
+CI, security checks, schema drift detection, reports, and badges for MCP servers.
+
+## Medium Description
+
+MCP Observatory is a CLI, GitHub Action, and MCP server for testing MCP servers before agents depend on them. It checks tools, prompts, resources, schema quality, security footguns, regressions, and drift, then generates reports and badges maintainers can share.
+
+## Long Description
+
+MCP Observatory gives MCP servers production safety rails: one-command CI setup, compatibility checks, security analysis, schema drift detection, record/replay/verify workflows, PR comments, health score badges, and static enterprise reports. It can run as a CLI, inside GitHub Actions, or as an MCP server that lets agents inspect other MCP servers.
+
+Free for local OSS use. Paid pilots are available for hosted reporting, private repo CI history, recurring security reports, certification, support, and fleet visibility.
+
+## Primary CTA
+
+Add MCP CI in one command:
+
+```bash
+npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
+```
+
+## Tags
+
+### GitHub Topics
+
+- `mcp`
+- `model-context-protocol`
+- `mcp-server`
+- `mcp-testing`
+- `mcp-security`
+- `mcp-ci`
+- `schema-drift`
+- `developer-tools`
+- `security`
+- `github-action`
+
+### Directory Tags
+
+- MCP
+- Model Context Protocol
+- Security
+- Developer Tools
+- Testing
+- CI/CD
+- Observability
+- Schema Drift
+- Regression Testing
+- AI Agents
+
+### npm Keywords
+
+- `mcp`
+- `mcp-server`
+- `model-context-protocol`
+- `mcp-testing`
+- `mcp-security`
+- `mcp-ci`
+- `schema-drift`
+- `github-action`
+- `developer-tools`
+- `security`
+- `production-monitoring`
+- `enterprise-report`
+
+## Links
+
+- README: `https://github.com/KryptosAI/mcp-observatory#readme`
+- GitHub Action: `https://github.com/KryptosAI/mcp-observatory/tree/main/action`
+- Certification guide: `https://github.com/KryptosAI/mcp-observatory/blob/main/docs/certification-distribution.md`
+- Proof: `https://github.com/KryptosAI/mcp-observatory/blob/main/docs/proof.md`
+- Commercial pilots: `https://github.com/KryptosAI/mcp-observatory/blob/main/COMMERCIAL.md`

package/docs/distribution-launch.md

@@ -0,0 +1,76 @@
+# Distribution And Pilot Launch
+
+Use this as the reversible launch motion for MCP Observatory commercialization.
+
+For the release gate and publication checklist, see [Publish And Distribution Readiness](./publish-readiness.md).
+For listing copy, use [Directory And Marketplace Listing Copy](./directory-listing-copy.md).
+For public proof, use [MCP Observatory Proof](./proof.md).
+
+## Positioning
+
+MCP Observatory helps teams test, secure, and monitor MCP servers before agents depend on them.
+
+## Public Surface Checklist
+
+- README pricing and enterprise CTA
+- npm description and keywords
+- GitHub repository homepage pointing to the README or commercial page
+- MCP directory listings updated with production/security language
+- Launch post published
+- Badge or certification language available for passing servers
+- Certification distribution loop published at [`docs/certification-distribution.md`](./certification-distribution.md)
+
+## Launch Post Draft
+
+MCP servers are becoming production dependencies. If an agent depends on a server, that server needs regression tests, security checks, and monitoring before it breaks workflows.
+
+MCP Observatory scans MCP servers, verifies capabilities, detects schema drift, records/replays sessions, and can run in CI or as an MCP server itself.
+
+Free for local OSS use. Paid pilots are available for hosted reporting, private repo CI, security reports, production monitoring, certification, support, and fleet visibility.
+
+Production MCP usage? Contact william@banksey.com.
+
+## Outreach Template
+
+Subject: MCP production testing and security checks
+
+Hi,
+
+I noticed signals that your team may be evaluating or using MCP servers. MCP Observatory helps teams test, secure, and monitor MCP servers before agents depend on them.
+
+We are running a small number of production pilots for hosted reports, private repo CI, security monitoring, certification, support, and fleet visibility.
+
+Would it be useful to compare what your MCP servers look like today and where regressions or production risk could show up?
+
+William
+
+## Helpful Maintainer PR Motion
+
+For popular MCP server repositories, open small PRs that add:
+
+- `.github/workflows/mcp-observatory.yml`
+- optional README badge
+- a short PR body explaining the security/compatibility benefit
+
+Frame this as free OSS safety infrastructure:
+
+> I added a lightweight MCP Observatory check so users can see this server is tested for compatibility, schema drift, and common security issues. It runs in GitHub Actions, comments a readable report on PRs, and does not require an account.
+
+Use the full template in [`certification-distribution.md`](./certification-distribution.md).
+
+Track each outbound wave with [`certification-campaign-template.md`](./certification-campaign-template.md).
+
+## Account Ranking Inputs
+
+Rank prospects with:
+
+- Company domain or GitHub organization
+- Evidence source: git email domain, git remote URL, hostname domain, CI provider
+- Event count and unique sessions
+- Commands used
+- Targets or servers seen
+- Production signals: CI, private repo naming, repeated scans, security checks, matrix scans
+- Confidence: high, medium, low
+- Tier recommendation: Team, Business, Enterprise, Strategic
+
+Do not publish raw emails. Keep account evidence internal.

package/docs/enterprise-outreach-playbook.md

@@ -0,0 +1,83 @@
+# Enterprise Outreach Playbook
+
+Use this playbook after running:
+
+```bash
+npm run telemetry:intelligence -- --input telemetry-exports/events-flat-full.json --out-dir reports
+```
+
+Start from `reports/telemetry-usage-summary.html` to confirm external usage before reading account rankings. Do not treat first-party CI, release workflows, or internal/personal sessions as market traction.
+
+Do not include raw personal emails in public issues, posts, or docs. Use account domains, GitHub orgs, and aggregate telemetry evidence.
+
+## Priority Accounts
+
+| Priority | Account | Evidence | Motion |
+| ---: | --- | --- | --- |
+| 1 | `thinkingdata.cn` | High-confidence external usage, repeated sessions, private-network target signal, Feishu/Lark MCP targets | Enterprise pilot |
+| 2 | `kimquy.capital` | Recent light usage across multiple sessions | Business pilot / design partner |
+| 3 | `paperstreetdata.com` | Small usage cluster | Business pilot / testimonial ask |
+| 4 | `cyberneticsplus.com` | Single company signal | Team pilot / feedback ask |
+| 5 | GitHub org/user signals | CI or repo-based usage | Team pilot unless company identity is confirmed |
+
+## ThinkingData First Email
+
+Subject: MCP security reporting for Feishu/Lark production workflows
+
+Hi,
+
+I build MCP Observatory, an open source tool for testing, securing, and monitoring MCP servers before agents depend on them.
+
+We are seeing serious production-style usage patterns around Feishu/Lark MCP workflows and internal HTTP MCP targets. I am opening a small number of enterprise pilots for teams that want hosted MCP security reports, private-repo CI history, and fleet visibility across agent environments.
+
+If your team is running MCP servers in production, I can prepare a short evidence-based report and a pilot proposal focused on:
+
+- Feishu/Lark MCP compatibility
+- private HTTP MCP health checks
+- security findings and schema drift
+- CI history and production monitoring
+- MCP fleet visibility across teams
+
+Would it be useful to compare notes this week?
+
+William
+
+## Pilot Routing
+
+- Repeated sessions + internal/private target: Enterprise Pilot, starts at `$3k/month`.
+- Major platform, AI lab, or very large company: Strategic only, `$250k+/year` anchor.
+- Light but recent company usage: Business Pilot, starts at `$999/month`.
+- GitHub-user-only or hobby-looking usage: Team Pilot, starts at `$299/month`.
+
+## Call Agenda
+
+1. Confirm whether MCP is already in production or only evaluation.
+2. Identify the owner: platform, security, AI infra, developer productivity, or app team.
+3. Ask which value matters most: CI, security report, dashboard, certification, fleet inventory, or private deployment.
+4. Offer to generate a static enterprise report from their first pilot run.
+5. Quote manually. Do not route large companies to self-serve Team/Business pricing.
+
+## Evidence Packet
+
+Prepare this before outreach:
+
+```bash
+npx @kryptosai/mcp-observatory enterprise-report \
+  --account "Account Name" \
+  --format html \
+  --output reports/account-enterprise-report.html
+```
+
+Include only aggregate facts:
+
+- company or GitHub organization domain
+- event count
+- unique sessions
+- first seen / last seen
+- commands used
+- targets seen
+- CI/private-network/security signals
+- confidence
+- recommended pilot tier
+
+Do not include raw hostnames, personal emails, tokens, or private URLs in external outreach.

package/docs/feishu-lark-mcp.md

@@ -0,0 +1,65 @@
+# Testing Feishu/Lark MCP Servers
+
+Feishu and Lark workflows often put documents, approvals, project data, and internal knowledge behind MCP servers. MCP Observatory helps teams test those servers before agents depend on them.
+
+## Local Server Check
+
+```bash
+npx @kryptosai/mcp-observatory test --security npx -y feishu-doc-mcp
+```
+
+Use `--security` when the server exposes document search, write actions, internal URLs, or credential-backed tools.
+
+## Internal HTTP MCP Check
+
+For an internal HTTP MCP endpoint, create a target file:
+
+```json
+{
+  "targetId": "feishu-doc-mcp",
+  "adapter": "http",
+  "url": "https://internal.example.com/mcp",
+  "authToken": "${FEISHU_MCP_TOKEN}",
+  "timeoutMs": 30000
+}
+```
+
+Then run:
+
+```bash
+export FEISHU_MCP_TOKEN="..."
+npx @kryptosai/mcp-observatory test --target feishu-target.json --security
+```
+
+## CI Report
+
+```yaml
+name: Feishu MCP Check
+on: [pull_request]
+
+jobs:
+  observatory:
+    runs-on: ubuntu-latest
+    env:
+      MCP_OBSERVATORY_ORG: your-company.com
+      MCP_OBSERVATORY_CONTACT: mcp-owner@your-company.com
+    steps:
+      - uses: actions/checkout@v4
+      - uses: KryptosAI/mcp-observatory/action@main
+        with:
+          target: feishu-target.json
+          security: true
+```
+
+## Enterprise Report
+
+```bash
+npx @kryptosai/mcp-observatory enterprise-report \
+  --account "Feishu MCP production fleet" \
+  --format html \
+  --output feishu-mcp-report.html
+```
+
+Production teams can use the report for MCP owner reviews, private-repo CI history, security review, and certification conversations.
+
+Contact `william@banksey.com` for production Feishu/Lark MCP usage, hosted reporting, private deployment, or fleet visibility.

package/docs/known-issues.md

@@ -0,0 +1,27 @@
+# Known Issues
+
+## `unsupported` vs `failed`
+
+This distinction is one of the main reasons the repo exists.
+
+- `unsupported` means the target did not advertise the capability. Example: `@modelcontextprotocol/server-filesystem` currently surfaces `prompts` and `resources` as `unsupported`.
+- `failed` means the capability path or startup path should have worked and did not. Example: a target that advertises a capability but errors during the list call, or a package that closes the connection before initialization completes.
+
+Collapsing those states would make the ecosystem look simpler than it is.
+
+## Not every MCP package is a drop-in stdio target
+
+Some packages in the ecosystem are app-oriented, require additional startup flags, or close immediately when invoked like a plain local-process stdio server. That is not a failure of MCP Observatory; it is useful ecosystem signal.
+
+Observed examples during launch hardening:
+
+- `@modelcontextprotocol/server-map` timed out under the current local-process harness
+- `@modelcontextprotocol/server-threejs` closed the connection before initialization completed
+- `@jsonresume/mcp` closed the connection before initialization completed
+- `@modelcontextprotocol/server-pdf` timed out under the current probe setup
+
+These are good candidates for future integration work because they help clarify:
+
+- stdio vs app/server transport expectations
+- startup requirements for package-specific servers
+- how MCP Observatory should present connection/setup failures clearly

package/docs/mcp-safety-report-latest.md

@@ -0,0 +1,85 @@
+# MCP Safety Report
+
+Latest generated baseline: June 19, 2026.
+
+MCP servers are becoming production dependencies. When agents depend on a server, that server needs repeatable compatibility checks, security review, schema drift detection, and visible trust signals.
+
+## What Observatory Checks
+
+MCP Observatory checks:
+
+- tools, prompts, and resources list/respond correctly
+- advertised capabilities match observed behavior
+- safe read-only tools can be invoked
+- schemas are usable by agents
+- security footguns are visible before production use
+- runs can be compared for regressions and schema drift
+- artifacts can be rendered as JSON, Markdown, HTML, JUnit, SARIF, or PR comments
+
+## Aggregate Usage Snapshot
+
+Safe aggregate telemetry from the latest local export:
+
+| Metric | Value |
+| --- | ---: |
+| Total telemetry events | 10,278 |
+| Unique sessions | 7,211 |
+| External sessions | 5,368 |
+| External CI sessions | 2,434 |
+| Attributed company/org sessions | 128 |
+
+Top external commands:
+
+1. `serve`
+2. `run`
+3. `diff`
+4. `test`
+5. `scan`
+6. `history`
+
+No raw emails, hostnames, private URLs, tokens, or response bodies are included in this report.
+
+## Common MCP Failure Classes
+
+From public sample artifacts and Observatory check categories, the most important failure classes are:
+
+- server startup failure
+- malformed or missing tools/list, prompts/list, or resources/list responses
+- schema quality issues that make tools harder for agents to call correctly
+- regressions between two runs
+- unexpected drift from a recorded baseline
+- broad filesystem/network/security-sensitive tool surfaces
+- slow or unreliable connection behavior
+
+## How Maintainers Add The Check
+
+```bash
+npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
+```
+
+That creates a GitHub Action and a README badge snippet. The action can comment on PRs and fail when MCP compatibility or security checks regress.
+
+## Production Path
+
+Production teams can use MCP Observatory for:
+
+- private repo CI history
+- hosted reporting
+- recurring security reports
+- MCP certification
+- support and rollout review
+- fleet visibility across teams and repos
+
+Contact `william@banksey.com` for pilots.
+
+## Launch Post
+
+MCP servers are becoming production dependencies.
+
+I built MCP Observatory so MCP maintainers can add CI, security checks, schema drift detection, PR reports, and trust badges in one command:
+
+```bash
+npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
+```
+
+Free for local OSS use. Paid pilots are available for hosted reporting, private repo CI, certification, support, and fleet visibility.