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

npm

npm install mcp-watchtower

pnpm

pnpm add mcp-watchtower

yarn

yarn add mcp-watchtower

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.

Public exports

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

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.

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)

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.

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.

Next steps

StaticAnalyzer class reference

Constructor options, the analyze() method signature, and the full StaticReport shape.

SemanticAnalyzer class reference

Constructor options, matching behavior, and the full SemanticReport shape.

Types reference

Full documentation for every exported interface and type, including all finding codes.