@kryptosai/mcp-observatory 0.22.0 → 0.23.0

package/docs/directory-listing-copy.md

@@ -2,22 +2,24 @@
 
 ## Standard Positioning
 
-MCP Observatory helps teams test, secure, and monitor MCP servers before agents depend on them.
+MCP Observatory is the CI and security gate for MCP servers before agents depend on them.
 
 ## Short Description
 
-CI, security checks, schema drift detection, reports, and badges for MCP servers.
+CI, security checks, schema drift detection, lock files, 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.
+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 lock files, 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.
+MCP Observatory gives MCP servers production safety rails: one-command CI setup, compatibility checks, security analysis, schema drift detection, lock-file verification, 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.
 
+For security and platform teams, see the MCP Server Security Field Guide and MCP Server Safety Index for agent security, AI supply chain security, and production MCP server review guidance.
+
 ## Primary CTA
 
 Add MCP CI in one command:
@@ -49,7 +51,6 @@ npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
 - Developer Tools
 - Testing
 - CI/CD
-- Observability
 - Schema Drift
 - Regression Testing
 - AI Agents
@@ -66,6 +67,8 @@ npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
 - `github-action`
 - `developer-tools`
 - `security`
+- `agent-security`
+- `ai-supply-chain`
 - `production-monitoring`
 - `enterprise-report`
 
@@ -73,6 +76,10 @@ npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
 
 - README: `https://github.com/KryptosAI/mcp-observatory#readme`
 - GitHub Action: `https://github.com/KryptosAI/mcp-observatory/tree/main/action`
+- Security field guide: `https://github.com/KryptosAI/mcp-observatory/blob/main/docs/mcp-security-field-guide.md`
+- Reference evaluations: `https://github.com/KryptosAI/mcp-observatory/blob/main/docs/reference-evaluations.md`
+- Safety index: `https://github.com/KryptosAI/mcp-observatory/blob/main/docs/mcp-server-safety-index.md`
+- Lock files: `https://github.com/KryptosAI/mcp-observatory/blob/main/docs/mcp-lock-files.md`
 - 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

@@ -8,7 +8,7 @@ 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.
+MCP Observatory is the CI and security gate for MCP servers before agents depend on them.
 
 ## Public Surface Checklist
 
@@ -22,11 +22,11 @@ MCP Observatory helps teams test, secure, and monitor MCP servers before agents
 
 ## 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 servers are becoming production dependencies. If an agent depends on a server, that server needs regression tests, security checks, and drift gates 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.
+Free for local OSS use. Paid pilots are available for hosted reporting, private repo CI, recurring security reports, certification, support, and fleet visibility.
 
 Production MCP usage? Contact william@banksey.com.
 
@@ -36,9 +36,9 @@ 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.
+I noticed signals that your team may be evaluating or using MCP servers. MCP Observatory is the CI and security gate for 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.
+We are running a small number of production pilots for hosted reports, private repo CI, recurring security reviews, 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?
 

package/docs/enterprise-outreach-playbook.md

@@ -8,7 +8,7 @@ npm run telemetry:intelligence -- --input telemetry-exports/events-flat-full.jso
 
 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.
+Raw telemetry is allowed for internal account intelligence and may include git email, git remote URL, hostname, target command or URL, CI metadata, target IDs, and command outcomes. Do not include raw personal emails, hostnames, private URLs, target commands, tokens, or private telemetry exports in public issues, posts, docs, or customer-facing outreach. Use account domains, GitHub orgs, and aggregate telemetry evidence.
 
 ## Priority Accounts
 
@@ -35,7 +35,7 @@ If your team is running MCP servers in production, I can prepare a short evidenc
 - Feishu/Lark MCP compatibility
 - private HTTP MCP health checks
 - security findings and schema drift
-- CI history and production monitoring
+- CI history and controlled drift review
 - MCP fleet visibility across teams
 
 Would it be useful to compare notes this week?

package/docs/mcp-lock-files.md

@@ -0,0 +1,63 @@
+# MCP Lock Files
+
+MCP lock files are the package-lock for AI tools.
+
+They capture the MCP contract a server exposes to agents: tools, prompts, resources, and tool input schemas. Once committed, CI can verify that future changes are intentional before agents depend on a changed surface.
+
+## Core Flow
+
+Create the lock:
+
+```bash
+npx @kryptosai/mcp-observatory lock
+```
+
+Verify the live server still matches:
+
+```bash
+npx @kryptosai/mcp-observatory lock verify
+```
+
+Add CI:
+
+```bash
+npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
+```
+
+## Why It Matters
+
+Agents call tools based on schemas and descriptions. If a tool is added, removed, renamed, or made more permissive, the agent-facing contract changed.
+
+Lock verification turns that into a reviewable event:
+
+- what changed
+- whether a tool, prompt, or resource was added or removed
+- whether a tool schema changed
+- whether the changed MCP surface should be accepted before release
+
+## Production Positioning
+
+For maintainers, lock files catch accidental breakage.
+
+For security and platform teams, lock files create an approval point for AI supply chain changes. A production MCP server can treat new tools, broader schemas, and high-risk capabilities like dependency changes that deserve review.
+
+## Recommended CI Policy
+
+- Commit `.mcp-observatory/lock.json` for production MCP servers.
+- Run `mcp-observatory lock verify` on pull requests.
+- Treat drift as blocking unless the PR intentionally updates the MCP surface.
+- Pair lock verification with `--security` checks before major releases.
+- Record suppressions with an owner, reason, and expiration when accepted risk is intentional.
+
+## Commercial Pilot Use
+
+Paid pilots can turn lock verification into a recurring MCP readiness report:
+
+- current MCP surface
+- drift since last approved lock
+- new or removed tools
+- schema changes
+- security findings
+- recommended review actions
+
+This is the simplest enterprise story: commit your MCP contract, then make drift visible before agents depend on it.

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

@@ -1,9 +1,11 @@
 # MCP Safety Report
 
-Latest generated baseline: June 19, 2026.
+Latest generated baseline: June 20, 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.
 
+For a broader security framing, see the [MCP Server Security Field Guide](./mcp-security-field-guide.md). For public examples, see [Reference Evaluations](./reference-evaluations.md).
+
 ## What Observatory Checks
 
 MCP Observatory checks:
@@ -22,11 +24,13 @@ 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 |
+| Total telemetry events | 10,918 |
+| Total sessions | 7,380 |
+| External sessions | 5,379 |
+| External CI sessions | 2,446 |
+| Attributed company/org sessions | 138 |
+| GitHub clones in visible traffic window | 721 |
+| Unique cloners in visible traffic window | 221 |
 
 Top external commands:
 

package/docs/mcp-security-field-guide.md

@@ -0,0 +1,97 @@
+# MCP Server Security Field Guide
+
+MCP servers are becoming part of AI agent infrastructure. They expose tools that agents can call, often with access to files, browsers, cloud APIs, databases, documents, and internal systems. That makes MCP security a practical engineering problem: teams need to know which tools exist, what they can touch, how their schemas change, and whether they are safe enough for production agent workflows.
+
+MCP Observatory is built around that control point. It gives maintainers and platform teams a repeatable way to test production MCP servers, add MCP server CI, detect schema drift, and surface agent security risk before agents depend on a tool.
+
+## Why MCP Servers Are An Agent-Facing Attack Surface
+
+Traditional libraries run inside an application boundary. MCP servers sit beside an agent and expose capabilities the model may choose to call. A small schema mistake, broad tool surface, or unreliable startup path can become an operational risk when the server is wired into an autonomous workflow.
+
+Important MCP risk patterns include:
+
+- **Tool overreach:** tools that expose shell, browser, filesystem, network, or data-write behavior with weak constraints.
+- **Schema ambiguity:** vague names, missing parameter descriptions, permissive object schemas, or unclear required fields that make agent calls less predictable.
+- **Prompt injection paths:** tools that retrieve untrusted content and return it directly to an agent context.
+- **Secret exposure:** responses, logs, headers, or environment-backed tools that can leak credentials or internal details.
+- **Schema drift:** changed tool names, parameters, or capabilities that break dependent agents without warning.
+- **Unreliable startup:** packages that work locally but hang, exit early, or fail under CI and production runners.
+- **Capability mismatch:** servers that advertise tools, prompts, or resources but do not return valid MCP responses.
+
+## What Can Go Wrong When Agents Depend On Tools
+
+An MCP server can look harmless during manual evaluation and still fail in production agent infrastructure. The most common failure modes are not exotic. They are basic integration risks amplified by agent autonomy:
+
+- a tool disappears or changes shape after an upgrade
+- a server starts on a laptop but fails in GitHub Actions
+- a broad filesystem or browser automation tool is exposed without a clear trust boundary
+- a tool returns untrusted text that gets treated as instruction-like context
+- a schema is technically valid but too vague for reliable model use
+- a private or credential-backed tool is added without audit visibility
+
+For security and platform teams, the goal is not to block every MCP server. The goal is to make tool invocation observable, testable, auditable, and safe enough for the workflow that depends on it.
+
+## What MCP Observatory Checks Today
+
+MCP Observatory focuses on model context protocol testing that can run locally, in CI, or through its own MCP server mode. It checks:
+
+- tools, prompts, and resources list/respond correctly
+- advertised capabilities match observed behavior
+- safe read-only tools can be invoked
+- schemas have enough structure for agents to call them reliably
+- risky schema patterns are surfaced before production use
+- runs can be compared for regressions and schema drift detection
+- artifacts can be rendered as JSON, Markdown, HTML, JUnit, SARIF, or PR comments
+- health scores and badges can create visible trust signals for MCP maintainers
+
+This is intentionally practical. It is not a formal proof of semantic safety. It is a CI-friendly control that helps teams find obvious compatibility, drift, and security issues before they become agent failures.
+
+## What CI Should Catch Before Deployment
+
+A useful MCP server CI gate should answer a few operational questions:
+
+- Does the server start reliably in a clean environment?
+- Do tools, prompts, and resources respond with valid MCP shapes?
+- Did any tool, parameter, prompt, or resource drift from the previous known-good run?
+- Are there broad filesystem, shell, browser, network, or credential-sensitive tools?
+- Are generated reports readable by maintainers and security reviewers?
+- Can the run produce artifacts for later audit, diffing, or enterprise review?
+
+MCP Observatory is designed to make that a one-command adoption path:
+
+```bash
+npx @kryptosai/mcp-observatory init-ci --all --command "npx -y my-mcp-server"
+```
+
+For a direct check:
+
+```bash
+npx @kryptosai/mcp-observatory test --security npx -y my-mcp-server
+```
+
+## How Security And Platform Teams Can Adopt MCP Checks
+
+For open source maintainers, start with the generated GitHub Action and a public badge. This creates a visible compatibility/security signal without requiring an account.
+
+For private teams, start with static artifacts:
+
+- run MCP checks in CI
+- store JSON and Markdown artifacts
+- compare releases with `diff`
+- use SARIF where security review tools expect it
+- generate a static enterprise report for owner review
+
+For production MCP fleets, the next layer is hosted history, recurring security reports, certification review, support, and fleet visibility across repositories and agent environments.
+
+## Future Direction
+
+The next generation of secure agentic systems will need more than ad hoc tool installs. Useful controls will include:
+
+- policy for which tools agents may call
+- provenance for MCP packages and server configurations
+- schema locks and controlled drift review
+- runtime monitoring for production agent tool use
+- certification signals for high-trust MCP servers
+- fleet inventory across teams, repositories, and hosts
+
+MCP Observatory starts with the smallest durable wedge: make MCP servers testable, visible, and auditable before agents depend on them.

package/docs/mcp-server-safety-index.md

@@ -0,0 +1,85 @@
+# MCP Server Safety Index
+
+The MCP Server Safety Index is a public, reproducible way to show how MCP servers behave under compatibility, schema quality, drift, and security checks.
+
+The goal is constructive proof, not callouts. Each entry shows what should be tested, how to reproduce it, what risk class matters, and what a maintainer can do next.
+
+## Index v0
+
+| # | Server | Category | Reproducible Command | What To Check | Risk Class | Status |
+| ---: | --- | --- | --- | --- | --- | --- |
+| 1 | [`modelcontextprotocol/servers`](https://github.com/modelcontextprotocol/servers) sequential thinking | Reference | `npx -y @modelcontextprotocol/server-sequential-thinking@latest` | Startup, tools/list, schema quality, security-lite | Reference compatibility | PR open: [#4392](https://github.com/modelcontextprotocol/servers/pull/4392) |
+| 2 | [`modelcontextprotocol/servers`](https://github.com/modelcontextprotocol/servers) filesystem | Filesystem | `npx -y @modelcontextprotocol/server-filesystem .` | Startup in harmless temp dir, path tools, schema quality | Filesystem boundary | Researched |
+| 3 | [`upstash/context7`](https://github.com/upstash/context7) | Documentation/search | `npx -y @upstash/context7-mcp@latest` | Startup, retrieval tools, schemas, prompt-injection-sensitive text flow | Untrusted content retrieval | PR open: [#2800](https://github.com/upstash/context7/pull/2800) |
+| 4 | [`executeautomation/mcp-playwright`](https://github.com/executeautomation/mcp-playwright) | Browser automation | `npx -y @executeautomation/playwright-mcp-server@latest` | Browser tools, schema quality, intentional code-eval suppressions | Browser/code execution | PR open: [#225](https://github.com/executeautomation/mcp-playwright/pull/225) |
+| 5 | [`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp) | Browser automation | `npx -y @playwright/mcp@latest` | Browser tools, skip-invoke policy, schema quality, suppressions | Browser/code execution | PR open: [#1657](https://github.com/microsoft/playwright-mcp/pull/1657) |
+| 6 | [`kazuph/mcp-taskmanager`](https://github.com/kazuph/mcp-taskmanager) | Developer tools | `npx -y @kazuph/mcp-taskmanager@latest` | Task tools, schema quality, mutation clarity | Project/task mutation | PR open: [#11](https://github.com/kazuph/mcp-taskmanager/pull/11) |
+| 7 | [`cyanheads/filesystem-mcp-server`](https://github.com/cyanheads/filesystem-mcp-server) | Filesystem | `node dist/index.js` | Capability declarations, resources/list, sandboxed filesystem target | Filesystem boundary | PR open: [#19](https://github.com/cyanheads/filesystem-mcp-server/pull/19) |
+| 8 | [`browserbase/mcp-server-browserbase`](https://github.com/browserbase/mcp-server-browserbase) | Browser automation | `npx -y @browserbasehq/mcp-server-browserbase` | Auth-free startup, browser tools, network/browser boundaries | Hosted browser control | Researched; likely needs API key |
+| 9 | [`redis/mcp-redis`](https://github.com/redis/mcp-redis) | Database | `uvx mcp-redis` | Startup without live database, command surface, destructive operations | Data mutation | Researched; may need service |
+| 10 | [`mongodb-js/mongodb-mcp-server`](https://github.com/mongodb-js/mongodb-mcp-server) | Database | `npx -y mongodb-mcp-server` | Connection handling, read/write tools, auth posture | Data mutation/auth | Researched; likely needs connection string |
+| 11 | [`supabase-community/supabase-mcp`](https://github.com/supabase-community/supabase-mcp) | Database/SaaS | `npx -y supabase-mcp` | Startup, token handling, project mutation tools | Cloud data access | Researched; likely needs token |
+| 12 | [`cloudflare/mcp-server-cloudflare`](https://github.com/cloudflare/mcp-server-cloudflare) | Cloud | `npx -y @cloudflare/mcp-server-cloudflare` | Auth posture, deploy/config tools, schema clarity | Cloud control plane | Researched; likely needs auth |
+| 13 | [`stripe/agent-toolkit`](https://github.com/stripe/agent-toolkit) | Payments | `npx -y @stripe/agent-toolkit` | MCP mode, payment/customer mutation tools, auth posture | Payments/destructive action | Researched; likely needs API key |
+| 14 | [`github/github-mcp-server`](https://github.com/github/github-mcp-server) | Developer tools | `docker run ghcr.io/github/github-mcp-server` | Auth handling, repo mutation tools, schema clarity | Source-code control | Researched; likely needs token |
+| 15 | [`jetbrains/mcpProxy`](https://github.com/JetBrains/mcpProxy) | IDE/developer tools | `npx -y @jetbrains/mcp-proxy` | IDE dependency, startup behavior, tool surface | Local IDE control | Researched; may need IDE process |
+| 16 | [`BrowserMCP/mcp`](https://github.com/BrowserMCP/mcp) | Browser automation | `npx -y @browsermcp/mcp` | Browser tools, schema quality, browser-control boundary | Browser control | PR open: [#189](https://github.com/BrowserMCP/mcp/pull/189) |
+| 17 | [`UI5/mcp-server`](https://github.com/UI5/mcp-server) | Developer tools | `npx -y @ui5/mcp-server` | UI5 tooling commands, schema quality, drift risk | App development tooling | PR open: [#348](https://github.com/UI5/mcp-server/pull/348) |
+| 18 | [`antvis/mcp-server-chart`](https://github.com/antvis/mcp-server-chart) | Visualization/data | `npx -y @antv/mcp-server-chart` | Chart generation tools, schema quality, artifact-producing tools | Generated artifacts | PR open: [#312](https://github.com/antvis/mcp-server-chart/pull/312) |
+| 19 | [`makenotion/notion-mcp-server`](https://github.com/makenotion/notion-mcp-server) | SaaS/API | `npx -y @notionhq/notion-mcp-server` | Auth handling, read/write tool separation, schema quality | Workspace data access | PR open: [#324](https://github.com/makenotion/notion-mcp-server/pull/324) |
+| 20 | [`sentry/sentry-mcp`](https://github.com/getsentry/sentry-mcp) | Developer SaaS | `npx -y @sentry/mcp-server` | Auth handling, issue/project tools, schema quality | Production incident data | Researched; likely needs token |
+
+## Evaluation Command
+
+For simple npm-backed servers:
+
+```bash
+npx @kryptosai/mcp-observatory test --security npx -y <server-package>
+```
+
+For safer campaign PRs:
+
+```bash
+npx @kryptosai/mcp-observatory init-ci --all --command "npx -y <server-package>"
+```
+
+For production-style review:
+
+```bash
+npx @kryptosai/mcp-observatory lock
+npx @kryptosai/mcp-observatory lock verify
+```
+
+## What Each Column Means
+
+- What To Check: the minimum compatibility/security surface a maintainer or platform team should inspect.
+- Risk Class: the operational reason the server matters before agents depend on it.
+- Status: public proof such as PR open, PR accepted, badge added, researched, or needs maintainer review.
+
+## Publication Rules
+
+- Use only public repositories, public package commands, public PRs, or sample artifacts.
+- Include a reproduction command for every row.
+- Link to the maintainer PR or public artifact when available.
+- Phrase findings constructively: “needs review” rather than “unsafe” unless there is clear public proof.
+- Keep customer/domain telemetry internal unless the customer gives permission or there is independent public evidence.
+
+## Five Patterns To Publish From v0
+
+1. Browser automation MCP servers need explicit policy around code execution, screenshots, navigation, and mutation.
+2. Filesystem MCP servers need harmless CI sandboxes and clear read/write boundaries.
+3. SaaS and cloud MCP servers often cannot be meaningfully checked without token-safe target configs.
+4. Database MCP servers need read/write classification and connection-string hygiene before CI rollout.
+5. Lock files turn MCP surface drift into a reviewable PR event instead of an invisible agent dependency change.
+
+## Next Wave Criteria
+
+Prioritize 20-50 servers that have:
+
+- active maintenance in the last 90 days
+- visible stars, downloads, or directory listings
+- simple `npx`, `uvx`, or Docker startup commands
+- enterprise-relevant categories such as browser automation, filesystem, documentation/search, databases, cloud, productivity, and developer tools
+- no existing MCP compatibility/security CI
+
+One accepted PR in a respected repo is worth more than a large list of shallow checks.

package/docs/paid-pilot-offer.md

@@ -0,0 +1,58 @@
+# 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
+
+- review of the customer’s MCP config, repo, or startup commands
+- MCP Observatory CI rollout for selected servers
+- private readiness report covering startup, capabilities, schema quality, security findings, and drift risk
+- MCP lock-file setup for contract drift review
+- prioritized remediation notes
+- 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. Do not build a dashboard until paid pilot feedback proves exactly what buyers need.

package/docs/project-case-study.md

@@ -4,9 +4,17 @@
 
 MCP Observatory is CI/security infrastructure for production MCP servers.
 
-## Problem
+## Project Narrative
 
-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.
+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
 
@@ -23,46 +31,57 @@ MCP Observatory provides:
 - static enterprise reports
 - telemetry intelligence for product and account-level learning
 
-## Architecture
+## 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. A Cloudflare Worker handles hosted artifact upload pilots, and a separate telemetry Worker stores private aggregate usage events in D1.
+The project is a TypeScript/Node CLI with modular command handlers, MCP adapters, check runners, reporters, artifact schemas, and a GitHub Action wrapper.
 
-## Technical Proof
+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.
 
-As of June 19, 2026:
+## Security Model
 
-- 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
+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.
 
-## Traction Snapshot
+Current controls include:
 
-Safe public and aggregate signals:
+- 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
 
-- 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
+For deeper context, see the [MCP Server Security Field Guide](./mcp-security-field-guide.md).
 
-These are early signals. Public social proof is still limited and should be improved through the certification campaign.
+## Telemetry Intelligence
 
-## Security And Privacy Posture
+Telemetry is used privately to understand product usage and identify account-level signals without publishing raw personal data.
 
-The project includes:
+As of the latest local export on June 20, 2026:
 
-- telemetry opt-out controls
-- privacy disclosure
-- security policy
-- token-based hosted artifact upload
-- private-network rejection for hosted scans
-- sanitized public reporting policy
+- 10,918 telemetry events
+- 7,380 total sessions
+- 5,379 external sessions after separating internal activity
+- 2,446 external CI sessions
+- 138 attributed company/org sessions
+- 11 attributed company/org candidates
 
-Public claims should use aggregate metrics and accepted public integrations, not raw telemetry.
+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.23.0`
+- npm package: `@kryptosai/mcp-observatory`
+- GitHub Action: `KryptosAI/mcp-observatory/action@main`
+- visible GitHub traffic window: 721 clones and 221 unique cloners
+- 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, and other MCP projects
+
+See [reference evaluations](./reference-evaluations.md) and [public proof](./proof.md).
 
 ## Commercial Path
 
@@ -83,24 +102,35 @@ Current pilot anchors:
 - Enterprise: starts at `$3k/month`
 - Strategic: `$250k+/year`
 
-## Job-Opportunity Value
+## Professional Signal
 
-This project demonstrates ability across:
+MCP Observatory demonstrates applied work across:
 
-- AI infrastructure
+- AI agent infrastructure
 - developer tooling
-- security tooling
-- MCP ecosystem work
+- secure tool invocation
+- software supply chain thinking
 - CI/CD integrations
 - telemetry and product analytics
-- commercialization and enterprise packaging
+- 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:
 
-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.
+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.
 
-## Next Milestones
+Longer-term opportunities:
 
-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.
+- 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