> ## Documentation Index
> Fetch the complete documentation index at: https://self-5d39fc87.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Watchtower TypeScript library overview

> Use mcp-watchtower as a Node.js or TypeScript library to run static and semantic analysis programmatically in scripts, registries, or custom CI tooling.

The `mcp-watchtower` package exposes a TypeScript API so you can run the same static and semantic analysis that power the CLI directly inside your own Node.js or TypeScript application. This is useful when you want to integrate analysis into a custom CI script, a registry that loads multiple MCP servers, or any tooling that already holds tool definitions in memory.

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install mcp-watchtower
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add mcp-watchtower
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add mcp-watchtower
    ```
  </Tab>
</Tabs>

<Note>
  `mcp-watchtower` requires Node.js 18 or later. The package ships ES modules only, so set `"type": "module"` in your `package.json` or use a `.mjs` extension.
</Note>

## Public exports

The package surface is intentionally small. Everything you need is available from the top-level import.

```typescript theme={null}
import { SemanticAnalyzer, StaticAnalyzer } from 'mcp-watchtower'
import type {
  AnalysisPhase,
  AnalysisReporter,
  AnalysisPhaseCompleteEvent,
  AnalysisToolStartEvent,
  AnalysisFindingEvent,
  Finding,
  SemanticFinding,
  SemanticReport,
  StaticAnalyzerConfig,
  StaticReport,
  ToolSchema,
} from 'mcp-watchtower'
```

| Export                       | Kind  | Description                                                                                         |
| ---------------------------- | ----- | --------------------------------------------------------------------------------------------------- |
| `StaticAnalyzer`             | Class | Runs all five static checks against a set of tool definitions.                                      |
| `SemanticAnalyzer`           | Class | Compares tool descriptions against the semantic corpus and reports likely overlaps.                 |
| `ToolSchema`                 | Type  | Shape of a single tool definition as declared in an MCP server manifest.                            |
| `Finding`                    | Type  | A single static finding with severity, code, message, and optional tool references.                 |
| `SemanticFinding`            | Type  | A single semantic overlap result produced by `SemanticAnalyzer`.                                    |
| `StaticReport`               | Type  | Full static scan output with server name, tool count, findings, and completion timestamp.           |
| `SemanticReport`             | Type  | Full semantic scan output with server name, tool count, findings, and scan timestamp.               |
| `StaticAnalyzerConfig`       | Type  | Static analyzer options including `platform`, `maxTools`, and an optional progress `reporter`.      |
| `AnalysisPhase`              | Type  | The scan phase identifier: `static` or `semantic`.                                                  |
| `AnalysisReporter`           | Type  | Optional callback interface for live `onToolStart`, `onFinding`, and `onPhaseComplete` scan events. |
| `AnalysisPhaseCompleteEvent` | Type  | Event payload emitted when a scan phase finishes with its tool and finding counts.                  |
| `AnalysisToolStartEvent`     | Type  | Event payload emitted when a tool begins analysis for a given phase.                                |
| `AnalysisFindingEvent`       | Type  | Event payload emitted when a static or semantic finding is produced.                                |

## Quick example

The following end-to-end example runs both analyzers against the same toolset.

```typescript theme={null}
import { SemanticAnalyzer, StaticAnalyzer } from 'mcp-watchtower'
import type { ToolSchema } from 'mcp-watchtower'

const tools: ToolSchema[] = [
  {
    name: 'get_stock_price',
    description: 'Fetch the latest price for a stock ticker.',
    inputSchema: {
      type: 'object',
      properties: {
        ticker: { type: 'string', description: 'Stock ticker symbol, e.g. AAPL' },
      },
      required: ['ticker'],
    },
  },
  {
    name: 'get_company_info',
    description: 'Return company metadata for a given stock.',
    inputSchema: {
      type: 'object',
      properties: {
        symbol: { type: 'string', description: 'Stock ticker symbol' },
      },
      required: ['symbol'],
    },
  },
]

const analyzer = new StaticAnalyzer({ platform: false, maxTools: 20 })
const staticReport = analyzer.analyze('my-server', tools)
const semanticReport = await new SemanticAnalyzer({ threshold: 0.8 }).analyze('my-server', tools)

const criticals = staticReport.findings.filter(f => f.severity === 'critical')
const semanticWarnings = semanticReport.findings.filter(f => f.severity === 'warning')

if (criticals.length > 0) {
  console.error(`Analysis failed with ${criticals.length} critical finding(s):`)
  for (const finding of criticals) {
    console.error(`  [${finding.code}] ${finding.message}`)
  }
  process.exit(1)
}

console.log(`Static findings: ${staticReport.findings.length}`)
console.log(`Semantic warnings: ${semanticWarnings.length}`)
console.log(semanticReport.findings)
```

<Tip>
  The `PARAMETER_CONFLICT` finding in the example above flags `ticker` (in `get_stock_price`) and `symbol` (in `get_company_info`) as likely synonyms. Standardizing on one name across your server eliminates this warning.
</Tip>

<Note>
  `SemanticAnalyzer` is asynchronous because it embeds tool and parameter context at runtime and queries the shipped semantic index. The CLI runs the same class in the default full scan and in `--semantic` mode.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="StaticAnalyzer class reference" icon="code" href="/api/static-analyzer">
    Constructor options, the `analyze()` method signature, and the full `StaticReport` shape.
  </Card>

  <Card title="SemanticAnalyzer class reference" icon="radar" href="/api/semantic-analyzer">
    Constructor options, matching behavior, and the full `SemanticReport` shape.
  </Card>

  <Card title="Types reference" icon="brackets-curly" href="/api/types">
    Full documentation for every exported interface and type, including all finding codes.
  </Card>
</CardGroup>