@kryptosai/mcp-observatory 0.27.0 → 0.28.0

package/docs/target-gallery.md

@@ -0,0 +1,49 @@
+# Target Gallery
+
+The Target Gallery turns the Safety Index into a maintainer-friendly map of the MCP ecosystem. It is not a leaderboard. It groups examples by the kind of agent dependency risk they represent.
+
+For reproducible evidence, see the [MCP Server Safety Index](./mcp-server-safety-index.md). For contributor credit attached to accepted targets, see [MCP Observatory Contributors](./contributor-recognition.md) and [Contributor Proof Cards](./contributor-proof-cards/).
+
+## Reference And Baseline Servers
+
+| Target | Why Agents Care | Next Step |
+| --- | --- | --- |
+| Official everything server | Broad MCP protocol surface across tools, prompts, and resources | Keep as a baseline compatibility target |
+| Official sequential thinking server | Small tool surface with readable schemas | Use as a simple CI starter target |
+| Official memory server | Agent-facing persistent state | Watch schema and write boundaries |
+
+## Filesystem, Browser, And Execution Boundaries
+
+| Target | Why Agents Care | Next Step |
+| --- | --- | --- |
+| Official filesystem server | File access boundaries need harmless test roots | Review path scope before production |
+| BrowserMCP | Browser-control tools can affect live sessions | Add read-only CI before agent rollout |
+| Microsoft Playwright MCP | Browser automation can cross into code execution policy | Treat findings as policy review prompts |
+| Puppeteer MCP server | Browser automation needs clear execution boundaries | Keep intentional browser checks explicit |
+| ExecuteAutomation Playwright MCP | Startup/listing reproducibility affects agent trust | Start with maintainer conversation |
+
+## Retrieval, Documentation, And Prompt Surfaces
+
+| Target | Why Agents Care | Next Step |
+| --- | --- | --- |
+| Context7 | Retrieval tools can move untrusted text into agent context | Add drift and schema checks |
+| Promptopia | Prompt/resource contracts shape agent behavior | Keep generated evidence current |
+| Ref tools | Developer-tool inventory should stay stable | Add CI and badge proof |
+
+## Infrastructure And Artifact-Producing Tools
+
+| Target | Why Agents Care | Next Step |
+| --- | --- | --- |
+| OpenTofu MCP server | Infrastructure tools can influence production changes | Run checks before unattended agents use it |
+| AntV chart MCP server | Artifact-producing tools need clear schemas and outputs | Keep CI evidence public |
+
+## Add A Target
+
+Use the [target contribution guide](./target-contribution-guide.md). The best target has a public package, no secrets, no paid dependency, and a harmless startup command.
+
+```bash
+npm run safety-index
+npm test -- tests/safety-index.test.ts
+```
+
+Accepted target PRs can receive a Target Scout or Target Verifier role, an All Contributors entry, and a proof card under `docs/contributor-proof-cards/` that links to the merged PR and generated public evidence.

package/docs/target-registry.md

@@ -23,6 +23,7 @@ Every accepted target creates several useful surfaces:
 - JSON and Markdown evidence artifacts
 - a maintainer conversation starter
 - a badge or CI adoption path
+- contributor recognition and a proof-card link
 - a small contribution that another agent can copy
 
 That means one tiny PR can produce docs, evidence, search surface, backlinks, and future issues.
@@ -89,10 +90,13 @@ Add one object to `docs/safety-index/targets.json`:
 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.
+6. Add or request a contributor proof card.
+7. 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).
 
+Accepted target contributions can receive a role on [MCP Observatory Contributors](./contributor-recognition.md), an All Contributors entry, and a Markdown proof card under [`docs/contributor-proof-cards/`](./contributor-proof-cards/).
+
 ## 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.

package/docs/tool-call-receipts.md

@@ -0,0 +1,116 @@
+# Tool-Call Receipts
+
+MCP servers need receipts, not badges.
+
+A badge says a project wants trust. A receipt shows what was checked, what could have happened, what could not have happened, and which artifact a maintainer or security team can rerun.
+
+Use this page when turning MCP Observatory results into Safety Index entries, maintainer PRs, SARIF uploads, proof cards, or private dependency reviews.
+
+## Receipt Fields
+
+A useful receipt should identify:
+
+| Field | Purpose |
+| --- | --- |
+| `maintainer` | Public project, package, or account responsible for the server. |
+| `source` | Public repo, package, version, and safe startup command. |
+| `observatory` | MCP Observatory version, command, mode, and report timestamp. |
+| `capabilityEnvelope` | What the simulation could and could not access. |
+| `call` | Tool-listing, schema, prompt, resource, or safe invocation surface inspected. |
+| `reason` | Why the check matters for agents depending on the server. |
+| `result` | Verdict, severity, normalized findings, and maintainer-facing recommendation. |
+| `changedArtifact` | JSON, Markdown, SARIF, hash, or PR evidence generated from the run. |
+| `baseline` | Previous run, lock file, or Safety Index entry used for drift comparison. |
+| `safeModeConstraints` | Explicit limits proving the receipt did not run destructive probes. |
+
+Example shape:
+
+```json
+{
+  "maintainer": "Example MCP Server",
+  "source": {
+    "repo": "https://github.com/example/mcp-server",
+    "command": "npx -y example-mcp-server"
+  },
+  "observatory": {
+    "version": "0.28.0",
+    "mode": "safe",
+    "command": "mcp-observatory attack-sim npx -y example-mcp-server"
+  },
+  "capabilityEnvelope": {
+    "filesystem": "fixture-only",
+    "network": "not invoked",
+    "shell": "not available to probes",
+    "credentials": "none"
+  },
+  "call": {
+    "type": "tools/list"
+  },
+  "reason": "permission-boundary risk",
+  "result": {
+    "severity": "medium",
+    "evidence": "Tool schema accepts broad path input and advertises write behavior."
+  },
+  "changedArtifact": {
+    "json": "docs/safety-index/artifacts/example.attack.json",
+    "sarif": "docs/safety-index/artifacts/example.attack.sarif"
+  },
+  "baseline": {
+    "id": "previous-safety-index-run"
+  },
+  "safeModeConstraints": [
+    "No destructive tool calls",
+    "No external exfiltration",
+    "No credential probing",
+    "No writes outside checked-in fixtures"
+  ]
+}
+```
+
+## Capability Envelope
+
+Every public receipt should explain the boundary of the run. For agent safety, the absence of a dangerous capability is as important as the finding itself.
+
+At minimum, state whether the run had access to:
+
+- Filesystem writes or deletes
+- Network calls
+- Shell or process execution
+- Credentials, tokens, cookies, or production services
+- Real user data
+- Fixture data only
+
+For public Safety Index evidence, prefer `attack-sim --mode safe`, public packages, checked-in fixtures, and no-secret startup commands. If a server requires private credentials, keep that evidence out of the public index and treat it as a private readiness review.
+
+## How Observatory Produces Receipts
+
+Use these commands as the receipt ladder:
+
+```bash
+npx @kryptosai/mcp-observatory test npx -y my-mcp-server --json run-artifact.json --markdown run-report.md
+npx @kryptosai/mcp-observatory attack-sim npx -y my-mcp-server --json attack-artifact.json --output attack-report.md --sarif attack-results.sarif
+npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" --sarif
+```
+
+The normal run artifact shows protocol readiness. The attack-sim artifact shows safe attack-readiness evidence for tool poisoning, exfiltration canaries, permission-boundary risk, and drift readiness. The CI setup turns the receipt into something a maintainer can keep rerunning.
+
+## Safety Index Rules
+
+Public Safety Index entries must use:
+
+- Public repos, public packages, or public startup commands
+- Sanitized JSON, Markdown, and SARIF artifacts
+- Safe-mode attack simulation only
+- Maintainer-friendly recommendations
+- No private telemetry, secrets, hostnames, customer data, emails, or unpublished claims
+
+Rough PRs are welcome at intake. Published entries should be normalized into receipts a maintainer can reproduce.
+
+## Contributor Prompt
+
+Use this when inviting agents, bot authors, and MCP maintainers to contribute:
+
+```text
+Name one MCP server your agent depends on. I will help turn it into a reproducible tool-call receipt: safe startup command, run artifact, attack-sim evidence, SARIF, and a CI gate maintainers can review.
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kryptosai/mcp-observatory",
-  "version": "0.27.0",
+  "version": "0.28.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",
@@ -33,18 +33,28 @@
     "README.md",
     "CLONED_THIS.md",
     "COMMERCIAL.md",
+    "CONTRIBUTORS.md",
     "PRIVACY.md",
     "TERMS.md",
     "LICENSE",
     "docs/agent-runtime-quickstart.md",
+    "docs/agent-ecosystem-promotion-plan.md",
+    "docs/agent-tasks.md",
+    "docs/automatic-ci-integration.md",
     "docs/architecture.md",
+    "docs/campaign-attribution.md",
+    "docs/code-scanning-demo.md",
     "docs/code-scanning-launch-outreach.md",
     "docs/compatibility.md",
+    "docs/contributor-proof-cards",
+    "docs/contributor-recognition.md",
     "docs/decisions.md",
     "docs/demo.svg",
     "docs/feishu-lark-mcp.md",
     "docs/github-code-scanning-for-mcp.md",
     "docs/known-issues.md",
+    "docs/launch.md",
+    "docs/mcp-attack-simulator.md",
     "docs/mcp-lock-files.md",
     "docs/mcp-safety-field-report-2026-06.md",
     "docs/mcp-safety-report-latest.md",
@@ -54,11 +64,15 @@
     "docs/metrics-dashboard.md",
     "docs/openclaw-agent-template",
     "docs/proof.md",
+    "docs/receipt-graph.md",
     "docs/reference-evaluations.md",
     "docs/safety-index",
     "docs/setup-ci-doctor.md",
     "docs/target-contribution-guide.md",
+    "docs/target-gallery.md",
     "docs/target-registry.md",
+    "docs/tool-call-receipts.md",
+    "scripts/postinstall.mjs",
     "schemas"
   ],
   "scripts": {
@@ -74,11 +88,13 @@
     "safety-index": "tsx scripts/run-safety-index.ts",
     "lint": "eslint .",
     "prepack": "npm run build",
+    "postinstall": "node scripts/postinstall.mjs",
     "proof:refresh": "tsx scripts/refresh-proof-artifacts.ts",
     "release:prep": "node scripts/release.mjs",
     "certification:pr-body": "tsx scripts/print-certification-pr-body.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json && npm --prefix api install && npm --prefix api run typecheck",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "validate:artifacts": "tsx scripts/validate-artifacts.ts",
     "verify:packed-install": "node scripts/verify-packed-install.mjs",
     "smoke": "npm run cli -- run --target tests/fixtures/sample-target-config.json && npm run cli -- diff tests/fixtures/sample-run-a.json tests/fixtures/sample-run-b.json",
@@ -120,7 +136,8 @@
     "enterprise-report",
     "feishu",
     "lark",
-    "schema-drift"
+    "schema-drift",
+    "attack-simulation"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -138,6 +155,7 @@
     "eslint": "10.6.0",
     "globals": "17.7.0",
     "tsx": "4.22.4",
+    "@vitest/coverage-v8": "4.1.9",
     "typescript": "6.0.3",
     "typescript-eslint": "8.62.1",
     "vitest": "4.1.9"

package/schemas/run-artifact.schema.json

@@ -49,6 +49,7 @@
         "tools-invoke",
         "security",
         "security-lite",
+        "attack-sim",
         "conformance",
         "schema-quality"
       ]

package/scripts/postinstall.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const projectRoot = path.resolve(process.env.INIT_CWD || process.cwd());
+const isSelfInstall = projectRoot === packageRoot || projectRoot.startsWith(`${packageRoot}${path.sep}`);
+const disabled = process.env.MCP_OBSERVATORY_POSTINSTALL === "0" ||
+  process.env.MCP_OBSERVATORY_DISABLE_POSTINSTALL === "1";
+const forceAuto = process.env.MCP_OBSERVATORY_AUTO_SETUP_CI === "1";
+const isCi = process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value || {}, key);
+}
+
+function isLikelyMcpProject(pkg) {
+  const keywords = Array.isArray(pkg?.keywords) ? pkg.keywords.map(String) : [];
+  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}), ...(pkg?.peerDependencies || {}) };
+  return Boolean(pkg?.mcpName) ||
+    keywords.some((keyword) => /^(mcp|mcp-server|model-context-protocol)$/i.test(keyword)) ||
+    hasOwn(deps, "@modelcontextprotocol/sdk") ||
+    Object.keys(pkg?.scripts || {}).some((name) => /(^|:)mcp($|:|-)/i.test(name));
+}
+
+function inferCommand(pkg, config) {
+  if (process.env.MCP_OBSERVATORY_TARGET_COMMAND) return process.env.MCP_OBSERVATORY_TARGET_COMMAND;
+  if (typeof config?.command === "string" && config.command.trim()) return config.command.trim();
+  const scripts = pkg?.scripts || {};
+  for (const name of ["mcp", "start:mcp", "server:mcp", "mcp:serve", "dev:mcp"]) {
+    if (typeof scripts[name] === "string") return `npm run ${name}`;
+  }
+  if (typeof pkg?.name === "string" && pkg.name.trim()) return `npx -y ${pkg.name}`;
+  return "npx -y <server-package>";
+}
+
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+
+function yamlFor(command, sarif) {
+  return [
+    "name: MCP Observatory",
+    "",
+    "on:",
+    "  pull_request:",
+    "  push:",
+    "    branches: [main]",
+    "",
+    "permissions:",
+    "  contents: read",
+    ...(sarif ? ["  security-events: write"] : []),
+    "",
+    "jobs:",
+    "  mcp-observatory:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v6",
+    "      - uses: KryptosAI/mcp-observatory/action@v0.27.0",
+    "        with:",
+    `          command: ${yamlString(command)}`,
+    "          deep: true",
+    "          security: true",
+    "          comment-on-pr: false",
+    "          set-status: false",
+    ...(sarif ? ["          upload-sarif: true"] : []),
+    "          # Generated by @kryptosai/mcp-observatory postinstall.",
+    "",
+  ].join("\n");
+}
+
+function writeCi(projectRoot, command, sarif) {
+  const workflowPath = path.join(projectRoot, ".github", "workflows", "mcp-observatory.yml");
+  mkdirSync(path.dirname(workflowPath), { recursive: true });
+  try {
+    writeFileSync(workflowPath, yamlFor(command, sarif), { encoding: "utf8", flag: "wx" });
+    return { status: "created", workflowPath };
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+      return { status: "exists", workflowPath };
+    }
+    throw error;
+  }
+}
+
+function log(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+try {
+  if (disabled || isSelfInstall || isCi) process.exit(0);
+
+  const pkg = readJson(path.join(projectRoot, "package.json"));
+  if (!pkg || !isLikelyMcpProject(pkg)) process.exit(0);
+
+  const config = pkg.mcpObservatory && typeof pkg.mcpObservatory === "object" ? pkg.mcpObservatory : {};
+  const command = inferCommand(pkg, config);
+  const sarif = config.sarif === true || process.env.MCP_OBSERVATORY_AUTO_SETUP_SARIF === "1";
+  const autoSetup = forceAuto || config.autoSetupCi === true;
+
+  if (autoSetup) {
+    const result = writeCi(projectRoot, command, sarif);
+    const relative = path.relative(projectRoot, result.workflowPath);
+    log(result.status === "created"
+      ? `MCP Observatory: created ${relative}. Verify with: npx @kryptosai/mcp-observatory setup-ci --doctor`
+      : `MCP Observatory: ${relative} already exists. Verify with: npx @kryptosai/mcp-observatory setup-ci --doctor`);
+  } else {
+    log(`MCP Observatory: CI ready. Run: npx @kryptosai/mcp-observatory setup-ci --all --command "${command.replaceAll("\"", "\\\"")}"${sarif ? " --sarif" : ""}`);
+    log("MCP Observatory: to auto-create CI on install, set package.json mcpObservatory.autoSetupCi=true.");
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  log(`MCP Observatory: install-time CI helper skipped (${message}).`);
+}