feat: improve discoverability for registries and AI agents (#62)

- Lead README with "first testing tool that is itself an MCP server"
- Add npm downloads badge and Smithery badge
- Add smithery.yaml for Smithery registry listing
- Update server.json to v0.8.2 with agent-optimized description
- Rewrite all MCP tool descriptions for agent self-discovery
- Add keywords: mcp-server, ai-agent, ai-tools, developer-tools, ci-cd, schema-drift
- Update MCP Server Mode section with "when to use" table
- Bold "Works as MCP server" in comparison table

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: KryptosAI

README.md

@@ -12,13 +12,15 @@
 
 [![CI](https://github.com/KryptosAI/mcp-observatory/actions/workflows/ci.yml/badge.svg)](https://github.com/KryptosAI/mcp-observatory/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@kryptosai/mcp-observatory)](https://www.npmjs.com/package/@kryptosai/mcp-observatory)
+[![npm downloads](https://img.shields.io/npm/dm/@kryptosai/mcp-observatory)](https://www.npmjs.com/package/@kryptosai/mcp-observatory)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-339933)](./package.json)
+[![Smithery](https://smithery.ai/badge/@kryptosai/mcp-observatory)](https://smithery.ai/server/@kryptosai/mcp-observatory)
 [![mcp-observatory MCP server](https://glama.ai/mcp/servers/KryptosAI/mcp-observatory/badges/score.svg)](https://glama.ai/mcp/servers/KryptosAI/mcp-observatory)
 
-Find problems in your MCP servers before your users do.
+**The first testing tool that is itself an MCP server.** Your AI agent can scan, test, record, replay, and verify other MCP servers autonomously — catching regressions, schema drift, and security issues without human intervention.
 
-You update a server, a tool silently breaks, and your agent starts failing. MCP Observatory catches that. It connects to your servers, checks every capability, actually calls tools to make sure they work, and diffs runs to catch what changed.
+Use it as a CLI, a CI action, or give it to your agent as an MCP server and let it test your other servers for you.
 
 <p align="center">
   <img src="./docs/demo.svg" alt="MCP Observatory scan output" width="820">
@@ -164,19 +166,25 @@ The action runs checks on every PR, comments a markdown report, and blocks merge
 
 ## MCP Server Mode
 
-When running as an MCP server (`serve`), your AI agent gets the same capabilities as the CLI:
+**No other testing tool is itself an MCP server.** Add Observatory as a server and your AI agent can autonomously test, diagnose, and monitor your other MCP servers.
 
-| Tool | What it does |
-|------|-------------|
-| `scan` | Discover and check all configured servers |
-| `check_server` | Check a specific server by command |
-| `record` | Record a server session to a cassette file |
-| `replay` | Replay a cassette offline — no live server needed |
-| `verify` | Verify a live server still matches a cassette |
-| `watch` | Run checks and diff against the previous run |
-| `diff_runs` | Compare two saved run artifacts |
-| `get_last_run` | Return the most recent run for a target |
-| `suggest_servers` | Scan your environment and recommend servers you're missing |
+```bash
+claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory serve
+```
+
+Your agent gets 9 tools:
+
+| Tool | When to use it |
+|------|---------------|
+| `scan` | Check if all your configured MCP servers are healthy |
+| `check_server` | Test a specific server before installing or after updating |
+| `record` | Capture a baseline of a working server for future comparison |
+| `replay` | Test against a recorded session — no live server needed |
+| `verify` | Confirm a server update didn't break anything |
+| `watch` | Check a server and see what changed since the last check |
+| `diff_runs` | Find regressions between two check results |
+| `get_last_run` | Retrieve previous check results for a server |
+| `suggest_servers` | Discover MCP servers that match your project stack |
 
 An AI tool that checks other AI tools. It's a tool testing tools that serve tools.*
 
@@ -259,7 +267,7 @@ npx @kryptosai/mcp-observatory run --target ./target.json
 | Benchmarking / latency | — | — | ✅ | — |
 | Jest integration | — | — | — | ✅ |
 | MCP proxy mode | — | ✅ | — | — |
-| Works as MCP server | ✅ | — | — | — |
+| **Works as MCP server** | **✅** | — | — | — |
 
 Each tool has strengths. Observatory focuses on regression detection and CI-friendly workflows. mcp-recorder is great as a transparent proxy. MCPBench is the go-to for performance benchmarking. mcp-jest is ideal if you're already in a Jest workflow.
 

package.json

@@ -51,7 +51,11 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
+    "ai-agent",
+    "ai-tools",
+    "developer-tools",
     "cli",
     "regression-testing",
     "interoperability",
@@ -62,7 +66,9 @@
     "vcr",
     "mcp-testing",
     "security",
-    "github-action"
+    "ci-cd",
+    "github-action",
+    "schema-drift"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.KryptosAI/mcp-observatory",
-  "description": "Regression testing for MCP servers. Checks capabilities, invokes tools, detects schema drift.",
+  "description": "The first testing tool that is itself an MCP server. AI agents can scan, test, record, replay, and verify other MCP servers autonomously — catching regressions, schema drift, and security issues without human intervention.",
   "repository": {
     "url": "https://github.com/KryptosAI/mcp-observatory",
     "source": "github"
   },
-  "version": "0.3.2",
+  "version": "0.8.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@kryptosai/mcp-observatory",
-      "version": "0.3.2",
+      "version": "0.8.2",
       "transport": {
         "type": "stdio"
       },

smithery.yaml

@@ -0,0 +1,10 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties: {}
+  commandFunction: |-
+    (config) => ({
+      command: "npx",
+      args: ["-y", "@kryptosai/mcp-observatory", "serve"]
+    })

src/server.ts

@@ -97,7 +97,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "scan",
-    "Auto-discover MCP servers from config files and run checks against each one. Returns a summary of tools/prompts/resources status for every discovered server.",
+    "Use this to check if all your MCP servers are healthy. Auto-discovers servers from Claude config files, connects to each one, and verifies tools/prompts/resources respond correctly. Use with deep=true to also invoke tools and confirm they actually execute. Returns pass/fail status for every server.",
     {
       config: z.string().optional().describe("Path to a specific MCP config file. If omitted, scans default locations."),
       deep: z.boolean().optional().describe("Also invoke safe tools to verify they execute."),
@@ -136,7 +136,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "check_server",
-    "Run checks against a specific MCP server by command. Example: check_server({ command: 'npx -y @modelcontextprotocol/server-everything' })",
+    "Use this to test a specific MCP server before installing or after updating it. Launches the server by command, checks all capabilities, and saves a run artifact for future comparison. Example: check_server({ command: 'npx -y @modelcontextprotocol/server-everything' }). Use deep=true to invoke tools, security=true to analyze schemas for vulnerabilities.",
     {
       command: z.string().describe("The command to launch the MCP server (e.g. 'npx -y @modelcontextprotocol/server-everything')."),
       args: z.array(z.string()).optional().describe("Additional arguments for the command."),
@@ -174,7 +174,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "score_server",
-    "Score an MCP server's health (0-100) including protocol compliance, schema quality, security, reliability, and performance. Returns grade A-F with detailed breakdown.",
+    "Use this to get a quick health grade for an MCP server. Runs all checks (capabilities, tool invocation, security) and returns a 0-100 score with A-F grade and detailed breakdown across protocol compliance, schema quality, security, reliability, and performance.",
     {
       command: z.string().describe("The command to launch the MCP server."),
       args: z.array(z.string()).optional().describe("Additional arguments for the command."),
@@ -224,7 +224,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "diff_runs",
-    "Compare two run artifact files and return the diff showing regressions, recoveries, and schema drift.",
+    "Use this to find what changed between two server checks. Compares two run artifacts and surfaces regressions (things that broke), recoveries (things that got fixed), schema drift (added/removed/changed tool parameters), and gate status changes. Essential after updating a server.",
     {
       base: z.string().describe("Path to the base run artifact JSON file."),
       head: z.string().describe("Path to the head run artifact JSON file."),
@@ -260,7 +260,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "get_last_run",
-    "Return the most recent run artifact for a given target ID. Searches the default runs directory.",
+    "Use this to retrieve the last check results for a server. Finds the most recent run artifact by target ID so you can review previous results or diff against a new run.",
     {
       targetId: z.string().describe("The target ID to find the last run for (e.g. server name or command)."),
     },
@@ -305,7 +305,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "suggest_servers",
-    "Gather context about the current environment to help recommend MCP servers. Returns currently configured servers, detected languages/frameworks/databases/services, and available servers from the MCP registry.",
+    "Use this when setting up a project or wondering what MCP servers to add. Scans the working directory for languages, frameworks, databases, and cloud providers, lists currently configured servers, and cross-references the MCP registry to recommend servers you're missing.",
     {
       cwd: z.string().optional().describe("Working directory to scan for environment signals. Defaults to process.cwd()."),
     },
@@ -412,7 +412,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "record",
-    "Record a live MCP server session to a cassette file. The cassette captures all JSON-RPC traffic and can be replayed offline or used to verify future server versions.",
+    "Use this to capture a baseline of a working MCP server. Records all JSON-RPC traffic to a cassette file that can be replayed offline (no server needed) or used to verify future versions haven't broken anything. Like VCR for MCP.",
     {
       command: z.string().describe("The command to launch the MCP server."),
       args: z.array(z.string()).optional().describe("Additional arguments for the command."),
@@ -457,7 +457,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "replay",
-    "Replay a cassette file offline — no live server needed. Runs all checks against the recorded responses.",
+    "Use this to test a server without running it. Replays a previously recorded cassette offline and runs all checks against the recorded responses. Useful in CI or when the live server is unavailable.",
     {
       cassette: z.string().describe("Path to a cassette JSON file."),
     },
@@ -510,7 +510,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "verify",
-    "Verify a live server still matches a recorded cassette. Connects to the server, replays the same requests, and compares responses.",
+    "Use this after updating a server to confirm nothing broke. Connects to the live server, sends the same requests from a recorded cassette, and compares responses. Reports exactly what changed — added tools, removed parameters, different response shapes.",
     {
       cassette: z.string().describe("Path to a cassette JSON file."),
       command: z.string().describe("The command to launch the MCP server."),
@@ -554,7 +554,7 @@ export async function startServer(): Promise<void> {
 
   server.tool(
     "watch",
-    "Run checks against a server repeatedly and report when results change. Returns the initial check and starts monitoring. Note: in MCP server mode this runs a single check and diff against the previous run rather than a persistent loop.",
+    "Use this to check a server and see what changed since the last check. Runs all checks, saves the result, and diffs against the previous run for the same target. Shows regressions, recoveries, and schema drift in one call.",
     {
       command: z.string().describe("The command to launch the MCP server."),
       args: z.array(z.string()).optional().describe("Additional arguments for the command."),