@kryptosai/mcp-observatory 0.26.0 → 0.27.0

package/docs/ecosystem-distribution-kit.md

@@ -1,79 +0,0 @@
-# Ecosystem Distribution Kit
-
-Use this kit when submitting MCP Observatory to directories, marketplaces, newsletters, and awesome lists.
-
-## One-Line Description
-
-MCP Observatory is the CI and security gate for MCP servers before agents depend on them.
-
-## Short Listing
-
-MCP Observatory tests MCP servers for startup health, capability discovery, schema drift, common security footguns, health scoring, badges, and GitHub Action CI. It can run locally, in CI, or as an MCP server for agent-accessible diagnostics.
-
-## Tags
-
-- MCP
-- MCP security
-- AI security
-- agent security
-- developer tools
-- CI/CD
-- schema drift
-- supply chain security
-- testing
-- GitHub Actions
-
-## Primary CTA
-
-```bash
-npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y <server-package>"
-```
-
-## Directory Targets
-
-Prioritize surfaces where users already look for MCP infrastructure:
-
-- MCP server directories
-- MCP developer-tool lists
-- AI security lists
-- GitHub Action Marketplace
-- awesome-MCP repositories
-- agent framework docs and community lists
-- npm package discovery through keywords and README copy
-
-## Submission Checklist
-
-- Link to the README.
-- Link to `CLONED_THIS.md` for immediate adoption.
-- Include the `setup-ci` command.
-- Mention free local OSS use.
-- Mention paid pilots only as production support: hosted history, private readiness review, drift/security reports, certification, support, and fleet visibility.
-- Do not include private telemetry, account names, hostnames, emails, or customer claims.
-
-## Marketplace Copy
-
-Title:
-
-> MCP Observatory CI
-
-Description:
-
-> Add MCP compatibility, schema drift, and security checks to GitHub Actions before agents depend on your server.
-
-Snippet:
-
-```yaml
-- uses: KryptosAI/mcp-observatory/action@v0.25.1
-  with:
-    command: npx -y <server-package>
-    deep: true
-    security: true
-```
-
-## Paid Pilot Demo
-
-Use a sanitized sample report when someone asks what the private review produces:
-
-```bash
-npx @kryptosai/mcp-observatory enterprise-report --sample --format html --output reports/sample-enterprise-report.html
-```

package/docs/enterprise-outreach-playbook.md

@@ -1,83 +0,0 @@
-# Enterprise Outreach Playbook
-
-Use this playbook after running:
-
-```bash
-npm run telemetry:intelligence -- --input <private-telemetry-export.jsonl> --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.
-
-Raw telemetry is allowed for internal account intelligence only. Do not include personal emails, hostnames, private URLs, target commands, tokens, proprietary schemas, customer names, or private telemetry exports in public issues, posts, docs, or customer-facing outreach without explicit permission. Keep account-specific rankings in ignored `reports/` outputs or private notes.
-
-## Priority Accounts
-
-| Priority | Account | Evidence | Motion |
-| ---: | --- | --- | --- |
-| 1 | Private account A | Repeated external sessions, CI usage, private-target signal, or security workflow evidence | Enterprise pilot |
-| 2 | Private account B | Recent usage across multiple sessions or repos | Business pilot / design partner |
-| 3 | Private account C | Small usage cluster with clear owner signal | Business pilot / testimonial ask |
-| 4 | Private account D | Single company or team signal | Team pilot / feedback ask |
-| 5 | GitHub org/user signals | CI or repo-based usage | Team pilot unless company identity is confirmed |
-
-## First Email Template
-
-Subject: MCP security reporting for production agent workflows
-
-Hi,
-
-I build MCP Observatory, an open source tool for testing, securing, and monitoring MCP servers before agents depend on them.
-
-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:
-
-- MCP compatibility
-- private HTTP MCP health checks
-- security findings and schema drift
-- CI history and controlled drift review
-- 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/paid-pilot-offer.md

@@ -1,74 +0,0 @@
-# Paid Pilot Offer
-
-## Private MCP Readiness Review
-
-Offer:
-
-> Private MCP readiness review + CI rollout + drift/security report.
-
-This is a manual pilot, not a self-serve SaaS promise.
-
-## Who It Is For
-
-- teams running MCP servers in production or pre-production
-- security/platform teams reviewing agent tool dependencies
-- companies with private MCP repos
-- teams that need proof before agents depend on internal tools
-
-## What The Pilot Includes
-
-- MCP server inventory across selected repos, configs, or agent environments
-- reproducible test artifacts for each reviewed server
-- private readiness report covering startup, capabilities, schema quality, security findings, and drift risk
-- schema/tool drift baseline using MCP lock files
-- MCP Observatory CI rollout plan for selected servers
-- executive summary with “safe for agent dependency” verdicts
-- prioritized remediation notes and owner-ready next steps
-- optional certification language for servers that pass agreed checks
-
-## Starting Prices
-
-- Business Pilot: starts at `$999/month`
-- Enterprise Pilot: starts at `$3k/month`
-- Strategic Accounts: custom, `$250k+/year`
-
-Do not route major platforms, AI labs, or large enterprises to Team/Business pricing. Use a production/security pilot conversation and ask for the owner or procurement path.
-
-## Simple Outreach Copy
-
-Subject: Private MCP readiness review
-
-Hi,
-
-I build MCP Observatory, the CI and security gate for MCP servers before agents depend on them.
-
-I am opening a small number of private MCP readiness pilots for teams running MCP in production or pre-production. The pilot includes CI rollout, schema/security review, drift checks, and a private readiness report for your MCP servers.
-
-If MCP is becoming part of your agent infrastructure, I can help you answer:
-
-- which servers are safe enough for agents to depend on?
-- which tool surfaces changed recently?
-- where are the schema/security risks?
-- what should block a PR before production?
-
-Would it be useful to compare notes this week?
-
-William
-
-## Delivery Shape
-
-Start with static reports and CI setup. The first deliverable should look like an internal security/readiness packet, not a SaaS login.
-
-## Evidence Standard
-
-The public [Safety Methodology](./methodology.md) and [MCP Server Safety Index](./mcp-server-safety-index.md) are the template for private work:
-
-- command/config used
-- date and tool version
-- JSON artifact
-- Markdown or HTML report
-- failure class
-- verdict
-- reproduction notes
-
-Private pilots can include customer-specific details, but public/customer-facing summaries should use sanitized evidence unless the customer approves otherwise.

package/docs/project-case-study.md

@@ -1,140 +0,0 @@
-# MCP Observatory Case Study
-
-## One-Line Summary
-
-MCP Observatory is CI/security infrastructure for production MCP servers.
-
-## Project Narrative
-
-MCP Observatory identifies an emerging risk in AI agent infrastructure and turns it into a practical OSS control: CI checks, security reports, drift detection, telemetry intelligence, and certification workflows for production MCP servers.
-
-The project is strongest as a signal because it connects product intuition with implementation depth. It starts from a real infrastructure shift, builds a working developer tool around that shift, instruments usage, and creates a credible path from open source adoption to production security workflows.
-
-## Problem Discovery
-
-MCP servers are becoming dependencies for AI agents. They expose tools, prompts, resources, and data access that agents can call directly. When those servers drift, fail to start, expose broad capabilities, or return ambiguous schemas, the failure can propagate into agent workflows.
-
-The control gap is simple: teams need a way to test MCP servers before agents depend on them. They also need artifacts that maintainers, platform engineers, and security reviewers can understand.
-
-## 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
-
-## System Design
-
-The project is a TypeScript/Node CLI with modular command handlers, MCP adapters, check runners, reporters, artifact schemas, and a GitHub Action wrapper.
-
-The system supports local-process and HTTP MCP targets, stores run artifacts, compares runs for regressions, generates reports for humans and CI systems, and can run as an MCP server itself. A Cloudflare Worker handles hosted artifact upload pilots. A separate telemetry Worker stores private aggregate usage events in D1 for product and account intelligence.
-
-## Security Model
-
-MCP Observatory treats MCP servers as agent-facing infrastructure. The goal is not to claim formal semantic safety. The goal is to make compatibility, drift, and obvious security risk visible before deployment.
-
-Current controls include:
-
-- lightweight security checks for risky schema patterns
-- schema quality analysis for agent usability
-- SARIF output for security review workflows
-- support for security suppressions when broad tools are intentional
-- private-network rejection for hosted scans
-- privacy disclosure and telemetry opt-out controls
-- sanitized public reporting policy
-
-For deeper context, see the [MCP Server Security Field Guide](./mcp-security-field-guide.md).
-
-## Telemetry Intelligence
-
-Telemetry is used privately to understand product usage and identify account-level signals without publishing raw personal data.
-
-As of the latest local export on June 21, 2026:
-
-- 11,481 telemetry events
-- 7,571 total sessions
-- 5,389 external sessions after separating internal activity
-- 2,446 external CI sessions
-- 148 attributed company/org sessions
-- 12 attributed company/org candidates
-- latest external activity: June 21, 2026
-
-Public claims use aggregate or sanitized data only. Raw emails, hostnames, private URLs, tokens, and response bodies are not published.
-
-## Distribution Strategy
-
-The distribution wedge is useful CI for other MCP repositories. The certification campaign opens small, helpful PRs that add MCP compatibility/security checks and leave maintainers with a public trust signal.
-
-Current public distribution proof includes:
-
-- latest release: `v0.25.1`
-- npm package: `@kryptosai/mcp-observatory`
-- GitHub Action: `KryptosAI/mcp-observatory/action@main`
-- npm downloads snapshot: 511 downloads for June 11-20, 2026
-- visible GitHub traffic window: 745 clones and 232 unique cloners
-- visible GitHub page-view window: 12 views and 9 unique visitors
-- public code-search references in MCP indexes, listing mirrors, and external experiment repos
-- official MCP reference PR open and green: [`modelcontextprotocol/servers#4392`](https://github.com/modelcontextprotocol/servers/pull/4392)
-- open certification PRs for Microsoft Playwright MCP, Upstash Context7, ExecuteAutomation Playwright MCP, AntV, BrowserMCP, UI5, Notion, and other MCP projects
-
-See [reference evaluations](./reference-evaluations.md) and [public proof](./proof.md).
-
-## 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`
-
-## Professional Signal
-
-MCP Observatory demonstrates applied work across:
-
-- AI agent infrastructure
-- developer tooling
-- secure tool invocation
-- software supply chain thinking
-- CI/CD integrations
-- telemetry and product analytics
-- open source distribution
-- enterprise packaging
-
-It is designed to be evaluated through public work: code, docs, CI integrations, reference evaluations, proof surfaces, and real maintainer PRs.
-
-## Future Roadmap
-
-Near-term milestones:
-
-1. Convert certification PRs into accepted public integrations.
-2. Publish recurring MCP safety reports.
-3. Add stronger policy/provenance language for production MCP adoption.
-4. Improve hosted artifact upload into a simple pilot workflow.
-5. Convert serious production users into paid pilots.
-
-Longer-term opportunities:
-
-- policy controls for agent tool use
-- provenance for MCP packages and configurations
-- schema locks and controlled drift review
-- runtime monitoring for production agent tool calls
-- fleet inventory across teams, repositories, and hosts

package/docs/public-post-drafts.md

@@ -1,98 +0,0 @@
-# Public Post Drafts
-
-Use these as launch posts, GitHub Discussion posts, LinkedIn posts, or short blog drafts. The framing is about MCP safety patterns, not “look at my tool.”
-
-## Flagship Post: I Tested Popular MCP Servers. The Failure Pattern Was Not What I Expected.
-
-MCP servers are becoming production dependencies for agents, but many of them still ship without the kind of CI gate we expect from normal software dependencies.
-
-The main pattern I saw while building the first MCP Server Safety Index was simple: the risky part is rarely that a server exists. The risky part is that agents may depend on a tool surface nobody is testing for startup reliability, schema quality, security posture, or drift.
-
-The industry does not need another vibes-based directory. It needs reproducible readiness evidence:
-
-- exact command/config
-- date and package version where available
-- JSON artifact
-- Markdown report
-- verdict
-- failure class
-- reproduction notes
-
-The checks that matter most:
-
-- does the server start cleanly in CI?
-- do tools, prompts, and resources respond as advertised?
-- are tool schemas precise enough for agents to call safely?
-- did a release add, remove, or broaden a tool?
-- are destructive tools clearly identifiable?
-
-My takeaway: MCP needs a package-lock moment. Commit the agent-facing contract, then make drift visible before agents depend on it.
-
-I am publishing the Safety Methodology and the first MCP Server Safety Index as a small evidence standard, not a leaderboard. If your team is putting MCP into private or production agent workflows, I am doing a small number of private MCP readiness reviews: inventory, CI rollout, schema/tool drift baseline, security findings, and safe-for-agent-dependency verdicts.
-
-## Supporting Angle: Browser MCP Servers Need A Different Security Bar
-
-Browser automation MCP servers are powerful because agents can navigate pages, click, type, inspect state, and sometimes execute scripts.
-
-That is exactly why they need explicit CI and security gates.
-
-For browser MCP servers, a useful review should separate:
-
-- harmless inventory checks
-- state-mutating browser actions
-- code execution or page-evaluation tools
-- network/navigation controls
-- tool schemas that are too broad for safe agent planning
-
-The goal is not to block browser MCP. The goal is to make the trust boundary visible before an agent gets browser-control powers.
-
-## Supporting Angle: Filesystem MCP Servers Should Always Test In A Sandbox
-
-Filesystem MCP servers are one of the clearest examples of why MCP CI needs context.
-
-A server can be useful and still dangerous if the test command points at the wrong directory, if read/write boundaries are unclear, or if a tool schema makes broad path access look harmless.
-
-The minimum safety pattern:
-
-- run CI against a temporary harmless directory
-- verify tools/resources respond as advertised
-- flag broad filesystem access
-- document which operations are read-only vs write-capable
-- treat changes to path schemas as contract drift
-
-Agents need tools. They do not need accidental access to everything.
-
-## Supporting Angle: Token-Backed SaaS MCP Servers Need Issue-First Certification
-
-Many SaaS, cloud, payments, database, and developer-platform MCP servers cannot be safely checked with a drive-by PR because meaningful startup requires tokens or live services.
-
-For those repos, the right move is usually not a workflow PR first. It is an issue or maintainer question:
-
-“What is the safest CI startup command for this server?”
-
-Once maintainers provide a token-safe target config, the useful checks are:
-
-- does startup fail cleanly without credentials?
-- are auth requirements documented?
-- are destructive tools obvious?
-- are schemas narrow enough for agent use?
-- can the repo publish a safe compatibility/security badge?
-
-Security adoption works better when it starts by respecting maintainer context.
-
-## Supporting Angle: MCP Drift Is An AI Supply Chain Problem
-
-When a package dependency changes, teams have lock files, diffs, review, and release notes.
-
-When an MCP server changes its tool surface, an agent dependency changed too.
-
-That means tool additions, tool removals, schema broadening, new write actions, and prompt/resource changes should be visible in pull requests.
-
-The useful primitive is an MCP lock file:
-
-```bash
-npx @kryptosai/mcp-observatory lock
-npx @kryptosai/mcp-observatory lock verify
-```
-
-The point is not bureaucracy. It is to make the agent-facing contract reviewable before production workflows quietly depend on something new.

package/docs/publish-readiness.md

@@ -1,79 +0,0 @@
-# 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.
-- Hosted HTTP scans require `Authorization: Bearer <HOSTED_SCAN_TOKEN>` and are treated as an authenticated pilot surface.
-
-Known audit note:
-
-- Release automation runs `semantic-release` ephemerally in GitHub Actions instead of installing it into the repository lockfile. This keeps release-only bundled dependencies out of the default-branch audit surface and out of the packed CLI artifact.
-
-## 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 is the CI and security gate for MCP servers before agents depend on them.”
-- Include “free for local OSS use; paid for hosted reporting, private repo CI, recurring security reports, 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, MCP security, 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.
-- `POST /api/v1/scan` requires `Authorization: Bearer <HOSTED_SCAN_TOKEN>`.
-- 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.