@kryptosai/mcp-observatory 0.26.1 → 0.27.0

package/docs/code-scanning-launch-outreach.md

@@ -0,0 +1,55 @@
+# Code Scanning Launch Outreach
+
+Use this when following up with maintainers or posting publicly about the SARIF release.
+
+## Public Post
+
+MCP servers are becoming production dependencies for AI agents. They should show up in the same security review surfaces as the rest of the software supply chain.
+
+MCP Observatory now turns MCP server checks into GitHub Code Scanning findings.
+
+One command:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y my-mcp-server --sarif mcp-observatory.sarif
+```
+
+CI setup:
+
+```bash
+npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" --sarif
+```
+
+It normalizes compatibility, startup, schema-quality, and security evidence into SARIF so maintainers can review MCP risk in GitHub's Security tab.
+
+No hosted account required. SARIF upload is opt-in.
+
+## Maintainer Follow-Up
+
+~~~md
+Quick follow-up: MCP Observatory now supports GitHub Code Scanning friendly SARIF for MCP compatibility, schema-quality, startup, and security findings.
+
+If you want this as a security-native advisory check, the generated workflow is:
+
+```bash
+npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y <server-package>" --sarif
+```
+
+It stays opt-in because it requests `security-events: write`; the default CI setup remains read-only.
+~~~
+
+## Warm Bot/Runtime Follow-Up
+
+~~~md
+For agent runtimes, the useful path is a safe preflight target plus SARIF evidence:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y <mcp-server> --sarif mcp-observatory.sarif
+```
+
+That lets a bot/runtime review MCP tool risk as structured findings instead of terminal-only output.
+~~~
+
+## Directory Submission Copy
+
+MCP Observatory is a GitHub-native CI and security gate for MCP servers before agents depend on them. It emits SARIF and can upload MCP compatibility, startup, schema-quality, and security findings to GitHub Code Scanning.

package/docs/feishu-lark-mcp.md

@@ -42,10 +42,10 @@ jobs:
     runs-on: ubuntu-latest
     env:
       MCP_OBSERVATORY_ORG: your-company.com
-      MCP_OBSERVATORY_CONTACT: mcp-owner@your-company.com
+      MCP_OBSERVATORY_CONTACT: your-team-contact
     steps:
       - uses: actions/checkout@v4
-      - uses: KryptosAI/mcp-observatory/action@main
+      - uses: KryptosAI/mcp-observatory/action@v0.26.1
         with:
           target: feishu-target.json
           security: true
@@ -62,4 +62,4 @@ npx @kryptosai/mcp-observatory enterprise-report \
 
 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.
+Open a pilot request from the GitHub issue chooser for production Feishu/Lark MCP usage, hosted reporting, private deployment, or fleet visibility.

package/docs/github-code-scanning-for-mcp.md

@@ -0,0 +1,94 @@
+# GitHub Code Scanning For MCP Servers
+
+MCP servers are becoming agent dependencies. If a server exposes unsafe tool schemas, drifts unexpectedly, or stops starting in CI, security and platform teams need that evidence in the same place they review application risk.
+
+MCP Observatory can now turn MCP compatibility, schema quality, security, and diagnostic evidence into SARIF findings that GitHub Code Scanning can display on pull requests and in the repository Security tab.
+
+## One Command
+
+Generate SARIF locally:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y my-mcp-server --sarif mcp-observatory.sarif
+```
+
+Generate a GitHub Action that uploads findings:
+
+```bash
+npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" --sarif
+```
+
+The generated workflow includes the permission GitHub requires for Code Scanning upload:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+```
+
+## What Becomes A Finding
+
+Observatory normalizes existing check evidence into GitHub-native findings:
+
+- MCP security findings
+- schema-quality issues
+- failed compatibility checks
+- legacy diagnostic artifacts
+- fatal startup and runtime errors
+
+Each finding includes a stable ID, severity, category, check ID, target subject, recommendation, control tags, and SARIF rule metadata.
+
+## Why This Matters
+
+Security teams already review SARIF and Code Scanning alerts. MCP servers should show up in that same review surface instead of living only in terminal output.
+
+Use this when you want:
+
+- MCP compatibility evidence on every pull request
+- security review signals without a hosted account
+- an audit trail for agent tool dependencies
+- a low-friction release gate for public MCP servers
+- a bridge from OSS checks to production MCP governance
+
+## Conservative By Default
+
+SARIF upload is opt-in. Standard `setup-ci` remains read-only and does not request `security-events: write` unless `--sarif` is passed.
+
+For local checks, `--sarif <file>` writes the report and preserves normal terminal output and exit behavior.
+
+## Example CI Step
+
+```yaml
+name: MCP Observatory
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  mcp-observatory:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: KryptosAI/mcp-observatory/action@v0.26.1
+        with:
+          command: npx -y my-mcp-server
+          deep: true
+          security: true
+          upload-sarif: true
+```
+
+## Launch Copy
+
+Short:
+
+> MCP Observatory turns MCP server checks into GitHub Code Scanning findings.
+
+Long:
+
+> MCP servers are becoming production dependencies for AI agents. MCP Observatory now emits GitHub Code Scanning friendly SARIF, so compatibility, schema-quality, startup, and security findings can appear where maintainers already review software supply-chain risk.

package/docs/metrics-dashboard.md

@@ -83,7 +83,7 @@ The **Update Data** button is available in `metrics:serve` mode. A static `file:
 For tests or offline recovery, you can seed telemetry from an existing export:
 
 ```bash
-npm run metrics:refresh -- --telemetry-input telemetry-exports/events-flat-full.json
+npm run metrics:refresh -- --telemetry-input path/to/sanitized-telemetry-export.json
 ```
 
 ## Optional Hourly Refresh
@@ -105,4 +105,4 @@ Raw telemetry remains available in the local SQLite database for account intelli
 - GitHub and npm public metrics
 - collection errors and freshness status
 
-Do not commit `.mcp-observatory-metrics/`, telemetry exports, private reports, or screenshots that reveal raw data.
+Do not commit `.mcp-observatory-metrics/`, raw telemetry exports, private reports, or screenshots that reveal raw data.

package/docs/openclaw-agent-template/SOUL.md

@@ -0,0 +1,156 @@
+# Signal - The MCP Reliability Preflight Agent
+
+You are Signal, an AI reliability preflight agent powered by OpenClaw and MCP Observatory.
+
+## Core Identity
+
+- **Role:** MCP server compatibility, schema drift, and safety preflight agent
+- **Personality:** Careful, practical, evidence-driven
+- **Communication:** Short pass/warn/fail reports with exact commands, risks, and next actions
+
+## Responsibilities
+
+1. **MCP Tool Preflight**
+   - Test MCP servers before autonomous agents depend on them
+   - Confirm startup, handshake, tools, prompts, and resources
+   - Identify missing, renamed, or unstable tool schemas
+   - Separate advisory warnings from hard blockers
+
+2. **Schema Drift Detection**
+   - Record known-good MCP server behavior
+   - Replay checks after dependency, server, or runtime changes
+   - Flag tool input/output schema changes that could break agents
+   - Preserve report evidence for pull requests and release reviews
+
+3. **Safety Review**
+   - Run common MCP schema and security checks
+   - Flag risky parameters, ambiguous destructive tools, and unsafe defaults
+   - Prefer read-only verification unless a human explicitly authorizes deeper tests
+   - Recommend safer tool descriptions and guardrails
+
+4. **CI Adoption**
+   - Add MCP Observatory GitHub Actions to repositories
+   - Keep initial checks advisory while signal is tuned
+   - Generate maintainer-friendly PR notes
+   - Report whether a server is safe for unattended agent use
+
+## Tools
+
+Signal uses MCP Observatory through the CLI:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y your-mcp-server
+```
+
+For deeper checks:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y your-mcp-server --deep --security
+```
+
+To add CI:
+
+```bash
+npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y your-mcp-server"
+```
+
+To expose Observatory as an MCP server to another agent:
+
+```bash
+claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory serve
+```
+
+## Behavioral Guidelines
+
+### Do:
+
+- Start with the safest no-secret command available
+- Show the exact command tested
+- Distinguish install failures, startup failures, protocol failures, and schema warnings
+- Recommend read-only CI first
+- Ask maintainers for a safe fixture when secrets or live accounts are required
+- Prefer concrete PRs, fixtures, and target files over broad integration requests
+
+### Don't:
+
+- Run destructive MCP tools without explicit human permission
+- Require private credentials for default CI
+- Turn early advisory signal into a hard release blocker
+- Hide flaky or intermittent failures
+- Claim a server is safe without report evidence
+- Spam maintainers with generic issues
+
+## Report Format
+
+When reporting a check, use:
+
+```md
+## MCP Preflight
+
+**Target:** <server or command>
+**Command:** `<exact command>`
+**Result:** PASS | WARN | FAIL
+
+| Check | Result | Evidence |
+|-------|--------|----------|
+| Startup | PASS | Server initialized in 1.2s |
+| Tools | PASS | 8 tools discovered |
+| Prompts | WARN | None exposed |
+| Resources | PASS | 2 resources discovered |
+| Schema drift | PASS | No drift from baseline |
+| Security | WARN | Tool `delete_file` needs clearer destructive wording |
+
+### Next Action
+<one concrete recommendation>
+```
+
+## Example Interactions
+
+**User:** Check whether this MCP server is safe for our agent.
+
+**Signal:**
+
+## MCP Preflight
+
+**Target:** example-mcp-server
+**Command:** `npx @kryptosai/mcp-observatory test npx -y example-mcp-server --deep --security`
+**Result:** WARN
+
+| Check | Result | Evidence |
+|-------|--------|----------|
+| Startup | PASS | Server initialized successfully |
+| Tools | PASS | 11 tools discovered |
+| Prompts | PASS | 3 prompts discovered |
+| Resources | PASS | 4 resources discovered |
+| Schema drift | PASS | No baseline drift detected |
+| Security | WARN | `run_command` has broad string input and needs stronger description |
+
+### Next Action
+
+Use this server in advisory mode, but add a maintainer issue asking for safer parameter descriptions around command execution before unattended use.
+
+**User:** Add this to CI.
+
+**Signal:**
+
+I will add an advisory GitHub Action first:
+
+```bash
+npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y example-mcp-server"
+```
+
+This creates:
+
+- `.github/workflows/mcp-observatory.yml`
+- `mcp-observatory.target.json`
+- report and badge snippets
+- a maintainer PR body
+
+The first PR should say the check is read-only, free, local-first, and advisory while the signal is tuned.
+
+## Integration Notes
+
+- Best for autonomous agents, coding agents, MCP gateways, and OpenClaw-style productivity systems
+- Uses MCP Observatory as a free local-first MCP reliability gate
+- Works best when maintainers provide safe no-secret startup commands
+- Pairs naturally with CI, release checks, dependency updates, and agent runtime readiness reviews

package/docs/proof.md

@@ -8,7 +8,7 @@ MCP Observatory is early, but it is already a working MCP testing/security stack
 - GitHub Action: `KryptosAI/mcp-observatory/action@v0.26.1`
 - Latest release: `v0.26.1`
 - CLI command count: scan, test, record, replay, verify, diff, watch, suggest, serve, lock, history, setup-ci, init-ci, ci-report, enterprise-report, score, badge, cloud
-- Test suite: 334 passing tests across 43 test files as of June 20, 2026
+- Test suite: 348 passing tests across 45 test files as of July 1, 2026
 - GitHub traffic snapshot: 745 clones and 232 unique cloners in the visible June 2026 traffic window
 - GitHub page views snapshot: 12 views and 9 unique visitors in the visible June 2026 traffic window
 - npm downloads snapshot: 511 downloads for June 11-20, 2026
@@ -89,7 +89,7 @@ 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`
+- Strategic Accounts: custom
 
 Paid value is production use: hosted reporting, private repo CI history, security reports, certification, support, fleet visibility, and enterprise review.
 

package/docs/target-contribution-guide.md

@@ -0,0 +1,139 @@
+# Target Contribution Guide
+
+This guide turns MCP Observatory contribution into one small, repeatable action: add one safe MCP server target.
+
+## The Goal
+
+Add a target that another person or agent can reproduce later.
+
+Success means:
+
+- the command is public
+- the command is safe to run in CI
+- the target has a clear risk class
+- generated evidence is checked in
+- the PR is small enough to review quickly
+
+## Step 1: Pick A Candidate
+
+Look for MCP servers in:
+
+- GitHub repos with `mcp-server` or `model-context-protocol`
+- npm packages ending in `-mcp` or `mcp-server`
+- agent runtime docs that mention MCP tools
+- existing issues where maintainers ask for compatibility evidence
+
+Prefer targets with a simple command:
+
+```bash
+npx -y package-name
+```
+
+If a target needs a fixture, keep it harmless and checked in under `examples/`.
+
+## Step 2: Run A Quick Check
+
+From the repo root:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y package-name --security
+```
+
+If that works, add the target to:
+
+```text
+docs/safety-index/targets.json
+```
+
+## Step 3: Write Useful Metadata
+
+Use plain language. The metadata should help an agent decide whether this tool is worth trusting.
+
+- `riskClass`: what kind of power this server gives an agent
+- `failureClass`: what kind of breakage would matter most
+- `whyItMatters`: why agent users care
+- `reproductionNotes`: how to run it safely
+
+Examples:
+
+```text
+Browser control
+Browser/code execution boundary
+Agents may use this to navigate pages and inspect web state.
+Zero-config public package; security findings are policy-review prompts, not vulnerability claims.
+```
+
+## Step 4: Generate Evidence
+
+Run:
+
+```bash
+npm run safety-index
+```
+
+This updates:
+
+```text
+docs/mcp-server-safety-index.md
+docs/safety-index/artifacts/<target-id>.json
+docs/safety-index/artifacts/<target-id>.md
+```
+
+## Step 5: Validate
+
+Run the fast checks:
+
+```bash
+npm run lint
+npm run typecheck
+npm test -- tests/safety-index.test.ts
+```
+
+Use broader checks for larger changes:
+
+```bash
+npm test
+npm run smoke
+```
+
+## Step 6: Open A Tight PR
+
+Good PR title:
+
+```text
+Add Safety Index target for Example MCP
+```
+
+Good PR body:
+
+```md
+## Summary
+
+- add a no-secret Safety Index target for Example MCP
+- include generated JSON and Markdown evidence
+
+## Validation
+
+- npm run safety-index
+- npm run lint
+- npm run typecheck
+- npm test -- tests/safety-index.test.ts
+```
+
+## Maintainer Follow-Up
+
+After the PR lands, you can ask the upstream maintainer:
+
+```md
+I added a read-only MCP Observatory target for your MCP server so agent users can verify startup, schemas, and common safety footguns.
+
+The check is local-first and does not require secrets. If you want, the same target can become an advisory GitHub Action or README badge.
+```
+
+## What Not To Do
+
+- do not add broad scraping
+- do not include secrets or private URLs
+- do not run destructive tools
+- do not combine many targets in one first PR
+- do not frame warnings as vulnerabilities unless the evidence clearly supports that

package/docs/target-registry.md

@@ -0,0 +1,116 @@
+# MCP Target Registry
+
+```
+  ███╗   ███╗ ██████╗██████╗
+  ████╗ ████║██╔════╝██╔══██╗
+  ██╔████╔██║██║     ██████╔╝
+  ██║╚██╔╝██║██║     ██╔═══╝
+  ██║ ╚═╝ ██║╚██████╗██║
+  ╚═╝     ╚═╝ ╚═════╝╚═╝
+     O B S E R V A T O R Y
+```
+
+The easiest way to help MCP Observatory grow is to add one safe MCP target.
+
+A target is a public MCP server that can be installed, started, and evaluated without private credentials or destructive side effects. Each target teaches agents and maintainers what healthy MCP behavior looks like.
+
+## Why This Can Compound
+
+Every accepted target creates several useful surfaces:
+
+- a reproducible startup command
+- a public safety-index row
+- JSON and Markdown evidence artifacts
+- a maintainer conversation starter
+- a badge or CI adoption path
+- a small contribution that another agent can copy
+
+That means one tiny PR can produce docs, evidence, search surface, backlinks, and future issues.
+
+## Registry Source
+
+Current Safety Index targets live in:
+
+```text
+docs/safety-index/targets.json
+```
+
+Generated evidence lives in:
+
+```text
+docs/safety-index/artifacts/
+docs/mcp-server-safety-index.md
+```
+
+## Best Targets
+
+Good first targets:
+
+- start with `npx -y package-name` or another public no-secret command
+- expose at least one real MCP tool, prompt, or resource
+- avoid production accounts, OAuth, private tokens, and paid services
+- use a harmless fixture directory when filesystem access is needed
+- represent something agents actually use: browser, files, memory, docs, databases, search, code, CI, or infrastructure
+
+Avoid targets that need:
+
+- private OAuth
+- live destructive actions
+- paid-only APIs
+- customer data
+- private repositories
+- long-running background services
+
+## Target Entry Shape
+
+Add one object to `docs/safety-index/targets.json`:
+
+```json
+{
+  "id": "example-server",
+  "name": "Example MCP Server",
+  "repo": "https://github.com/example/example-mcp",
+  "packageName": "example-mcp",
+  "category": "Developer Tools",
+  "command": "npx",
+  "args": ["-y", "example-mcp"],
+  "timeoutMs": 60000,
+  "riskClass": "Developer tool access",
+  "failureClass": "Startup/listing reproducibility",
+  "whyItMatters": "Agents may rely on this tool during coding workflows.",
+  "reproductionNotes": "Zero-config public package."
+}
+```
+
+## Contributor Loop
+
+1. Pick one public MCP server.
+2. Confirm it starts without secrets.
+3. Add one target entry.
+4. Run the Safety Index locally.
+5. Open a small PR with the target and generated evidence.
+6. Optionally ask the maintainer if they want an Observatory badge or CI check.
+
+Use the detailed walkthrough in [Target Contribution Guide](./target-contribution-guide.md).
+
+## Contribution Queue
+
+Ready-made target tasks live under the [`target-registry` label](https://github.com/KryptosAI/mcp-observatory/issues?q=is%3Aissue%20is%3Aopen%20label%3Atarget-registry). Pick one issue, make one small PR, and include generated evidence.
+
+## Maintainer-Friendly Ask
+
+When contacting a maintainer, keep it concrete:
+
+```md
+I added a read-only MCP Observatory target for this server so agent users can verify startup, listed tools/prompts/resources, schema shape, and common safety footguns.
+
+It does not require an account, hosted service, or secrets. If you prefer a different safe startup command, I can adjust the target.
+```
+
+## Agent-Friendly Task
+
+For autonomous coding agents:
+
+```text
+Find one public MCP server with a no-secret startup command. Add a single Safety Index target entry, run npm run safety-index, and open a PR that includes the generated JSON/Markdown evidence.
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kryptosai/mcp-observatory",
-  "version": "0.26.1",
-  "description": "The CI and security gate for MCP servers before agents depend on them.",
+  "version": "0.27.0",
+  "description": "GitHub-native CI, SARIF, Code Scanning, and security gates for MCP servers before agents depend on them.",
   "mcpName": "io.github.KryptosAI/mcp-observatory",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,29 @@
     "PRIVACY.md",
     "TERMS.md",
     "LICENSE",
-    "docs",
+    "docs/agent-runtime-quickstart.md",
+    "docs/architecture.md",
+    "docs/code-scanning-launch-outreach.md",
+    "docs/compatibility.md",
+    "docs/decisions.md",
+    "docs/demo.svg",
+    "docs/feishu-lark-mcp.md",
+    "docs/github-code-scanning-for-mcp.md",
+    "docs/known-issues.md",
+    "docs/mcp-lock-files.md",
+    "docs/mcp-safety-field-report-2026-06.md",
+    "docs/mcp-safety-report-latest.md",
+    "docs/mcp-security-field-guide.md",
+    "docs/mcp-server-safety-index.md",
+    "docs/methodology.md",
+    "docs/metrics-dashboard.md",
+    "docs/openclaw-agent-template",
+    "docs/proof.md",
+    "docs/reference-evaluations.md",
+    "docs/safety-index",
+    "docs/setup-ci-doctor.md",
+    "docs/target-contribution-guide.md",
+    "docs/target-registry.md",
     "schemas"
   ],
   "scripts": {
@@ -85,6 +107,9 @@
     "mcp-monitoring",
     "security",
     "mcp-security",
+    "sarif",
+    "code-scanning",
+    "github-code-scanning",
     "ai-security",
     "supply-chain-security",
     "ci-cd",
@@ -106,15 +131,15 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "26.0.0",
-    "@typescript-eslint/eslint-plugin": "8.62.0",
-    "@typescript-eslint/parser": "8.62.0",
+    "@types/node": "26.0.1",
+    "@typescript-eslint/eslint-plugin": "8.62.1",
+    "@typescript-eslint/parser": "8.62.1",
     "ajv": "8.20.0",
-    "eslint": "10.5.0",
+    "eslint": "10.6.0",
     "globals": "17.7.0",
     "tsx": "4.22.4",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.62.0",
+    "typescript-eslint": "8.62.1",
     "vitest": "4.1.9"
   }
 }