@hraness/slopcamera 3.2.4

package/src/mcp/boundary.ts

@@ -0,0 +1,354 @@
+import { open, mkdir, realpath, stat } from "node:fs/promises"
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  win32,
+} from "node:path"
+
+export const mcpSourceByteLimit = 1024 * 1024
+
+export class WorkspaceBoundaryError extends Error {
+  readonly code:
+    | "INVALID_PATH"
+    | "PATH_OUTSIDE_ROOT"
+    | "SOURCE_NOT_FOUND"
+    | "SOURCE_NOT_FILE"
+    | "SOURCE_TOO_LARGE"
+    | "SOURCE_ENCODING"
+    | "OUTPUT_NOT_DIRECTORY"
+    | "FILESYSTEM_ERROR"
+
+  constructor(
+    code: WorkspaceBoundaryError["code"],
+    message: string,
+  ) {
+    super(message)
+    this.name = "WorkspaceBoundaryError"
+    this.code = code
+  }
+}
+
+interface NormalizedRelativePath {
+  readonly native: string
+  readonly portable: string
+}
+
+export interface WorkspaceSource {
+  readonly absolutePath: string
+  readonly relativePath: string
+  readonly text: string
+}
+
+export interface WorkspaceDirectory {
+  readonly absolutePath: string
+  readonly relativePath: string
+}
+
+export interface WorkspaceFile {
+  readonly absolutePath: string
+  readonly relativePath: string
+}
+
+function filesystemCode(error: unknown): string | undefined {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    typeof error.code === "string"
+  ) {
+    return error.code
+  }
+  return undefined
+}
+
+function normalizeRelativePath(
+  value: string,
+  options: { readonly allowRoot: boolean },
+): NormalizedRelativePath {
+  if (value.length === 0 || value.includes("\0")) {
+    throw new WorkspaceBoundaryError("INVALID_PATH", "Path must be a non-empty root-relative path.")
+  }
+  if (
+    isAbsolute(value) ||
+    win32.isAbsolute(value) ||
+    /^[A-Za-z]:/.test(value)
+  ) {
+    throw new WorkspaceBoundaryError("INVALID_PATH", "Absolute paths are not allowed.")
+  }
+  const segments = value
+    .split(/[\\/]/)
+    .filter((segment) => segment !== "" && segment !== ".")
+  if (segments.includes("..")) {
+    throw new WorkspaceBoundaryError("INVALID_PATH", "Parent-directory traversal is not allowed.")
+  }
+  if (segments.length === 0) {
+    if (!options.allowRoot) {
+      throw new WorkspaceBoundaryError("INVALID_PATH", "Path must identify a file below the root.")
+    }
+    return { native: ".", portable: "." }
+  }
+  return {
+    native: segments.join("/"),
+    portable: segments.join("/"),
+  }
+}
+
+function isConfined(rootDirectory: string, target: string): boolean {
+  const fromRoot = relative(rootDirectory, target)
+  return fromRoot === "" || (!fromRoot.startsWith("..") && !isAbsolute(fromRoot))
+}
+
+async function readUtf8WithCap(filePath: string): Promise<string> {
+  let handle
+  try {
+    handle = await open(filePath, "r")
+    const metadata = await handle.stat()
+    if (!metadata.isFile()) {
+      throw new WorkspaceBoundaryError(
+        "SOURCE_NOT_FILE",
+        "Diagram source must be a regular file.",
+      )
+    }
+    if (metadata.size > mcpSourceByteLimit) {
+      throw new WorkspaceBoundaryError(
+        "SOURCE_TOO_LARGE",
+        `Diagram source exceeds the ${mcpSourceByteLimit}-byte limit.`,
+      )
+    }
+
+    const buffer = Buffer.allocUnsafe(mcpSourceByteLimit + 1)
+    let bytesRead = 0
+    while (bytesRead <= mcpSourceByteLimit) {
+      const next = await handle.read(
+        buffer,
+        bytesRead,
+        mcpSourceByteLimit + 1 - bytesRead,
+        null,
+      )
+      if (next.bytesRead === 0) break
+      bytesRead += next.bytesRead
+    }
+    if (bytesRead > mcpSourceByteLimit) {
+      throw new WorkspaceBoundaryError(
+        "SOURCE_TOO_LARGE",
+        `Diagram source exceeds the ${mcpSourceByteLimit}-byte limit.`,
+      )
+    }
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(
+        buffer.subarray(0, bytesRead),
+      )
+    } catch {
+      throw new WorkspaceBoundaryError(
+        "SOURCE_ENCODING",
+        "Diagram source must contain valid UTF-8.",
+      )
+    }
+  } catch (error) {
+    if (error instanceof WorkspaceBoundaryError) throw error
+    const code = filesystemCode(error)
+    if (code === "ENOENT") {
+      throw new WorkspaceBoundaryError("SOURCE_NOT_FOUND", "Diagram source does not exist.")
+    }
+    throw new WorkspaceBoundaryError("FILESYSTEM_ERROR", "Diagram source could not be read.")
+  } finally {
+    await handle?.close()
+  }
+}
+
+export class WorkspaceBoundary {
+  readonly rootDirectory: string
+
+  private constructor(rootDirectory: string) {
+    this.rootDirectory = rootDirectory
+  }
+
+  static async create(rootDirectory: string): Promise<WorkspaceBoundary> {
+    let resolvedRoot: string
+    try {
+      resolvedRoot = await realpath(resolve(rootDirectory))
+      if (!(await stat(resolvedRoot)).isDirectory()) {
+        throw new WorkspaceBoundaryError(
+          "OUTPUT_NOT_DIRECTORY",
+          "MCP root must be a directory.",
+        )
+      }
+    } catch (error) {
+      if (error instanceof WorkspaceBoundaryError) throw error
+      throw new WorkspaceBoundaryError(
+        "FILESYSTEM_ERROR",
+        "MCP root could not be opened.",
+      )
+    }
+    return new WorkspaceBoundary(resolvedRoot)
+  }
+
+  private assertConfined(target: string): void {
+    if (!isConfined(this.rootDirectory, target)) {
+      throw new WorkspaceBoundaryError(
+        "PATH_OUTSIDE_ROOT",
+        "Path resolves outside the MCP root.",
+      )
+    }
+  }
+
+  toRelativePath(absolutePath: string): string {
+    this.assertConfined(absolutePath)
+    const fromRoot = relative(this.rootDirectory, absolutePath)
+    return fromRoot === "" ? "." : fromRoot.split("\\").join("/")
+  }
+
+  async readSource(value: string): Promise<WorkspaceSource> {
+    const normalized = normalizeRelativePath(value, { allowRoot: false })
+    const lexicalPath = resolve(this.rootDirectory, normalized.native)
+    this.assertConfined(lexicalPath)
+
+    let canonicalPath: string
+    try {
+      canonicalPath = await realpath(lexicalPath)
+    } catch (error) {
+      if (filesystemCode(error) === "ENOENT") {
+        throw new WorkspaceBoundaryError(
+          "SOURCE_NOT_FOUND",
+          "Diagram source does not exist.",
+        )
+      }
+      throw new WorkspaceBoundaryError(
+        "FILESYSTEM_ERROR",
+        "Diagram source could not be resolved.",
+      )
+    }
+    this.assertConfined(canonicalPath)
+    return {
+      absolutePath: canonicalPath,
+      relativePath: this.toRelativePath(canonicalPath),
+      text: await readUtf8WithCap(canonicalPath),
+    }
+  }
+
+  async resolveInputFile(
+    value: string,
+    maximumBytes: number,
+  ): Promise<WorkspaceFile> {
+    const normalized = normalizeRelativePath(value, { allowRoot: false })
+    const lexicalPath = resolve(this.rootDirectory, normalized.native)
+    this.assertConfined(lexicalPath)
+    let canonicalPath: string
+    try {
+      canonicalPath = await realpath(lexicalPath)
+      this.assertConfined(canonicalPath)
+      const metadata = await stat(canonicalPath)
+      if (!metadata.isFile()) {
+        throw new WorkspaceBoundaryError(
+          "SOURCE_NOT_FILE",
+          "Input must be a regular file.",
+        )
+      }
+      if (
+        !Number.isSafeInteger(maximumBytes) ||
+        maximumBytes < 1 ||
+        metadata.size > maximumBytes
+      ) {
+        throw new WorkspaceBoundaryError(
+          "SOURCE_TOO_LARGE",
+          `Input exceeds the ${maximumBytes}-byte limit.`,
+        )
+      }
+    } catch (error) {
+      if (error instanceof WorkspaceBoundaryError) throw error
+      if (filesystemCode(error) === "ENOENT") {
+        throw new WorkspaceBoundaryError(
+          "SOURCE_NOT_FOUND",
+          "Input does not exist.",
+        )
+      }
+      throw new WorkspaceBoundaryError(
+        "FILESYSTEM_ERROR",
+        "Input could not be resolved.",
+      )
+    }
+    return {
+      absolutePath: canonicalPath,
+      relativePath: this.toRelativePath(canonicalPath),
+    }
+  }
+
+  async prepareOutputFile(value: string): Promise<WorkspaceFile> {
+    const normalized = normalizeRelativePath(value, { allowRoot: false })
+    const fileName = basename(normalized.native)
+    if (fileName === "." || fileName === ".." || fileName.length === 0) {
+      throw new WorkspaceBoundaryError(
+        "INVALID_PATH",
+        "Output path must identify a file below the root.",
+      )
+    }
+    const directory = await this.prepareOutputDirectory(
+      dirname(normalized.native),
+    )
+    const absolutePath = join(directory.absolutePath, fileName)
+    this.assertConfined(absolutePath)
+    return {
+      absolutePath,
+      relativePath: this.toRelativePath(absolutePath),
+    }
+  }
+
+  async prepareOutputDirectory(value: string): Promise<WorkspaceDirectory> {
+    const normalized = normalizeRelativePath(value, { allowRoot: true })
+    const lexicalPath = resolve(this.rootDirectory, normalized.native)
+    this.assertConfined(lexicalPath)
+
+    // Resolve the nearest existing ancestor before mkdir so a symlink in the
+    // requested path cannot redirect writes outside the server root.
+    let ancestor = lexicalPath
+    for (;;) {
+      try {
+        const canonicalAncestor = await realpath(ancestor)
+        this.assertConfined(canonicalAncestor)
+        break
+      } catch (error) {
+        if (error instanceof WorkspaceBoundaryError) throw error
+        if (filesystemCode(error) !== "ENOENT") {
+          throw new WorkspaceBoundaryError(
+            "FILESYSTEM_ERROR",
+            "Output directory could not be resolved.",
+          )
+        }
+        const parent = dirname(ancestor)
+        if (parent === ancestor) {
+          throw new WorkspaceBoundaryError(
+            "PATH_OUTSIDE_ROOT",
+            "Output directory resolves outside the MCP root.",
+          )
+        }
+        ancestor = parent
+      }
+    }
+
+    try {
+      await mkdir(lexicalPath, { recursive: true })
+      const canonicalPath = await realpath(lexicalPath)
+      this.assertConfined(canonicalPath)
+      if (!(await stat(canonicalPath)).isDirectory()) {
+        throw new WorkspaceBoundaryError(
+          "OUTPUT_NOT_DIRECTORY",
+          "Output path must be a directory.",
+        )
+      }
+      return {
+        absolutePath: canonicalPath,
+        relativePath: this.toRelativePath(canonicalPath),
+      }
+    } catch (error) {
+      if (error instanceof WorkspaceBoundaryError) throw error
+      throw new WorkspaceBoundaryError(
+        "FILESYSTEM_ERROR",
+        "Output directory could not be created.",
+      )
+    }
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,33 @@
+export {
+  slopcameraMcpProtocolVersion,
+  slopcameraMcpServerName,
+  runMcpServer,
+} from "./server.js"
+export {
+  slopcameraMcpTools,
+  SlopcameraMcpToolRuntime,
+  mcpMaximumEdges,
+  mcpMaximumRenderedPixels,
+  mcpMaximumReturnedFindings,
+  mcpMaximumScale,
+  mcpMaximumShapes,
+} from "./tools.js"
+export {
+  mcpSourceByteLimit,
+  WorkspaceBoundary,
+  WorkspaceBoundaryError,
+  type WorkspaceDirectory,
+  type WorkspaceFile,
+  type WorkspaceSource,
+} from "./boundary.js"
+export type {
+  JsonRpcFailure,
+  JsonRpcId,
+  JsonRpcResponseId,
+  JsonRpcResponse,
+  JsonRpcSuccess,
+  McpServerOptions,
+  McpTextContent,
+  McpToolDefinition,
+  McpToolResult,
+} from "./types.js"

package/src/mcp/server.ts

@@ -0,0 +1,272 @@
+import {
+  slopcameraMcpTools,
+  SlopcameraMcpToolRuntime,
+} from "./tools.js"
+import type {
+  JsonRpcId,
+  JsonRpcResponse,
+  JsonRpcResponseId,
+  McpServerOptions,
+} from "./types.js"
+import { SLOPCAMERA_VERSION } from "../version.js"
+
+export const slopcameraMcpProtocolVersion = "2025-11-25"
+export const slopcameraMcpServerName = "hraness-slopcamera"
+
+const maximumMessageBytes = 1024 * 1024
+
+interface RequestRecord {
+  readonly jsonrpc: "2.0"
+  readonly id?: JsonRpcId
+  readonly method: string
+  readonly params?: unknown
+}
+
+type LifecycleState = "new" | "initializing" | "ready"
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isJsonRpcId(value: unknown): value is JsonRpcId {
+  return (
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isSafeInteger(value))
+  )
+}
+
+function isInitializeParams(value: unknown): value is Readonly<{
+  protocolVersion: string
+  capabilities: Readonly<Record<string, unknown>>
+  clientInfo: Readonly<{ name: string; version: string }>
+}> {
+  return (
+    isRecord(value) &&
+    typeof value.protocolVersion === "string" &&
+    isRecord(value.capabilities) &&
+    isRecord(value.clientInfo) &&
+    typeof value.clientInfo.name === "string" &&
+    typeof value.clientInfo.version === "string"
+  )
+}
+
+function parseRequest(value: unknown): RequestRecord {
+  if (
+    !isRecord(value) ||
+    value.jsonrpc !== "2.0" ||
+    typeof value.method !== "string" ||
+    value.method.length === 0 ||
+    ("id" in value && !isJsonRpcId(value.id))
+  ) {
+    throw new Error("invalid request")
+  }
+  return {
+    jsonrpc: "2.0",
+    ...("id" in value ? { id: value.id as JsonRpcId } : {}),
+    method: value.method,
+    ...("params" in value ? { params: value.params } : {}),
+  }
+}
+
+function success(id: JsonRpcId, result: unknown): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result }
+}
+
+function failure(
+  id: JsonRpcResponseId,
+  code: number,
+  message: string,
+): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message } }
+}
+
+function parseToolCall(
+  params: unknown,
+): { readonly name: string; readonly argumentsValue: unknown } {
+  if (
+    !isRecord(params) ||
+    typeof params.name !== "string" ||
+    (params.arguments !== undefined && !isRecord(params.arguments))
+  ) {
+    throw new Error("invalid params")
+  }
+  const unknownKeys = Object.keys(params).filter(
+    (key) => key !== "name" && key !== "arguments",
+  )
+  if (unknownKeys.length > 0) throw new Error("invalid params")
+  return {
+    name: params.name,
+    argumentsValue: params.arguments ?? {},
+  }
+}
+
+class SlopcameraMcpSession {
+  readonly runtime: SlopcameraMcpToolRuntime
+  readonly serverVersion: string
+  state: LifecycleState = "new"
+
+  constructor(runtime: SlopcameraMcpToolRuntime, serverVersion: string) {
+    this.runtime = runtime
+    this.serverVersion = serverVersion
+  }
+
+  async handle(value: unknown): Promise<JsonRpcResponse | null> {
+    let request: RequestRecord
+    try {
+      request = parseRequest(value)
+    } catch {
+      return failure(null, -32600, "Invalid Request")
+    }
+
+    const notification = request.id === undefined
+    if (request.method === "notifications/initialized") {
+      if (!notification) {
+        return failure(request.id!, -32600, "Invalid Request")
+      }
+      if (this.state === "initializing") this.state = "ready"
+      return null
+    }
+    if (notification) return null
+    const id = request.id!
+
+    if (request.method === "initialize") {
+      if (this.state !== "new" || !isInitializeParams(request.params)) {
+        return failure(id, -32602, "Invalid initialize parameters")
+      }
+      this.state = "initializing"
+      return success(id, {
+        protocolVersion: slopcameraMcpProtocolVersion,
+        capabilities: {
+          tools: { listChanged: false },
+        },
+        serverInfo: {
+          name: slopcameraMcpServerName,
+          version: this.serverVersion,
+        },
+        instructions:
+          "Use check_diagram/render_diagram or search_slopcamera followed by execute_slopcamera with an exact registry code and typed JSON. Local paths are root-relative; source code is never accepted or evaluated.",
+      })
+    }
+
+    if (this.state !== "ready") {
+      return failure(id, -32002, "Server is not initialized")
+    }
+    if (request.method === "ping") return success(id, {})
+    if (request.method === "tools/list") {
+      if (
+        request.params !== undefined &&
+        (!isRecord(request.params) || Object.keys(request.params).length > 0)
+      ) {
+        return failure(id, -32602, "Invalid tools/list parameters")
+      }
+      return success(id, { tools: slopcameraMcpTools })
+    }
+    if (request.method === "tools/call") {
+      try {
+        const toolCall = parseToolCall(request.params)
+        if (!slopcameraMcpTools.some((tool) => tool.name === toolCall.name)) {
+          return failure(id, -32602, "Unknown tool")
+        }
+        return success(
+          id,
+          await this.runtime.call(toolCall.name, toolCall.argumentsValue),
+        )
+      } catch {
+        return failure(id, -32602, "Invalid tools/call parameters")
+      }
+    }
+    return failure(id, -32601, "Method not found")
+  }
+}
+
+async function defaultWriteLine(line: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    process.stdout.write(`${line}\n`, (error) => {
+      if (error === null || error === undefined) resolve()
+      else reject(error)
+    })
+  })
+}
+
+function defaultInput(): AsyncIterable<Uint8Array> {
+  return process.stdin
+}
+
+async function emitResponse(
+  writeLine: (line: string) => void | Promise<void>,
+  response: JsonRpcResponse,
+): Promise<void> {
+  await writeLine(JSON.stringify(response))
+}
+
+async function processLine(
+  line: Uint8Array,
+  session: SlopcameraMcpSession,
+  writeLine: (line: string) => void | Promise<void>,
+): Promise<void> {
+  if (line.byteLength === 0) return
+  let value: unknown
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(line)
+    if (text.trim() === "") return
+    value = JSON.parse(text)
+  } catch {
+    await emitResponse(writeLine, failure(null, -32700, "Parse error"))
+    return
+  }
+  if (Array.isArray(value)) {
+    await emitResponse(writeLine, failure(null, -32600, "Invalid Request"))
+    return
+  }
+  const response = await session.handle(value)
+  if (response !== null) await emitResponse(writeLine, response)
+}
+
+/**
+ * Run one newline-delimited JSON-RPC MCP session. Protocol output is the only
+ * stdout surface; callers that need logs must write them to stderr.
+ */
+export async function runMcpServer(
+  options: McpServerOptions = {},
+): Promise<void> {
+  const runtime = await SlopcameraMcpToolRuntime.create(
+    options.rootDirectory ?? process.cwd(),
+    options.generateDependencies,
+  )
+  const session = new SlopcameraMcpSession(
+    runtime,
+    options.serverVersion ?? SLOPCAMERA_VERSION,
+  )
+  const writeLine = options.writeLine ?? defaultWriteLine
+  let buffered = Buffer.alloc(0)
+
+  for await (const chunk of options.input ?? defaultInput()) {
+    const bytes =
+      typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk)
+    buffered = Buffer.concat([buffered, bytes])
+    if (buffered.byteLength > maximumMessageBytes && !buffered.includes(0x0a)) {
+      buffered = Buffer.alloc(0)
+      await emitResponse(writeLine, failure(null, -32700, "Parse error"))
+      continue
+    }
+    for (;;) {
+      const newline = buffered.indexOf(0x0a)
+      if (newline === -1) break
+      let line = buffered.subarray(0, newline)
+      buffered = buffered.subarray(newline + 1)
+      if (line.at(-1) === 0x0d) line = line.subarray(0, -1)
+      if (line.byteLength > maximumMessageBytes) {
+        await emitResponse(writeLine, failure(null, -32700, "Parse error"))
+      } else {
+        await processLine(line, session, writeLine)
+      }
+    }
+  }
+  if (buffered.byteLength > 0) {
+    if (buffered.byteLength > maximumMessageBytes) {
+      await emitResponse(writeLine, failure(null, -32700, "Parse error"))
+    } else {
+      await processLine(buffered, session, writeLine)
+    }
+  }
+}