tactus-mcp 0.1.1

package/dist/safety.js

@@ -0,0 +1,216 @@
+import { TactusError } from "./types.js";
+/**
+ * Per-device rate limiter with trailing coalescing: commands under the cap go
+ * straight through; bursts above it collapse to the latest value, flushed at
+ * the rate boundary. Protects BLE from being flooded (spec §7.4).
+ */
+class RateLimiter {
+    minIntervalMs;
+    lastSentAt = 0;
+    pending;
+    timer;
+    constructor(minIntervalMs) {
+        this.minIntervalMs = minIntervalMs;
+    }
+    submit(action) {
+        const now = Date.now();
+        const elapsed = now - this.lastSentAt;
+        if (elapsed >= this.minIntervalMs) {
+            this.lastSentAt = now;
+            return action(); // under the cap — await and propagate errors
+        }
+        // Over the cap: keep only the latest command, flush when the window opens.
+        this.pending = action;
+        if (!this.timer) {
+            this.timer = setTimeout(() => {
+                this.timer = undefined;
+                const next = this.pending;
+                this.pending = undefined;
+                if (next) {
+                    this.lastSentAt = Date.now();
+                    // Fire-and-forget: the caller already received a resolved promise when
+                    // this command was coalesced, so a rejection here cannot propagate back.
+                    // Swallow it (logged to stderr) rather than letting it surface as an
+                    // unhandled rejection — a dropped trailing command must NEVER crash the
+                    // server (safety is the headline feature; playbook §3).
+                    void next().catch((e) => {
+                        console.error(`[tactus] coalesced command failed after the rate-limit window: ${e instanceof Error ? e.message : String(e)}`);
+                    });
+                }
+            }, this.minIntervalMs - elapsed);
+            this.timer.unref?.();
+        }
+        return Promise.resolve();
+    }
+    dispose() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pending = undefined;
+    }
+}
+/**
+ * Wraps a DeviceController with the safety guarantees that are Tactus's headline
+ * feature (spec §7.4, playbook §3): intensity clamp, an INDEPENDENT watchdog
+ * timer (not check-on-next-call), per-device rate limiting, stop-preemptible
+ * patterns, and fail-safe stops that retry rather than assume success.
+ */
+export class SafetyLayer {
+    controller;
+    config;
+    watchdogs = new Map();
+    limiters = new Map();
+    patterns = new Map();
+    constructor(controller, config) {
+        this.controller = controller;
+        this.config = config;
+    }
+    /** Drive methods return the EFFECTIVE value actually applied (post-clamp), so
+     *  callers can see when a request was clamped — honesty over optimism. */
+    async vibrate(deviceId, intensity, target) {
+        return this.driveScalar(deviceId, "vibrate", intensity, target);
+    }
+    async oscillate(deviceId, intensity, target) {
+        return this.driveScalar(deviceId, "oscillate", intensity, target);
+    }
+    async rotate(deviceId, speed, clockwise, target) {
+        const v = this.clampIntensity(speed);
+        this.cancelPattern(deviceId);
+        this.armWatchdog(deviceId);
+        await this.submit(deviceId, () => this.controller.rotate(deviceId, v, clockwise, target));
+        return v;
+    }
+    async linear(deviceId, position, durationMs, target) {
+        const p = Math.max(0, Math.min(1, position)); // position is a coordinate, not an intensity
+        this.cancelPattern(deviceId);
+        this.armWatchdog(deviceId);
+        await this.submit(deviceId, () => this.controller.linear(deviceId, p, durationMs, target));
+        return p;
+    }
+    /**
+     * Kick off a server-side timed pattern and return immediately. Playing is
+     * driven by chained timers (NOT an awaited sleep), so a single tool call
+     * never occupies the serial stdio handler — stop_* can always preempt it
+     * (playbook §3.4).
+     */
+    startVibratePattern(deviceId, steps, repeat, target) {
+        this.cancelPattern(deviceId);
+        const flat = [];
+        for (let r = 0; r < repeat; r++)
+            flat.push(...steps);
+        const run = { cancelled: false };
+        this.patterns.set(deviceId, run);
+        let i = 0;
+        const next = () => {
+            if (run.cancelled)
+                return;
+            if (i >= flat.length) {
+                this.patterns.delete(deviceId);
+                void this.controller.stopDevice(deviceId).catch(() => { });
+                return;
+            }
+            const step = flat[i++];
+            this.armWatchdog(deviceId);
+            void this.submit(deviceId, () => this.controller.output(deviceId, "vibrate", this.clampIntensity(step.intensity), target));
+            run.timer = setTimeout(next, step.durationMs);
+            run.timer.unref?.();
+        };
+        next();
+    }
+    /** Fail-safe stop: if we cannot confirm the device stopped, retry — never
+     *  optimistically report success (playbook §3.1). */
+    async stopDevice(deviceId) {
+        this.clearWatchdog(deviceId);
+        this.cancelPattern(deviceId);
+        await this.retry(() => this.controller.stopDevice(deviceId));
+    }
+    async stopAll() {
+        for (const id of [...this.watchdogs.keys()])
+            this.clearWatchdog(id);
+        for (const id of [...this.patterns.keys()])
+            this.cancelPattern(id);
+        await this.retry(() => this.controller.stopAll());
+    }
+    /** Drop all per-device state for a device that has disconnected. No point
+     *  keeping a watchdog/pattern/limiter alive for a device that is gone. */
+    forgetDevice(deviceId) {
+        this.clearWatchdog(deviceId);
+        this.cancelPattern(deviceId);
+        const limiter = this.limiters.get(deviceId);
+        if (limiter) {
+            limiter.dispose();
+            this.limiters.delete(deviceId);
+        }
+    }
+    /** Best-effort emergency stop for shutdown paths; never throws. */
+    async shutdown() {
+        for (const l of this.limiters.values())
+            l.dispose();
+        this.limiters.clear();
+        try {
+            await this.stopAll();
+        }
+        catch {
+            /* shutting down — nothing more we can do here */
+        }
+    }
+    // --- internals ---
+    async driveScalar(deviceId, type, intensity, target) {
+        const v = this.clampIntensity(intensity);
+        this.cancelPattern(deviceId);
+        this.armWatchdog(deviceId);
+        await this.submit(deviceId, () => this.controller.output(deviceId, type, v, target));
+        return v;
+    }
+    clampIntensity(v) {
+        return Math.max(0, Math.min(this.config.maxIntensity, v));
+    }
+    submit(deviceId, action) {
+        let limiter = this.limiters.get(deviceId);
+        if (!limiter) {
+            limiter = new RateLimiter(1000 / this.config.maxCommandsPerSec);
+            this.limiters.set(deviceId, limiter);
+        }
+        return limiter.submit(action);
+    }
+    /** (Re)arm the independent auto-stop timer for a device. */
+    armWatchdog(deviceId) {
+        this.clearWatchdog(deviceId);
+        const timer = setTimeout(() => {
+            this.watchdogs.delete(deviceId);
+            void this.retry(() => this.controller.stopDevice(deviceId)).catch(() => { });
+        }, this.config.maxContinuousMs);
+        timer.unref?.();
+        this.watchdogs.set(deviceId, timer);
+    }
+    clearWatchdog(deviceId) {
+        const timer = this.watchdogs.get(deviceId);
+        if (timer) {
+            clearTimeout(timer);
+            this.watchdogs.delete(deviceId);
+        }
+    }
+    cancelPattern(deviceId) {
+        const run = this.patterns.get(deviceId);
+        if (run) {
+            run.cancelled = true;
+            if (run.timer)
+                clearTimeout(run.timer);
+            this.patterns.delete(deviceId);
+        }
+    }
+    async retry(fn, attempts = 3) {
+        let lastErr;
+        for (let i = 0; i < attempts; i++) {
+            try {
+                await fn();
+                return;
+            }
+            catch (e) {
+                lastErr = e;
+            }
+        }
+        throw new TactusError(`Could not confirm stop after ${attempts} attempts: ${String(lastErr)}`, "DEVICE_ERROR");
+    }
+}
+//# sourceMappingURL=safety.js.map

package/dist/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DeviceController } from "./controller.js";
+import { SafetyLayer } from "./safety.js";
+import { TactusConfig } from "./types.js";
+/** Register every Tactus tool on the given server. */
+export declare function registerTools(server: McpServer, safety: SafetyLayer, controller: DeviceController, config: TactusConfig): void;
+export declare function makeServer(version: string): McpServer;
+/** Server-side hard bounds for patterns — never trust client schema alone (playbook §4). */
+export declare function enforcePatternBounds(steps: readonly {
+    duration_ms: number;
+}[], repeat: number, config: TactusConfig): void;

package/dist/server.js

@@ -0,0 +1,234 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { TactusError } from "./types.js";
+/** Server-level guidance; some clients ignore this, hence the per-tool prefixes too. */
+const INSTRUCTIONS = "Tactus is a content-agnostic hardware control layer. It forwards device " +
+    "control commands only and generates no content. Always confirm a device " +
+    "exists via list_devices before driving it. Intensity is normalized 0.0-1.0. " +
+    "Use stop_all to immediately halt everything.";
+const DRIVE_PREFIX = "[Hardware control] Forwards a command to physical hardware. ";
+const text = (s) => [{ type: "text", text: s }];
+const ok = (message, structured) => ({
+    content: text(message),
+    ...(structured ? { structuredContent: structured } : {}),
+});
+const fail = (e) => {
+    const message = e instanceof TactusError ? e.message : `Unexpected error: ${String(e)}`;
+    return { content: text(message), isError: true };
+};
+const deviceId = z.number().int().nonnegative().describe("Device id from list_devices");
+const unit = (label) => z.number().min(0).max(1).describe(`${label}, 0.0-1.0`);
+const actuatorIndex = z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe("Restrict to one actuator index; omit to drive all matching actuators");
+/** Register every Tactus tool on the given server. */
+export function registerTools(server, safety, controller, config) {
+    // --- discovery / status ---
+    server.registerTool("list_devices", {
+        title: "List devices",
+        description: "List currently connected devices and their actuators.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const devices = controller.listDevices();
+            return ok(`${devices.length} device(s) connected.`, { devices, status: controller.status() });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("server_status", {
+        title: "Server status",
+        description: "Report connection status to Intiface and device count.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok("Status.", { status: controller.status() });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("scan_for_devices", {
+        title: "Scan for devices",
+        description: "Scan for new devices for a duration, then return any newly found.",
+        inputSchema: { duration_ms: z.number().int().positive().optional() },
+    }, async ({ duration_ms }) => {
+        try {
+            const found = await controller.scan(duration_ms ?? config.scanDefaultMs);
+            return ok(`Found ${found.length} new device(s).`, { devices: found });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_battery", {
+        title: "Get battery",
+        description: "Read battery level (0.0-1.0) for a device that reports it.",
+        inputSchema: { device_id: deviceId },
+    }, async ({ device_id }) => {
+        try {
+            const battery = await controller.getBattery(device_id);
+            return ok(`Battery: ${Math.round(battery * 100)}%`, { device_id, battery });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    // --- drive (all clamped + watchdog-tracked via the safety layer) ---
+    server.registerTool("vibrate", {
+        title: "Vibrate",
+        description: DRIVE_PREFIX + "Set vibration intensity on a device.",
+        inputSchema: { device_id: deviceId, intensity: unit("Vibration intensity"), actuator_index: actuatorIndex },
+    }, async ({ device_id, intensity, actuator_index }) => {
+        try {
+            const effective = await safety.vibrate(device_id, intensity, { actuatorIndex: actuator_index });
+            return ok(driveMsg("Vibrating", device_id, intensity, effective), {
+                device_id,
+                intensity: effective,
+                requested: intensity,
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("oscillate", {
+        title: "Oscillate",
+        description: DRIVE_PREFIX + "Set oscillation intensity on a device.",
+        inputSchema: { device_id: deviceId, intensity: unit("Oscillation intensity"), actuator_index: actuatorIndex },
+    }, async ({ device_id, intensity, actuator_index }) => {
+        try {
+            const effective = await safety.oscillate(device_id, intensity, { actuatorIndex: actuator_index });
+            return ok(driveMsg("Oscillating", device_id, intensity, effective), {
+                device_id,
+                intensity: effective,
+                requested: intensity,
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("rotate", {
+        title: "Rotate",
+        description: DRIVE_PREFIX + "Set rotation speed (and direction) on a device.",
+        inputSchema: {
+            device_id: deviceId,
+            speed: unit("Rotation speed"),
+            clockwise: z.boolean().optional().describe("Direction; honored only if the device supports it"),
+            actuator_index: actuatorIndex,
+        },
+    }, async ({ device_id, speed, clockwise, actuator_index }) => {
+        try {
+            const effective = await safety.rotate(device_id, speed, clockwise ?? true, { actuatorIndex: actuator_index });
+            return ok(driveMsg("Rotating", device_id, speed, effective), {
+                device_id,
+                speed: effective,
+                requested: speed,
+                clockwise: clockwise ?? true,
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("linear", {
+        title: "Linear stroke",
+        description: DRIVE_PREFIX + "Move a stroker to a position over a duration.",
+        inputSchema: {
+            device_id: deviceId,
+            position: unit("Target position"),
+            duration_ms: z.number().int().positive().describe("Time to reach the position, ms"),
+            actuator_index: actuatorIndex,
+        },
+    }, async ({ device_id, position, duration_ms, actuator_index }) => {
+        try {
+            const effective = await safety.linear(device_id, position, duration_ms, { actuatorIndex: actuator_index });
+            return ok(`Moving device ${device_id} to ${pct(effective)} over ${duration_ms}ms.`, {
+                device_id,
+                position: effective,
+                duration_ms,
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("vibrate_pattern", {
+        title: "Vibrate pattern",
+        description: DRIVE_PREFIX + "Play a timed multi-step vibration pattern; interruptible by any stop.",
+        inputSchema: {
+            device_id: deviceId,
+            steps: z
+                .array(z.object({ intensity: unit("Step intensity"), duration_ms: z.number().int().positive() }))
+                .min(1),
+            repeat: z.number().int().positive().optional(),
+            actuator_index: actuatorIndex,
+        },
+    }, async ({ device_id, steps, repeat, actuator_index }) => {
+        try {
+            const count = repeat ?? 1;
+            enforcePatternBounds(steps, count, config);
+            const pattern = steps.map((s) => ({ intensity: s.intensity, durationMs: s.duration_ms }));
+            safety.startVibratePattern(device_id, pattern, count, { actuatorIndex: actuator_index });
+            return ok(`Started pattern on device ${device_id} (${steps.length} steps x${count}).`, {
+                device_id,
+                steps: steps.length,
+                repeat: count,
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    // --- stop (always available, never clamped away) ---
+    server.registerTool("stop_device", {
+        title: "Stop device",
+        description: "Stop all actuators on one device.",
+        inputSchema: { device_id: deviceId },
+    }, async ({ device_id }) => {
+        try {
+            await safety.stopDevice(device_id);
+            return ok(`Stopped device ${device_id}.`, { device_id, stopped: true });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("stop_all", {
+        title: "Stop all (emergency)",
+        description: "Immediately stop every connected device. Emergency stop.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            await safety.stopAll();
+            return ok("Stopped all devices.", { stopped: true });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}
+export function makeServer(version) {
+    return new McpServer({ name: "tactus", version }, { instructions: INSTRUCTIONS });
+}
+const pct = (v) => `${Math.round(v * 100)}%`;
+/** Human-readable drive message that notes when the request was clamped. */
+const driveMsg = (verb, deviceId, requested, effective) => effective < requested
+    ? `${verb} device ${deviceId} at ${pct(effective)} (clamped from ${pct(requested)} by MAX_INTENSITY).`
+    : `${verb} device ${deviceId} at ${pct(effective)}.`;
+/** Server-side hard bounds for patterns — never trust client schema alone (playbook §4). */
+export function enforcePatternBounds(steps, repeat, config) {
+    if (steps.length > config.maxPatternSteps) {
+        throw new TactusError(`Pattern has ${steps.length} steps; max is ${config.maxPatternSteps}.`, "INVALID_INPUT");
+    }
+    const total = steps.reduce((sum, s) => sum + s.duration_ms, 0) * repeat;
+    if (total > config.maxContinuousMs) {
+        throw new TactusError(`Pattern total duration ${total}ms exceeds the ${config.maxContinuousMs}ms limit.`, "INVALID_INPUT");
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/** Shared, protocol-agnostic types for Tactus. */
+export type ActuatorType = "vibrate" | "oscillate" | "rotate" | "linear" | "constrict" | "inflate" | "unknown";
+/** A single drivable output on a device (maps to one Buttplug feature output). */
+export interface ActuatorInfo {
+    index: number;
+    type: ActuatorType;
+    /** Number of discrete steps the actuator accepts (from the feature value range). */
+    step_count: number;
+}
+export interface DeviceInfo {
+    id: number;
+    name: string;
+    actuators: ActuatorInfo[];
+    has_battery: boolean;
+    /** 0..1, present only when reported. */
+    battery?: number;
+}
+export interface ServerStatus {
+    connected: boolean;
+    intiface_url: string;
+    server_name?: string;
+    device_count: number;
+}
+export interface TactusConfig {
+    intifaceUrl: string;
+    /** Clamp ceiling for drive intensity, 0..1. */
+    maxIntensity: number;
+    /** Watchdog auto-stop after this many ms of uninterrupted drive. */
+    maxContinuousMs: number;
+    scanDefaultMs: number;
+    /** Per-device command rate cap; excess is coalesced. */
+    maxCommandsPerSec: number;
+    maxPatternSteps: number;
+    /** When true, the intensity clamp is disabled (explicitly gated, discouraged). */
+    allowUnsafe: boolean;
+}
+/** Codes for actionable, non-crashing failures surfaced to callers. */
+export type TactusErrorCode = "NOT_CONNECTED" | "UNKNOWN_DEVICE" | "NO_ACTUATOR" | "INVALID_INPUT" | "DEVICE_ERROR";
+export declare class TactusError extends Error {
+    readonly code: TactusErrorCode;
+    constructor(message: string, code: TactusErrorCode);
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/** Shared, protocol-agnostic types for Tactus. */
+export class TactusError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "TactusError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAyDlD,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGzB;IAFX,YACE,OAAe,EACN,IAAqB;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,SAAI,GAAJ,IAAI,CAAiB;QAG9B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "tactus-mcp",
+  "version": "0.1.1",
+  "description": "A content-agnostic MCP server that exposes intimate hardware control to AI agents by wrapping Buttplug/Intiface.",
+  "type": "module",
+  "bin": {
+    "tactus-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "m0": "tsx src/m0-smoke.ts",
+    "e2e": "tsx src/e2e-probe.ts",
+    "test": "node --import tsx --test test/*.test.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "buttplug",
+    "intiface",
+    "haptics"
+  ],
+  "author": "ProjectAILiberation",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ProjectAILiberation/tactus.git"
+  },
+  "homepage": "https://github.com/ProjectAILiberation/tactus#readme",
+  "bugs": {
+    "url": "https://github.com/ProjectAILiberation/tactus/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "buttplug": "^5.0.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}