SemanticAnalyzer class reference

Full reference for the SemanticAnalyzer class: constructor options, corpus overlap behavior, semantic parameter matching, and the SemanticReport shape.

SemanticAnalyzer compares your tool descriptions against MCP tools in the semantic corpus and also performs a deeper semantic parameter pass within the server you are scanning. Today the corpus is built from Smithery data and shipped as an HNSW index plus metadata file. The analyzer runs locally against that index; it does not call Smithery during analyze().

Constructor

new SemanticAnalyzer(config?: { threshold?: number; topK?: number; parameterThreshold?: number })

Pass an optional configuration object to tune how strictly the analyzer matches tools.

import { SemanticAnalyzer } from 'mcp-watchtower'

const defaultAnalyzer = new SemanticAnalyzer()
const strictAnalyzer = new SemanticAnalyzer({ threshold: 0.85, topK: 5 })

Config options

config.threshold · number · default: "0.75"

Minimum similarity score required before a match becomes a finding. Valid values are between 0 and 1. Raise the threshold to reduce borderline matches.

config.topK · number · default: "10"

Number of nearest neighbors to retrieve from the semantic index for each tool before threshold filtering is applied. Higher values increase recall at the cost of more comparison work.

config.parameterThreshold · number · default: "0.88"

Minimum similarity score required before the within-server semantic parameter matcher emits SEMANTIC_PARAMETER_CONFLICT. When omitted, Watchtower uses the stricter of threshold and 0.88 to keep the deeper pass conservative by default.

analyze()

analyze(serverName: string, tools: ToolSchema[]): Promise<SemanticReport>

Runs semantic overlap detection for the provided tools and returns a SemanticReport.

Parameters

serverName · string · required

Human-readable label for the server being analyzed. Matches from the same serverName are filtered out so the analyzer does not flag your own corpus entry as a cross-server overlap.

tools · ToolSchema[] · required

Array of tool definitions to compare against the corpus. Tools with empty descriptions are skipped because they cannot be embedded meaningfully.

Return value

analyze() resolves to a SemanticReport.

server · string · required

The serverName value you passed in.

toolCount · number · required

Number of tools in the input array.

findings · SemanticFinding[] · required

Semantic findings that met the configured threshold.

scannedAt · string · required

ISO 8601 timestamp of when the scan completed.

How matching works

For each tool, SemanticAnalyzer:

1. embeds the tool description
2. builds a retrieval query from tool.name + tool.description
3. searches the local HNSW index for the nearest neighbors
4. recomputes similarity from descriptions when the tool names are identical
5. performs a within-server semantic parameter pass using parameter and tool context
6. filters corpus matches below threshold, filters parameter matches below parameterThreshold, and drops corpus matches from the same server
7. emits ALREADY_IN_CORPUS, SEMANTIC_OVERLAP, and when applicable SEMANTIC_PARAMETER_CONFLICT

The analyzer loads index files from ~/.mcp-watchtower/index when a newer downloaded index is present. Otherwise it falls back to the bundled semantic.hnsw and semantic-meta.json files shipped with the package.

Code examples

Basic usage

import { SemanticAnalyzer } from 'mcp-watchtower'
import type { ToolSchema } from 'mcp-watchtower'

const tools: ToolSchema[] = [
  {
    name: 'search_docs',
    description: 'Search internal documentation for a query string.',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query' },
      },
      required: ['query'],
    },
  },
]

const analyzer = new SemanticAnalyzer()
const report = await analyzer.analyze('my-server', tools)

for (const finding of report.findings) {
  console.log(`[${finding.code}] ${finding.message}`)
}

import { SemanticAnalyzer } from 'mcp-watchtower'

const analyzer = new SemanticAnalyzer({ threshold: 0.85, topK: 5 })
const report = await analyzer.analyze('my-server', tools)

const warnings = report.findings.filter(f => f.severity === 'warning')
console.log(`Found ${warnings.length} semantic warning(s)`)

Related pages

Semantic workflow

How the Smithery-backed corpus is crawled, embedded, indexed, and refreshed.

Types reference

Field-by-field reference for SemanticFinding and SemanticReport.