@kryptosai/mcp-observatory 0.20.3 → 0.21.0

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 --command "npx -y my-mcp-server" --badge
+```
+
+## 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 --command "npx -y my-mcp-server" --badge
+```
+
+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 --command "npx -y my-mcp-server" --badge
+```
+
+Free for local OSS use. Paid pilots are available for hosted reporting, private repo CI, certification, support, and fleet visibility.

package/docs/project-case-study.md

@@ -0,0 +1,106 @@
+# MCP Observatory Case Study
+
+## One-Line Summary
+
+MCP Observatory is CI/security infrastructure for production MCP servers.
+
+## Problem
+
+MCP servers are becoming dependencies for AI agents. Teams need to know whether those servers still start, expose usable tools, keep schemas stable, avoid obvious security footguns, and behave consistently as agents depend on them.
+
+## Product
+
+MCP Observatory provides:
+
+- CLI checks for MCP servers
+- MCP server mode so agents can inspect other MCP servers
+- GitHub Action integration
+- PR comments and commit status checks
+- JSON, Markdown, HTML, JUnit, SARIF, and PR-comment reports
+- schema drift detection
+- record/replay/verify workflows
+- health score badges
+- static enterprise reports
+- telemetry intelligence for product and account-level learning
+
+## Architecture
+
+The project is a TypeScript/Node CLI with modular command handlers, MCP adapters, check runners, reporters, artifact schemas, and a GitHub Action wrapper. A Cloudflare Worker handles hosted artifact upload pilots, and a separate telemetry Worker stores private aggregate usage events in D1.
+
+## Technical Proof
+
+As of June 19, 2026:
+
+- 10k+ source lines in `src`
+- 40 test files
+- 321 passing tests
+- npm package published
+- GitHub Action available
+- MCP server mode available
+- telemetry export and company intelligence tooling available
+
+## Traction Snapshot
+
+Safe public and aggregate signals:
+
+- 10,278 telemetry events
+- 7,211 telemetry sessions
+- 5,368 external sessions after separating internal activity
+- 582 GitHub clones and 175 unique cloners in the visible June 2026 traffic window
+- 104 npm downloads during June 11-17, 2026
+
+These are early signals. Public social proof is still limited and should be improved through the certification campaign.
+
+## Security And Privacy Posture
+
+The project includes:
+
+- telemetry opt-out controls
+- privacy disclosure
+- security policy
+- token-based hosted artifact upload
+- private-network rejection for hosted scans
+- sanitized public reporting policy
+
+Public claims should use aggregate metrics and accepted public integrations, not raw telemetry.
+
+## Commercial Path
+
+The free OSS wedge is local testing and public repo CI. Paid value is production/private use:
+
+- hosted CI history
+- private repo reporting
+- recurring security reports
+- certification
+- support
+- fleet visibility
+- enterprise review
+
+Current pilot anchors:
+
+- Team: starts at `$299/month`
+- Business: starts at `$999/month`
+- Enterprise: starts at `$3k/month`
+- Strategic: `$250k+/year`
+
+## Job-Opportunity Value
+
+This project demonstrates ability across:
+
+- AI infrastructure
+- developer tooling
+- security tooling
+- MCP ecosystem work
+- CI/CD integrations
+- telemetry and product analytics
+- commercialization and enterprise packaging
+
+It is strongest as a portfolio asset when paired with public proof: accepted external PRs, badges in other repos, directory listings, and a short demo.
+
+## Next Milestones
+
+1. Publish latest package with `init-ci`.
+2. Open first certification PR wave.
+3. Capture accepted PRs as public proof.
+4. Publish recurring MCP safety reports.
+5. Convert serious users into paid pilots.

package/docs/proof.md

@@ -0,0 +1,68 @@
+# MCP Observatory Proof
+
+MCP Observatory is early, but it is already a working MCP testing/security stack rather than a landing page.
+
+## Current Public Surface
+
+- npm package: `@kryptosai/mcp-observatory`
+- GitHub Action: `KryptosAI/mcp-observatory/action@main`
+- CLI command count: scan, test, record, replay, verify, diff, watch, suggest, serve, lock, history, init-ci, ci-report, enterprise-report, score, badge, cloud
+- Test suite: 321 passing tests across 40 test files as of June 19, 2026
+- GitHub traffic snapshot: 582 clones and 175 unique cloners in the visible June 2026 traffic window
+- npm downloads snapshot: 104 downloads for June 11-17, 2026
+
+## Safe Aggregate Telemetry Snapshot
+
+Internal telemetry is used for product analytics and account-level outreach. Public reporting uses only aggregate or sanitized data.
+
+As of the latest local export on June 19, 2026:
+
+- 10,278 telemetry events
+- 7,211 unique sessions
+- 5,368 external sessions after separating internal/personal activity
+- 2,434 external CI sessions
+- 128 attributed company/org sessions
+- top external commands: `serve`, `run`, `diff`, `test`, `scan`, `history`
+
+Raw emails, hostnames, private URLs, tokens, and response bodies are not published.
+
+## Product Proof
+
+MCP Observatory can:
+
+- install as an npm CLI
+- run as an MCP server
+- test local-process and HTTP MCP targets
+- run in GitHub Actions
+- post PR comments
+- generate JSON, Markdown, HTML, JUnit, SARIF, and PR-comment reports
+- generate health badges
+- record/replay/verify MCP sessions
+- detect schema drift
+- run lightweight MCP security checks
+- create static enterprise reports from artifacts
+
+## Certification Proof
+
+The certification campaign is designed to create public proof through accepted maintainer PRs.
+
+Accepted third-party integrations will be tracked here:
+
+| Repo | PR | Check Added | Badge Added | Status |
+| --- | --- | --- | --- | --- |
+| _pending_ | | | | |
+
+## Commercial Proof
+
+Current paid positioning is pilot-first:
+
+- Team Pilot: starts at `$299/month`
+- Business Pilot: starts at `$999/month`
+- Enterprise Pilot: starts at `$3k/month`
+- Strategic Accounts: custom, `$250k+/year`
+
+Paid value is production use: hosted reporting, private repo CI history, security reports, certification, support, fleet visibility, and enterprise review.
+
+## Claims Policy
+
+Use public proof for public claims. Company-domain telemetry signals are private and should only be used internally for outreach unless a customer gives permission or there is independent public evidence.

package/docs/publish-readiness.md

@@ -0,0 +1,73 @@
+# Publish And Distribution Readiness
+
+Use this checklist before a commercialization push. The goal is to increase distribution and start paid conversations without locking the project into a permanent licensing or product shape.
+
+## Release Gate
+
+Run:
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+npm test
+npm run validate:artifacts
+npm audit --json
+```
+
+Confirm:
+
+- GitHub Action target scans support `deep`, `security`, and baseline drift failure.
+- `schemas/run-artifact.schema.json` and `schemas/diff-artifact.schema.json` validate current artifacts.
+- HTTP target examples use env references instead of inline tokens.
+- Security findings appear in artifact evidence as structured `findings`.
+- Hosted upload is available through `mcp-observatory cloud upload <artifact>` when `MCP_OBSERVATORY_CLOUD_TOKEN` is set.
+
+## Public Distribution
+
+- Merge the health/commercialization PR.
+- Update the GitHub repo homepage to the README or commercial page.
+- Publish npm only after the release gate is green.
+- Refresh MCP directory listings with: “MCP Observatory helps teams test, secure, and monitor MCP servers before agents depend on them.”
+- Include “free for local OSS use; paid for hosted reporting, private repo CI, security reports, production monitoring, certification, support, and fleet visibility.”
+- Link production users to `COMMERCIAL.md` and `william@banksey.com`.
+- Submit or refresh listings on Glama, PulseMCP, Smithery, and relevant awesome-MCP lists with the tags: security, developer tools, CI/CD, testing, observability, schema drift.
+- Use the certification distribution loop to open helpful PRs against popular MCP server repos and convert accepted PRs into proof points.
+- Link public proof, the safety report, and directory listing copy from launch/outreach materials.
+
+## Sales Operating Loop
+
+1. Export telemetry rows privately.
+2. Run:
+
+```bash
+npx tsx scripts/telemetry-company-intelligence.ts --input telemetry-events.jsonl --out-dir reports
+```
+
+3. Review `reports/telemetry-company-intelligence.html`.
+4. Contact the top 25 high-confidence company/org candidates.
+5. For large or strategic domains, quote Strategic only and ask for a security/procurement path.
+6. Use hosted artifact upload or static enterprise reports before building a full SaaS dashboard.
+
+## Hosted Upload
+
+CLI:
+
+```bash
+export MCP_OBSERVATORY_CLOUD_TOKEN="pilot-token"
+export MCP_OBSERVATORY_ORG="customer.com"
+npx @kryptosai/mcp-observatory cloud upload .mcp-observatory/runs/<run>.json
+```
+
+Worker:
+
+- `POST /api/v1/artifacts` stores a run artifact behind bearer-token auth.
+- `GET /api/v1/artifacts/:org` returns the org artifact index behind the same auth.
+- Hosted scans reject localhost/private-network targets; use local CLI for internal MCP servers.
+
+## What Not To Do Yet
+
+- Do not change the MIT license until paid signal demands it.
+- Do not hard-paywall existing local OSS checks.
+- Do not build a full dashboard before a buyer asks for dashboard workflows.
+- Do not publish raw telemetry emails or individual PII in public materials.