@ntcore-ts/mcp 1.0.0-beta.2

package/dist/index.esm.js

@@ -0,0 +1,998 @@
+import { BUILT_IN_STRUCT_TYPE_NAMES, getBuiltInDescriptor, unpack, NetworkTables, LogLevel } from '@ntcore-ts/client';
+import { McpServer } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+
+/** Shared response helpers and payload caps for MCP tool results. */
+const MAX_TOPICS = 500;
+const MAX_SAMPLES_PER_TOPIC = 200;
+const MAX_SUBSCRIBE_TOPICS = 100;
+const MAX_GET_MULTIPLE = 50;
+const DEFAULT_SUBSCRIBE_DURATION_S = 2;
+const MAX_SUBSCRIBE_DURATION_S = 30;
+function jsonResult(payload, isError = false) {
+    const structuredContent = payload !== null && typeof payload === 'object' && !Array.isArray(payload)
+        ? payload
+        : { value: payload };
+    const content = [{ type: 'text', text: JSON.stringify(payload, jsonReplacer, 2) }];
+    if (isError) {
+        return { content, structuredContent, isError: true };
+    }
+    return { content, structuredContent };
+}
+function jsonReplacer(_key, value) {
+    if (value instanceof Uint8Array) {
+        return {
+            __type: 'Uint8Array',
+            length: value.length,
+            hexPreview: Buffer.from(value.subarray(0, Math.min(32, value.length))).toString('hex'),
+        };
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    return value;
+}
+/** Convert a value into JSON-safe form for tool responses. */
+function toJsonSafe(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string')
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Uint8Array) {
+        return {
+            __type: 'Uint8Array',
+            length: value.length,
+            hexPreview: Buffer.from(value.subarray(0, Math.min(32, value.length))).toString('hex'),
+        };
+    }
+    if (Array.isArray(value))
+        return value.map(toJsonSafe);
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = toJsonSafe(v);
+        }
+        return out;
+    }
+    return String(value);
+}
+/** Match topic paths against simple glob patterns (`*` = one segment, `**` = any depth). */
+function matchGlob(path, pattern) {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const normalizedPattern = pattern.startsWith('/') ? pattern : `/${pattern}`;
+    const regex = globToRegExp(normalizedPattern);
+    return regex.test(normalizedPath);
+}
+function globToRegExp(pattern) {
+    let i = 0;
+    let out = '^';
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                out += '.*';
+                i += 2;
+                if (pattern[i] === '/')
+                    i += 1;
+            }
+            else {
+                out += '[^/]*';
+                i += 1;
+            }
+        }
+        else if (c === '?') {
+            out += '[^/]';
+            i += 1;
+        }
+        else if ('\\.[]{}()+-^$|'.includes(c)) {
+            out += `\\${c}`;
+            i += 1;
+        }
+        else {
+            out += c;
+            i += 1;
+        }
+    }
+    out += '$';
+    return new RegExp(out);
+}
+
+const BUILTIN_STRUCT_TYPE_NAMES = [...BUILT_IN_STRUCT_TYPE_NAMES];
+/** Resolve a typed topic handle from a NetworkTables wire type string. */
+function resolveTopic(nt, name, type) {
+    switch (type) {
+        case 'boolean':
+            return nt.getBooleanTopic(name);
+        case 'double':
+            return nt.getDoubleTopic(name);
+        case 'int':
+            return nt.getIntegerTopic(name);
+        case 'float':
+            return nt.getFloatTopic(name);
+        case 'string':
+            return nt.getStringTopic(name);
+        case 'boolean[]':
+            return nt.getBooleanArrayTopic(name);
+        case 'double[]':
+            return nt.getDoubleArrayTopic(name);
+        case 'int[]':
+            return nt.getIntegerArrayTopic(name);
+        case 'float[]':
+            return nt.getFloatArrayTopic(name);
+        case 'string[]':
+            return nt.getStringArrayTopic(name);
+        case 'json':
+            return nt.getJsonTopic(name);
+        case 'raw':
+            return nt.getRawTopic(name);
+    }
+    if (type.startsWith('struct:')) {
+        const typeName = type.slice('struct:'.length);
+        return nt.getStructTopic(name, { typeName });
+    }
+    if (type.startsWith('proto:') || type === 'protobuf') {
+        return nt.getProtobufTopic(name);
+    }
+    return nt.getRawTopic(name);
+}
+function isStructOrProtobufType(type) {
+    return type.startsWith('struct:') || type.startsWith('proto:') || type === 'protobuf';
+}
+
+/** Decode a struct wire payload using built-in descriptors when possible. */
+function decodeStructBytes(typeName, bytes) {
+    const isArray = typeName.endsWith('[]');
+    const base = isArray ? typeName.slice(0, -2) : typeName;
+    const desc = getBuiltInDescriptor(base);
+    if (!desc)
+        return null;
+    try {
+        if (isArray) {
+            const elemSize = desc.size;
+            if (bytes.length % elemSize !== 0)
+                return null;
+            const n = bytes.length / elemSize;
+            const arr = [];
+            for (let i = 0; i < n; i++) {
+                arr.push(unpack(new Uint8Array(bytes.buffer, bytes.byteOffset + i * elemSize, elemSize), desc));
+            }
+            return toJsonSafe(arr);
+        }
+        return toJsonSafe(unpack(bytes, desc));
+    }
+    catch {
+        return null;
+    }
+}
+function decodeInventoryValue(type, rawValue) {
+    if (rawValue == null)
+        return null;
+    if (rawValue instanceof Uint8Array) {
+        if (type.startsWith('struct:')) {
+            return decodeStructBytes(type.slice('struct:'.length), rawValue);
+        }
+        return toJsonSafe(rawValue);
+    }
+    return toJsonSafe(rawValue);
+}
+/** Parent prefix for a topic path, e.g. /MyTable/Gyro -> /MyTable/ */
+function topicParentPrefix(topic) {
+    const idx = topic.lastIndexOf('/');
+    if (idx <= 0)
+        return '/';
+    return topic.slice(0, idx + 1);
+}
+async function snapshotTopic(nt, topic, settleMs = 400) {
+    const prefix = topicParentPrefix(topic);
+    let found = null;
+    const prefixTopic = nt.getPrefixTopic(prefix);
+    const subuid = prefixTopic.subscribe((value, params) => {
+        if (params.name === topic) {
+            found = { type: params.type, rawValue: value };
+        }
+    }, { immediateNotify: true, all: true });
+    await new Promise((r) => setTimeout(r, settleMs));
+    try {
+        prefixTopic.unsubscribe(subuid);
+    }
+    catch {
+        // ignore
+    }
+    return found;
+}
+
+/**
+ * Topic discovery cache.
+ *
+ * Uses short-lived prefix subscriptions for snapshots. A long-lived prefix `/`
+ * subscription prevents later typed topic subscriptions from receiving values
+ * (ntcore-ts / NT4 interaction), so we never leave a prefix sub open.
+ */
+class TopicInventory {
+    constructor() {
+        this.topics = new Map();
+        this.nt = null;
+        this.started = false;
+    }
+    async start(nt, prefix = '/') {
+        this.nt = nt;
+        this.started = true;
+        await this.refresh(prefix, 400);
+    }
+    stop() {
+        this.nt = null;
+        this.topics.clear();
+        this.started = false;
+    }
+    get isStarted() {
+        return this.started;
+    }
+    async refresh(prefix = '/', settleMs = 300) {
+        if (!this.nt)
+            return;
+        const prefixTopic = this.nt.getPrefixTopic(prefix);
+        const subuid = prefixTopic.subscribe((value, params) => {
+            this.upsert(params, value);
+        }, { immediateNotify: true, all: true });
+        await new Promise((r) => setTimeout(r, settleMs));
+        try {
+            prefixTopic.unsubscribe(subuid);
+        }
+        catch {
+            // ignore
+        }
+    }
+    upsert(params, value) {
+        const existing = this.topics.get(params.name);
+        this.topics.set(params.name, {
+            name: params.name,
+            type: params.type,
+            id: params.id,
+            properties: params.properties ?? null,
+            lastValue: toJsonSafe(value),
+            rawValue: value,
+            lastChangedTime: existing?.lastChangedTime ?? null,
+        });
+    }
+    updateValue(name, value, lastChangedTime) {
+        const existing = this.topics.get(name);
+        if (!existing)
+            return;
+        existing.lastValue = toJsonSafe(value);
+        existing.rawValue = value;
+        if (lastChangedTime != null)
+            existing.lastChangedTime = lastChangedTime;
+    }
+    get(name) {
+        return this.topics.get(name);
+    }
+    list(prefix, limit = MAX_TOPICS) {
+        const all = [...this.topics.values()].sort((a, b) => a.name.localeCompare(b.name));
+        const filtered = prefix ? all.filter((t) => t.name.startsWith(prefix)) : all;
+        return filtered.slice(0, limit);
+    }
+    discoveredStructTypes() {
+        const names = new Set();
+        for (const topic of this.topics.values()) {
+            if (topic.type.startsWith('struct:')) {
+                const raw = topic.type.slice('struct:'.length);
+                names.add(raw.endsWith('[]') ? raw.slice(0, -2) : raw);
+            }
+            if (topic.name.startsWith('/.schema/struct:')) {
+                names.add(topic.name.slice('/.schema/struct:'.length));
+            }
+        }
+        return [...names].sort();
+    }
+}
+
+/** Stderr-only logging for stdio MCP servers (stdout is the protocol channel). */
+function writeStderr(prefix, message, details) {
+    // Single-line messages only — multi-line / multi-arg console.error can confuse MCP hosts.
+    if (details && Object.keys(details).length > 0) {
+        console.error(`${prefix} ${message} ${JSON.stringify(details)}`);
+    }
+    else {
+        console.error(`${prefix} ${message}`);
+    }
+}
+function logInfo(message, details) {
+    writeStderr('[ntcore-ts-mcp]', message, details);
+}
+function logWarn(message, details) {
+    writeStderr('[ntcore-ts-mcp:warn]', message, details);
+}
+
+function isNumeric(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function valuesEqual(a, b, epsilon) {
+    if (isNumeric(a) && isNumeric(b))
+        return Math.abs(a - b) <= epsilon;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Collect samples via short-lived prefix subscriptions only.
+ * (Typed topic subscriptions do not receive values after a prefix sub has been used
+ * on the same NetworkTables instance — see inventory snapshot design.)
+ */
+async function collectSamples(nt, options) {
+    const durationSeconds = Math.min(Math.max(options.durationSeconds ?? DEFAULT_SUBSCRIBE_DURATION_S, 0.1), MAX_SUBSCRIBE_DURATION_S);
+    const format = options.format ?? 'summary';
+    const changeOnly = options.changeOnly ?? false;
+    const epsilon = options.changeEpsilon ?? 1e-9;
+    const sampleIntervalMs = options.sampleIntervalMs ?? 0;
+    const typeMap = { ...(options.types ?? {}) };
+    const buckets = new Map();
+    let truncated = false;
+    const ensureBucket = (name, type) => {
+        let bucket = buckets.get(name);
+        if (!bucket) {
+            if (buckets.size >= MAX_SUBSCRIBE_TOPICS) {
+                truncated = true;
+                return null;
+            }
+            bucket = { type, points: [], lastRaw: undefined };
+            buckets.set(name, bucket);
+        }
+        return bucket;
+    };
+    const record = (name, type, value) => {
+        if (value == null)
+            return;
+        let decoded = value;
+        if (value instanceof Uint8Array) {
+            decoded = decodeInventoryValue(type, value);
+            if (decoded == null)
+                return;
+        }
+        const bucket = ensureBucket(name, type);
+        if (!bucket)
+            return;
+        if (changeOnly && bucket.lastRaw !== undefined && valuesEqual(bucket.lastRaw, decoded, epsilon)) {
+            return;
+        }
+        const now = Date.now();
+        if (sampleIntervalMs > 0 && bucket.points.length > 0) {
+            const lastT = bucket.points[bucket.points.length - 1].t;
+            if (now - lastT < sampleIntervalMs)
+                return;
+        }
+        if (bucket.points.length >= MAX_SAMPLES_PER_TOPIC) {
+            truncated = true;
+            return;
+        }
+        bucket.lastRaw = decoded;
+        bucket.points.push({ t: now, value: toJsonSafe(decoded) });
+    };
+    const prefixTopics = options.prefixes.map((prefix) => {
+        const pt = nt.getPrefixTopic(prefix);
+        const subuid = pt.subscribe((value, params) => {
+            const type = typeMap[params.name] ?? params.type;
+            typeMap[params.name] = type;
+            record(params.name, type, value);
+        }, { all: true, immediateNotify: true });
+        return { pt, subuid };
+    });
+    await new Promise((r) => setTimeout(r, durationSeconds * 1000));
+    for (const { pt, subuid } of prefixTopics) {
+        try {
+            pt.unsubscribe(subuid);
+        }
+        catch {
+            // ignore
+        }
+    }
+    const summaries = [];
+    const samples = {};
+    for (const [topic, bucket] of buckets) {
+        if (format === 'samples') {
+            samples[topic] = bucket.points;
+        }
+        const nums = bucket.points.map((p) => p.value).filter(isNumeric);
+        const first = bucket.points[0]?.value ?? null;
+        const last = bucket.points[bucket.points.length - 1]?.value ?? null;
+        const elapsedSec = bucket.points.length >= 2
+            ? (bucket.points[bucket.points.length - 1].t - bucket.points[0].t) / 1000
+            : durationSeconds;
+        const summary = {
+            topic,
+            type: bucket.type,
+            count: bucket.points.length,
+            first,
+            last,
+            rateHz: elapsedSec > 0 ? bucket.points.length / elapsedSec : undefined,
+        };
+        if (nums.length > 0) {
+            summary.min = Math.min(...nums);
+            summary.max = Math.max(...nums);
+            summary.mean = nums.reduce((a, b) => a + b, 0) / nums.length;
+        }
+        summaries.push(summary);
+    }
+    summaries.sort((a, b) => a.topic.localeCompare(b.topic));
+    return {
+        durationSeconds,
+        topicCount: buckets.size,
+        format,
+        ...(format === 'summary' ? { summaries } : { samples, summaries }),
+        truncated,
+    };
+}
+
+class NtSession {
+    constructor() {
+        this.nt = null;
+    }
+    get client() {
+        return this.nt;
+    }
+    getConnectionInfo() {
+        if (!this.nt) {
+            return { connected: false, connecting: false, uri: null, port: null, rttMs: -1 };
+        }
+        return {
+            connected: this.nt.isRobotConnected(),
+            connecting: this.nt.isRobotConnecting(),
+            uri: this.nt.getURI(),
+            port: this.nt.getPort(),
+            rttMs: this.nt.getRttMs(),
+        };
+    }
+    async connect(options) {
+        const port = options.port ?? 5810;
+        const timeoutMs = options.timeoutMs ?? 10000;
+        if (options.team == null && !options.host) {
+            throw new Error('Provide either team or host to connect.');
+        }
+        if (options.team != null && options.host) {
+            throw new Error('Provide either team or host, not both.');
+        }
+        this.disconnect();
+        if (options.team != null) {
+            this.nt = NetworkTables.getInstanceByTeam(options.team, port, options.platform ?? 'roborio');
+            logInfo('Connecting by team', { team: options.team, port, platform: options.platform ?? 'roborio' });
+        }
+        else {
+            this.nt = NetworkTables.getInstanceByURI(options.host, port);
+            logInfo('Connecting by host', { host: options.host, port });
+        }
+        await this.waitUntilConnected(timeoutMs);
+        return this.getConnectionInfo();
+    }
+    disconnect() {
+        if (this.nt) {
+            logInfo('Disconnecting', { uri: this.nt.getURI(), port: this.nt.getPort() });
+            try {
+                this.nt.close();
+            }
+            catch {
+                // ignore teardown races
+            }
+            this.nt = null;
+        }
+    }
+    requireClient() {
+        if (!this.nt) {
+            throw new Error('Not connected. Call nt_connect first (team or host/port).');
+        }
+        return this.nt;
+    }
+    waitUntilConnected(timeoutMs = 10000) {
+        const nt = this.requireClient();
+        return new Promise((resolve, reject) => {
+            if (nt.isRobotConnected()) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(() => {
+                remove();
+                reject(new Error(`Connection timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const remove = nt.addRobotConnectionListener((connected) => {
+                if (connected) {
+                    clearTimeout(timer);
+                    remove();
+                    resolve();
+                }
+            }, true);
+        });
+    }
+}
+
+const DEFAULT_ALLOWLIST = ['/SmartDashboard/**', '/Tuning/**', '/MyTable/**'];
+class WriteGate {
+    constructor(options) {
+        this.sessionEnabled = false;
+        this.wasToggledOff = false;
+        const fromEnv = process.env.NT_WRITE_ALLOWLIST?.split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        this.allowlist = options?.allowlist ?? (fromEnv?.length ? fromEnv : DEFAULT_ALLOWLIST);
+        this.requireLocalhost =
+            options?.requireLocalhost ??
+                (process.env.NT_REQUIRE_LOCALHOST === '1' || process.env.NT_REQUIRE_LOCALHOST === 'true');
+        this.envBootstrap =
+            options?.envAllowWrites ?? (process.env.NT_ALLOW_WRITES === '1' || process.env.NT_ALLOW_WRITES === 'true');
+        if (this.envBootstrap) {
+            this.sessionEnabled = true;
+            logInfo('Write gate enabled from NT_ALLOW_WRITES');
+        }
+    }
+    getStatus() {
+        return {
+            enabled: this.sessionEnabled,
+            source: this.sessionEnabled ? (this.envBootstrap && !this.wasToggledOff ? 'env' : 'session') : 'off',
+            allowlist: [...this.allowlist],
+            requireLocalhost: this.requireLocalhost,
+        };
+    }
+    setWriteMode(enabled, confirm) {
+        if (enabled && !confirm) {
+            throw new Error('Enabling writes requires confirm: true. Writes can change robot behavior.');
+        }
+        this.sessionEnabled = enabled;
+        if (!enabled)
+            this.wasToggledOff = true;
+        logInfo(`Write mode ${enabled ? 'ENABLED' : 'disabled'}`, { confirm });
+        return this.getStatus();
+    }
+    assertCanWrite(topic, host) {
+        if (!this.sessionEnabled) {
+            throw new Error('Writes are disabled. Call nt_set_write_mode({ enabled: true, confirm: true }) or set NT_ALLOW_WRITES=1.');
+        }
+        if (this.requireLocalhost) {
+            const h = (host ?? '').toLowerCase();
+            if (h !== 'localhost' && h !== '127.0.0.1' && h !== '::1') {
+                throw new Error(`NT_REQUIRE_LOCALHOST is set; refusing write to non-local host "${host ?? '(unknown)'}".`);
+            }
+        }
+        if (!this.allowlist.some((pattern) => matchGlob(topic, pattern))) {
+            throw new Error(`Topic "${topic}" is not on the write allowlist (${this.allowlist.join(', ')}).`);
+        }
+    }
+    auditWrite(topic, valueDigest) {
+        logWarn('WRITE', { topic, valueDigest });
+    }
+}
+
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class NtMcpService {
+    constructor() {
+        this.session = new NtSession();
+        this.inventory = new TopicInventory();
+        this.writeGate = new WriteGate();
+    }
+    guide() {
+        const conn = this.session.getConnectionInfo();
+        const writes = this.writeGate.getStatus();
+        return jsonResult({
+            connected: conn.connected,
+            writeGate: writes,
+            connection: conn,
+            callFirst: 'nt_guide',
+            workflow: [
+                '1. Call nt_guide (this tool) if unfamiliar.',
+                '2. nt_connect with team or host/port (sim: host=127.0.0.1 or localhost, port=5810).',
+                '3. nt_list_topics to discover names/types.',
+                '4. Prefer nt_get_decoded for struct:/proto: topics; nt_get for scalars.',
+                '5. Use nt_subscribe for timed evidence (summary) instead of a single get when debugging dynamics.',
+                '6. Writes are off by default. Enable with nt_set_write_mode({ enabled: true, confirm: true }) or NT_ALLOW_WRITES=1.',
+            ],
+            tools: {
+                nt_connect: 'Open NT4 connection (team XOR host).',
+                nt_disconnect: 'Close connection and clear inventory.',
+                nt_connection_info: 'connected / RTT / endpoint.',
+                nt_list_topics: 'Cached topic inventory (prefix filter).',
+                nt_get: 'Single topic value (scalars/arrays/json; raw preview for bytes).',
+                nt_get_multiple: 'Batch get (max 50).',
+                nt_get_decoded: 'Decode struct/protobuf topics to JSON objects.',
+                nt_subscribe: 'Sample prefixes for N seconds; format=summary|samples.',
+                nt_list_struct_types: 'Built-in + discovered struct type names.',
+                nt_set_write_mode: 'Enable/disable session writes (confirm required to enable).',
+                nt_set: 'Publish one topic (gated + allowlist).',
+                nt_set_multiple: 'Publish several topics (gated + allowlist).',
+            },
+            safety: [
+                'Never use NT writes as a substitute for Driver Station enable/disable.',
+                'Default allowlist: /SmartDashboard/**, /Tuning/**, /MyTable/** (override with NT_WRITE_ALLOWLIST).',
+                'Set NT_REQUIRE_LOCALHOST=1 to refuse writes to non-local hosts.',
+                'One sample is not root cause — prefer nt_subscribe summaries for live evidence.',
+            ],
+            outOfScope: [
+                'WPILOG / offline log analysis (use wpilog-mcp).',
+                'roboRIO DS status / subsystems (use refinery-roborio-mcp).',
+                'HTTP MCP transport, MCP Resources, persistent poll subscriptions.',
+            ],
+        });
+    }
+    async connect(options) {
+        try {
+            this.inventory.stop();
+            const info = await this.session.connect(options);
+            const nt = this.session.requireClient();
+            await this.inventory.start(nt, '/');
+            return jsonResult({ ...info, inventoryStarted: true });
+        }
+        catch (err) {
+            return jsonResult({ connected: false, error: err instanceof Error ? err.message : String(err) }, true);
+        }
+    }
+    disconnect() {
+        this.inventory.stop();
+        this.session.disconnect();
+        return jsonResult({ connected: false, disconnected: true });
+    }
+    connectionInfo() {
+        const info = this.session.getConnectionInfo();
+        return jsonResult({ ...info, writeGate: this.writeGate.getStatus() });
+    }
+    async listTopics(prefix, limit = MAX_TOPICS) {
+        try {
+            const nt = this.session.requireClient();
+            if (!this.inventory.isStarted)
+                await this.inventory.start(nt, '/');
+            else
+                await this.inventory.refresh(prefix ?? '/', 250);
+            const topics = this.inventory.list(prefix, limit);
+            return jsonResult({
+                connected: nt.isRobotConnected(),
+                prefix: prefix ?? '/',
+                count: topics.length,
+                topics: topics.map(({ name, type, id, properties }) => ({ name, type, id, properties })),
+            });
+        }
+        catch (err) {
+            return jsonResult({ connected: false, error: err instanceof Error ? err.message : String(err) }, true);
+        }
+    }
+    async get(topic) {
+        try {
+            const nt = this.session.requireClient();
+            await this.inventory.refresh(topic.includes('/') ? topic.slice(0, topic.lastIndexOf('/') + 1) || '/' : '/', 350);
+            let record = this.inventory.get(topic);
+            if (!record) {
+                const snap = await snapshotTopic(nt, topic, 400);
+                if (snap) {
+                    this.inventory.upsert({ name: topic, id: -1, type: snap.type, properties: {} }, snap.rawValue);
+                    record = this.inventory.get(topic);
+                }
+            }
+            if (!record) {
+                return jsonResult({
+                    connected: nt.isRobotConnected(),
+                    topic,
+                    error: `Unknown topic "${topic}". Call nt_list_topics first so the inventory can learn its type.`,
+                }, true);
+            }
+            const value = decodeInventoryValue(record.type, record.rawValue) ?? record.lastValue;
+            return jsonResult({
+                connected: nt.isRobotConnected(),
+                topic,
+                type: record.type,
+                timestamp: record.lastChangedTime,
+                value,
+            });
+        }
+        catch (err) {
+            return jsonResult({
+                connected: this.session.getConnectionInfo().connected,
+                topic,
+                error: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    }
+    async getMultiple(topics) {
+        const slice = topics.slice(0, MAX_GET_MULTIPLE);
+        const results = [];
+        for (const topic of slice) {
+            results.push((await this.get(topic)).structuredContent);
+        }
+        return jsonResult({
+            connected: this.session.getConnectionInfo().connected,
+            count: results.length,
+            truncated: topics.length > MAX_GET_MULTIPLE,
+            results,
+        });
+    }
+    async getDecoded(topic, typeHint) {
+        try {
+            const nt = this.session.requireClient();
+            await this.inventory.refresh(topic.includes('/') ? topic.slice(0, topic.lastIndexOf('/') + 1) || '/' : '/', 400);
+            let record = this.inventory.get(topic);
+            if (!record) {
+                const snap = await snapshotTopic(nt, topic, 500);
+                if (snap) {
+                    this.inventory.upsert({ name: topic, id: -1, type: snap.type, properties: {} }, snap.rawValue);
+                    record = this.inventory.get(topic);
+                }
+            }
+            const type = typeHint ?? record?.type;
+            if (!type) {
+                return jsonResult({
+                    connected: nt.isRobotConnected(),
+                    topic,
+                    error: `Unknown topic type for "${topic}". Pass typeHint or call nt_list_topics first.`,
+                }, true);
+            }
+            if (!isStructOrProtobufType(type) && !(typeHint && isStructOrProtobufType(typeHint))) {
+                return jsonResult({
+                    connected: nt.isRobotConnected(),
+                    topic,
+                    type,
+                    error: `Topic type "${type}" is not struct/protobuf. Use nt_get instead, or pass typeHint like "struct:Pose2d".`,
+                }, true);
+            }
+            const wireType = typeHint && isStructOrProtobufType(typeHint) ? typeHint : type;
+            const raw = record?.rawValue;
+            let value = decodeInventoryValue(wireType, raw);
+            // Fallback: short prefix snapshot dedicated to this topic
+            if (value == null ||
+                (raw instanceof Uint8Array && value && typeof value === 'object' && '__type' in value)) {
+                const snap = await snapshotTopic(nt, topic, 500);
+                if (snap)
+                    value = decodeInventoryValue(snap.type.startsWith('struct:') ? snap.type : wireType, snap.rawValue);
+            }
+            if (value == null) {
+                return jsonResult({
+                    connected: nt.isRobotConnected(),
+                    topic,
+                    type: wireType,
+                    error: 'Decoded value is null. For custom structs, ensure the schema is published; built-in geometry types decode from inventory snapshots.',
+                }, true);
+            }
+            return jsonResult({
+                connected: nt.isRobotConnected(),
+                topic,
+                type: wireType,
+                timestamp: record?.lastChangedTime ?? null,
+                value,
+            });
+        }
+        catch (err) {
+            return jsonResult({
+                connected: this.session.getConnectionInfo().connected,
+                topic,
+                error: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    }
+    listStructTypes() {
+        const discovered = this.inventory.discoveredStructTypes();
+        return jsonResult({
+            connected: this.session.getConnectionInfo().connected,
+            builtin: BUILTIN_STRUCT_TYPE_NAMES,
+            discovered,
+        });
+    }
+    async subscribe(options) {
+        try {
+            const nt = this.session.requireClient();
+            const types = {};
+            for (const t of this.inventory.list()) {
+                types[t.name] = t.type;
+            }
+            const result = await collectSamples(nt, { ...options, types: { ...types, ...options.types } });
+            return jsonResult({ connected: nt.isRobotConnected(), ...result });
+        }
+        catch (err) {
+            return jsonResult({
+                connected: this.session.getConnectionInfo().connected,
+                error: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    }
+    setWriteMode(enabled, confirm) {
+        try {
+            const status = this.writeGate.setWriteMode(enabled, confirm);
+            return jsonResult({ connected: this.session.getConnectionInfo().connected, writeGate: status });
+        }
+        catch (err) {
+            return jsonResult({
+                connected: this.session.getConnectionInfo().connected,
+                error: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    }
+    async set(topic, value, expectedType) {
+        try {
+            const nt = this.session.requireClient();
+            const host = nt.getURI();
+            this.writeGate.assertCanWrite(topic, host);
+            const record = this.inventory.get(topic);
+            const type = expectedType ?? record?.type;
+            if (!type) {
+                throw new Error(`Cannot determine type for "${topic}". Pass expected_type or ensure the topic is announced (nt_list_topics).`);
+            }
+            if (expectedType && record?.type && expectedType !== record.type) {
+                throw new Error(`Type mismatch: expected_type=${expectedType} but announced type=${record.type}`);
+            }
+            const handle = resolveTopic(nt, topic, type);
+            await handle.publish({ retained: true });
+            // Allow publish announce to settle (server rejects set before publish is registered)
+            await sleep(50);
+            handle.setValue(value);
+            this.writeGate.auditWrite(topic, JSON.stringify(toJsonSafe(value)).slice(0, 200));
+            this.inventory.updateValue(topic, value);
+            logInfo('Published', { topic, type });
+            return jsonResult({
+                connected: nt.isRobotConnected(),
+                topic,
+                type,
+                published: true,
+                value: toJsonSafe(value),
+            });
+        }
+        catch (err) {
+            return jsonResult({
+                connected: this.session.getConnectionInfo().connected,
+                topic,
+                error: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    }
+    async setMultiple(updates) {
+        const results = [];
+        for (const u of updates) {
+            results.push((await this.set(u.topic, u.value, u.expected_type)).structuredContent);
+        }
+        const anyError = results.some((r) => typeof r.error === 'string');
+        return jsonResult({
+            connected: this.session.getConnectionInfo().connected,
+            count: results.length,
+            results,
+        }, anyError);
+    }
+}
+
+/** Build an MCP server exposing NetworkTables tools. */
+function createNtMcpServer(options) {
+    // Keep client logging off when serving over stdio (stdout = JSON-RPC).
+    NetworkTables.setLogLevel(LogLevel.SILENT);
+    const service = options?.service ?? new NtMcpService();
+    const server = new McpServer({ name: 'ntcore-ts', version: '1.0.0-beta.2' });
+    server.registerTool('nt_guide', {
+        title: 'NetworkTables MCP guide',
+        description: 'Call this first if unfamiliar. Explains workflow, tool choice (nt_get vs nt_get_decoded vs nt_subscribe), write-gate status, and safety rules. Read-only.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async () => service.guide());
+    server.registerTool('nt_connect', {
+        title: 'Connect to NetworkTables',
+        description: 'Connect to an NT4 server. Provide either team (mDNS/team IP) OR host (e.g. localhost for sim). Default port 5810. Starts topic inventory. Prefer this before list/get/subscribe.',
+        inputSchema: z.object({
+            team: z.number().int().positive().optional().describe('FRC team number (mutually exclusive with host)'),
+            host: z
+                .string()
+                .optional()
+                .describe('Hostname or IP (e.g. localhost, 127.0.0.1). Mutually exclusive with team'),
+            port: z.number().int().positive().optional().describe('NT4 port (default 5810)'),
+            platform: z
+                .enum(['roborio', 'systemcore'])
+                .optional()
+                .describe('Address resolution when using team (default roborio)'),
+            timeout_ms: z.number().int().positive().optional().describe('Connection wait timeout in ms (default 10000)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, async (args) => service.connect({
+        team: args.team,
+        host: args.host,
+        port: args.port,
+        platform: args.platform,
+        timeoutMs: args.timeout_ms,
+    }));
+    server.registerTool('nt_disconnect', {
+        title: 'Disconnect from NetworkTables',
+        description: 'Close the NT connection and clear the topic inventory cache.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, async () => service.disconnect());
+    server.registerTool('nt_connection_info', {
+        title: 'Connection info',
+        description: 'Return connected/connecting flags, endpoint, RTT, and write-gate status. Read-only.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async () => service.connectionInfo());
+    server.registerTool('nt_list_topics', {
+        title: 'List NetworkTables topics',
+        description: 'List announced topics from the inventory cache (name, type, properties). Filter with prefix (e.g. /MyTable/). Call nt_connect first. Prefer over guessing topic names. Read-only.',
+        inputSchema: z.object({
+            prefix: z.string().optional().describe('Only topics starting with this prefix'),
+            limit: z.number().int().positive().max(500).optional().describe('Max topics to return (default 500)'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async (args) => await service.listTopics(args.prefix, args.limit));
+    server.registerTool('nt_get', {
+        title: 'Get topic value',
+        description: 'Read one topic value. Best for scalars/arrays/json. For struct:/proto: topics prefer nt_get_decoded. Topic must be known via nt_list_topics. Read-only.',
+        inputSchema: z.object({
+            topic: z.string().describe('Full topic name, e.g. /MyTable/Gyro'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async (args) => service.get(args.topic));
+    server.registerTool('nt_get_multiple', {
+        title: 'Get multiple topic values',
+        description: 'Batch nt_get for up to 50 topics. Read-only.',
+        inputSchema: z.object({
+            topics: z.array(z.string()).min(1).max(50).describe('Topic names to read'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async (args) => service.getMultiple(args.topics));
+    server.registerTool('nt_get_decoded', {
+        title: 'Get decoded struct/protobuf topic',
+        description: 'Decode a struct: or proto: topic into a JSON object using @ntcore-ts/client. Prefer this over nt_get for Pose2d and other structured types. Optional type_hint like struct:Pose2d. Read-only.',
+        inputSchema: z.object({
+            topic: z.string().describe('Full topic name'),
+            type_hint: z.string().optional().describe('Override wire type, e.g. struct:Pose2d or proto:Pose2d'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async (args) => service.getDecoded(args.topic, args.type_hint));
+    server.registerTool('nt_list_struct_types', {
+        title: 'List struct types',
+        description: 'List built-in WPILib geometry struct types and any discovered from /.schema/struct:* or live topics. Read-only.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    }, async () => service.listStructTypes());
+    server.registerTool('nt_subscribe', {
+        title: 'Timed subscribe / sample',
+        description: 'Sample topic updates under prefixes for duration_seconds. Use format=summary for min/max/mean/last/rate (preferred evidence). format=samples returns capped point lists. Prefer over repeated nt_get for dynamics. Read-only.',
+        inputSchema: z.object({
+            prefixes: z.array(z.string()).min(1).max(20).describe('Topic prefixes to sample (e.g. ["/MyTable/"])'),
+            duration_seconds: z.number().positive().max(30).optional().describe('How long to sample (default 2, max 30)'),
+            sample_interval_ms: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Min ms between stored samples per topic (0 = every change)'),
+            change_only: z.boolean().optional().describe('Skip numeric changes at or below change_epsilon'),
+            change_epsilon: z.number().optional().describe('Epsilon for change_only numerics (default 1e-9)'),
+            format: z.enum(['summary', 'samples']).optional().describe('summary (default) or samples'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false },
+    }, async (args) => service.subscribe({
+        prefixes: args.prefixes,
+        durationSeconds: args.duration_seconds,
+        sampleIntervalMs: args.sample_interval_ms,
+        changeOnly: args.change_only,
+        changeEpsilon: args.change_epsilon,
+        format: args.format,
+    }));
+    server.registerTool('nt_set_write_mode', {
+        title: 'Enable or disable NT writes',
+        description: 'Session write gate. Enabling REQUIRES confirm=true. Also enabled when NT_ALLOW_WRITES=1 at process start. Does not bypass path allowlist. Destructive.',
+        inputSchema: z.object({
+            enabled: z.boolean().describe('true to allow nt_set / nt_set_multiple'),
+            confirm: z.boolean().optional().describe('Must be true when enabling writes'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async (args) => service.setWriteMode(args.enabled, args.confirm ?? false));
+    server.registerTool('nt_set', {
+        title: 'Set / publish a topic value',
+        description: 'Publish a value to one topic. Fails if write gate is off, topic is outside NT_WRITE_ALLOWLIST, or types mismatch. Prefer expected_type when known. Destructive — can affect robot behavior. Not for DS enable.',
+        inputSchema: z.object({
+            topic: z.string().describe('Full topic name'),
+            value: z.unknown().describe('Value to publish (JSON-compatible for scalars/structs)'),
+            expected_type: z.string().optional().describe('NT type string, e.g. double or struct:Pose2d'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+    }, async (args) => await service.set(args.topic, args.value, args.expected_type));
+    server.registerTool('nt_set_multiple', {
+        title: 'Set / publish multiple topics',
+        description: 'Batch nt_set. Same write-gate and allowlist rules. Destructive.',
+        inputSchema: z.object({
+            updates: z
+                .array(z.object({
+                topic: z.string(),
+                value: z.unknown(),
+                expected_type: z.string().optional(),
+            }))
+                .min(1)
+                .max(50),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+    }, async (args) => await service.setMultiple(args.updates));
+    return server;
+}
+
+export { BUILTIN_STRUCT_TYPE_NAMES, NtMcpService, NtSession, TopicInventory, WriteGate, collectSamples, createNtMcpServer, jsonResult, matchGlob, resolveTopic, toJsonSafe };
+//# sourceMappingURL=index.esm.js.map