@volcanic-dev/tephra 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# Tephra
+
+**A clipboard for AI agents.** Tephra is an MCP server that lets a model copy an exact character range from a file — start `(line, char)` to end `(line, char)` — and paste it at an exact position somewhere else. Byte-for-byte, no retyping, no transcription drift, no tokens spent regenerating code that already exists.
+
+The clipboard is a **private in-process buffer, deliberately not the OS clipboard**. An agent can never read what you last copied (passwords, tokens, anything) and can never overwrite what you're about to paste. Nothing touches disk; the buffer dies with the session.
+
+## Install
+
+```sh
+# Claude Code
+claude mcp add tephra -- npx -y @volcanic-dev/tephra
+
+# or any MCP client (stdio transport)
+npx -y @volcanic-dev/tephra
+```
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `copy` | Copy `(start_line, start_char)` → `(end_line, end_char)` from a file to the clipboard. Both ends inclusive, 1-indexed. Newlines inside the range are included. |
+| `cut` | Same as `copy`, but removes the range from the source file. |
+| `paste` | Insert the clipboard into a file before the character at `(line, char)`. `char` may be line length + 1 to append to a line. Never overwrites — text shifts to make room. |
+| `peek` | Show the clipboard's current size and a preview. |
+
+## Addressing
+
+- Lines and characters are **1-indexed**: the first character of a file is `(1, 1)`.
+- Copy/cut ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
+- To copy whole lines 10–14: start `(10, 1)`, end `(14, <length of line 14>)`.
+- A file ending in a newline has an addressable empty final line, so appending at end-of-file is `paste` at `(lastLine, 1)`.
+- Out-of-range positions return the line's real length and a preview of it, so an agent can self-correct in one step.
+
+## Requirements
+
+Node ≥ 18. No native dependencies, no OS clipboard backends — the buffer lives in the server process.
+
+---
+
+Part of [Volcanic](https://volcanic.dev/tephra).

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@volcanic-dev/tephra",
+  "version": "0.1.0",
+  "description": "MCP server that gives AI agents a clipboard of their own: copy an exact line:char range from a file, paste it anywhere — byte-for-byte, without touching the OS clipboard.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "tephra": "server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "clipboard",
+    "copy-paste",
+    "ai-agents"
+  ],
+  "author": "Volcanic <noreply@volcanic.dev>",
+  "homepage": "https://volcanic.dev/tephra",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  }
+}

package/server.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// @tephra-server
+// Tephra — an MCP server that gives AI agents a clipboard of their own.
+//
+// Models are bad at retyping: moving 80 lines of code by regenerating them
+// invites transcription drift and burns tokens. Tephra lets an agent name an
+// exact range — start (line, char) to end (line, char), both 1-indexed and
+// inclusive — copy it byte-for-byte, and paste it at an exact position in
+// another file.
+//
+// The clipboard is a private in-process buffer, deliberately NOT the OS
+// clipboard: an agent must not be able to read whatever the human last
+// copied (passwords, tokens) or overwrite what they're about to paste.
+// Nothing is written to disk; the buffer dies with the session.
+//
+// Tools: copy, cut, paste, peek.
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+// @tephra-buffer — the private clipboard; in-memory only, per-session
+let clipboard = ''
+
+// @tephra-positions — 1-indexed (line, char) ↔ absolute offset math
+// indexLines keeps a trailing empty line when the file ends with \n, so
+// "append at end of file" is addressable as (lastLine, 1).
+function indexLines(text) {
+  const lines = []
+  let start = 0
+  for (let i = 0; i <= text.length; i++) {
+    if (i === text.length || text[i] === '\n') {
+      let contentEnd = i
+      if (contentEnd > start && text[contentEnd - 1] === '\r') contentEnd--
+      lines.push({ start, contentEnd })
+      start = i + 1
+    }
+  }
+  return lines
+}
+
+class PositionError extends Error {}
+
+function lineAt(lines, line, label) {
+  if (!Number.isInteger(line) || line < 1 || line > lines.length) {
+    throw new PositionError(`${label}: line ${line} is out of range — the file has ${lines.length} line${lines.length === 1 ? '' : 's'}.`)
+  }
+  return lines[line - 1]
+}
+
+// charOffset: char 1 = first character of the line. maxExtra=0 for copy/cut
+// anchors (must land on a real character); maxExtra=1 for paste (char may be
+// lineLength+1, meaning "after the last character, before the newline").
+function charOffset(text, lines, line, char, label, maxExtra) {
+  const L = lineAt(lines, line, label)
+  const len = L.contentEnd - L.start
+  const max = len + maxExtra
+  if (!Number.isInteger(char) || char < 1 || char > max) {
+    const preview = text.slice(L.start, L.contentEnd)
+    const shown = preview.length > 80 ? `${preview.slice(0, 80)}…` : preview
+    throw new PositionError(
+      `${label}: char ${char} is out of range on line ${line}, which has ${len} character${len === 1 ? '' : 's'}` +
+      (maxExtra ? ` (valid: 1–${max}, where ${max} means end of line)` : ` (valid: 1–${Math.max(max, 1)})`) +
+      `. Line ${line} is: "${shown}"`,
+    )
+  }
+  return L.start + (char - 1)
+}
+
+// @tephra-preview — head/tail preview so results stay small even for big copies
+function preview(text) {
+  if (text.length <= 300) return text
+  return `${text.slice(0, 200)}\n… [${text.length - 300} chars omitted] …\n${text.slice(-100)}`
+}
+
+function describe(text) {
+  const lines = text.length === 0 ? 0 : text.split('\n').length
+  return `${text.length} chars, ${lines} line${lines === 1 ? '' : 's'}`
+}
+
+// endPosition: (line, char) of the character right after `text` inserted at (line, char)
+function endPosition(startLine, startChar, text) {
+  const parts = text.split('\n')
+  if (parts.length === 1) return { line: startLine, char: startChar + text.length }
+  return { line: startLine + parts.length - 1, char: parts[parts.length - 1].length + 1 }
+}
+
+// @tephra-extract — shared range extraction for copy/cut
+async function extractRange(file, startLine, startChar, endLine, endChar) {
+  const text = await readFile(file, 'utf8')
+  const lines = indexLines(text)
+  const startOff = charOffset(text, lines, startLine, startChar, 'start', 0)
+  const endOff = charOffset(text, lines, endLine, endChar, 'end', 0)
+  if (endOff < startOff) {
+    throw new PositionError(`The end position (line ${endLine}, char ${endChar}) comes before the start position (line ${startLine}, char ${startChar}).`)
+  }
+  return { text, startOff, endOff: endOff + 1 } // end is inclusive
+}
+
+function ok(message) {
+  return { content: [{ type: 'text', text: message }] }
+}
+
+function fail(message) {
+  return { content: [{ type: 'text', text: message }], isError: true }
+}
+
+async function guarded(fn) {
+  try {
+    return await fn()
+  } catch (e) {
+    return fail(e instanceof PositionError ? e.message : `Error: ${e.message}`)
+  }
+}
+
+// @tephra-tools
+const server = new McpServer({ name: 'tephra', version: '0.1.0' })
+
+const rangeSchema = {
+  file: z.string().describe('Absolute path of the file to copy from'),
+  start_line: z.number().int().describe('Line of the first character to copy (1-indexed)'),
+  start_char: z.number().int().describe('Character position on start_line of the first character to copy (1-indexed)'),
+  end_line: z.number().int().describe('Line of the last character to copy (1-indexed, inclusive)'),
+  end_char: z.number().int().describe('Character position on end_line of the last character to copy (1-indexed, inclusive)'),
+}
+
+server.registerTool(
+  'copy',
+  {
+    title: 'Copy range to clipboard',
+    description:
+      "Copy an exact character range from a file to Tephra's clipboard, byte-for-byte. " +
+      'The range runs from (start_line, start_char) through (end_line, end_char), inclusive on both ends; ' +
+      'newlines inside the range are included. Use this instead of retyping text you intend to move or duplicate. ' +
+      'The clipboard is private to this session, not the operating system clipboard.',
+    inputSchema: rangeSchema,
+  },
+  async ({ file, start_line, start_char, end_line, end_char }) =>
+    guarded(async () => {
+      const { text, startOff, endOff } = await extractRange(file, start_line, start_char, end_line, end_char)
+      const snippet = text.slice(startOff, endOff)
+      clipboard = snippet
+      return ok(`Copied ${describe(snippet)} from ${file} (${start_line}:${start_char} → ${end_line}:${end_char}) to the clipboard.\n\nPreview:\n${preview(snippet)}`)
+    }),
+)
+
+server.registerTool(
+  'cut',
+  {
+    title: 'Cut range to clipboard',
+    description:
+      'Same as copy, but also removes the range from the source file. ' +
+      'The range is inclusive on both ends. The file is written back immediately.',
+    inputSchema: rangeSchema,
+  },
+  async ({ file, start_line, start_char, end_line, end_char }) =>
+    guarded(async () => {
+      const { text, startOff, endOff } = await extractRange(file, start_line, start_char, end_line, end_char)
+      const snippet = text.slice(startOff, endOff)
+      clipboard = snippet
+      await writeFile(file, text.slice(0, startOff) + text.slice(endOff), 'utf8')
+      return ok(`Cut ${describe(snippet)} from ${file} (${start_line}:${start_char} → ${end_line}:${end_char}) to the clipboard. The file has been updated.\n\nPreview:\n${preview(snippet)}`)
+    }),
+)
+
+server.registerTool(
+  'paste',
+  {
+    title: 'Paste clipboard into file',
+    description:
+      "Insert Tephra's clipboard contents into a file at an exact position. " +
+      'The clipboard text is inserted before the character at (line, char); char may be one past the end of the line to append to it. ' +
+      'Existing text is never overwritten — it shifts to make room.',
+    inputSchema: {
+      file: z.string().describe('Absolute path of the file to paste into'),
+      line: z.number().int().describe('Line to paste at (1-indexed)'),
+      char: z.number().int().describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line)'),
+    },
+  },
+  async ({ file, line, char }) =>
+    guarded(async () => {
+      const clip = clipboard
+      if (clip.length === 0) return fail('The clipboard is empty — nothing to paste. Use copy or cut first.')
+      const text = await readFile(file, 'utf8')
+      const lines = indexLines(text)
+      const off = charOffset(text, lines, line, char, 'paste position', 1)
+      await writeFile(file, text.slice(0, off) + clip + text.slice(off), 'utf8')
+      const end = endPosition(line, char, clip)
+      return ok(`Pasted ${describe(clip)} into ${file} at ${line}:${char}. The inserted text now spans ${line}:${char} → ${end.line}:${end.char} (exclusive end).\n\nPreview:\n${preview(clip)}`)
+    }),
+)
+
+server.registerTool(
+  'peek',
+  {
+    title: 'Peek at clipboard',
+    description: "Show what is currently on Tephra's clipboard (size and a preview) without modifying anything.",
+    inputSchema: {},
+  },
+  async () =>
+    guarded(async () => {
+      if (clipboard.length === 0) return ok('The clipboard is empty.')
+      return ok(`Clipboard holds ${describe(clipboard)}.\n\nPreview:\n${preview(clipboard)}`)
+    }),
+)
+
+// @tephra-main
+const transport = new StdioServerTransport()
+await server.connect(transport)