@agentcairn/mcp-server 0.0.0-stage → 0.1.0

package/ui/js/store.js

@@ -0,0 +1,77 @@
+import { api } from './api.js'
+
+/**
+ * The live connection to the server: recent events, rolling stats, and a
+ * server-sent stream that keeps both current. Views subscribe and re-draw.
+ */
+const MAX_EVENTS = 500
+
+export const live = {
+  status: 'idle', // idle | connecting | live | down
+  stats: null,
+  events: [],
+  listeners: new Set(),
+  source: null,
+
+  subscribe(fn) {
+    this.listeners.add(fn)
+    return () => this.listeners.delete(fn)
+  },
+
+  emit(kind, payload) {
+    for (const fn of this.listeners) {
+      try {
+        fn(kind, payload)
+      } catch (error) {
+        console.error('live listener failed', error)
+      }
+    }
+  },
+
+  async start() {
+    if (this.source) return
+    this.status = 'connecting'
+    this.emit('status')
+    await this.backfill()
+    const source = new EventSource('/admin/api/stream')
+    this.source = source
+    source.addEventListener('open', () => {
+      this.status = 'live'
+      this.emit('status')
+    })
+    source.addEventListener('error', () => {
+      this.status = source.readyState === EventSource.CLOSED ? 'down' : 'connecting'
+      this.emit('status')
+    })
+    source.addEventListener('stats', e => {
+      this.stats = JSON.parse(e.data)
+      this.emit('stats', this.stats)
+    })
+    source.addEventListener('event', e => {
+      const event = JSON.parse(e.data)
+      if (this.events.some(x => x.id === event.id)) return
+      this.events.unshift(event)
+      if (this.events.length > MAX_EVENTS) this.events.length = MAX_EVENTS
+      this.emit('event', event)
+    })
+  },
+
+  async backfill() {
+    try {
+      const { events } = await api('events?limit=300')
+      const known = new Set(this.events.map(e => e.id))
+      this.events = [...this.events, ...events.filter(e => !known.has(e.id))].sort((a, b) => b.id - a.id).slice(0, MAX_EVENTS)
+    } catch {
+      // the stream will still deliver new events
+    }
+  },
+
+  stop() {
+    this.source?.close()
+    this.source = null
+    this.status = 'idle'
+    this.stats = null
+    this.events = []
+    this.emit('status')
+  },
+}

package/ui/js/views/access.js

@@ -0,0 +1,129 @@
+import { api } from '../api.js'
+import { ago, codeBox, copyText, emptyState, h, icon, toast } from '../dom.js'
+
+export async function mount(container, { query }) {
+  const [{ projects }, tokensReply] = await Promise.all([api('projects'), api('tokens')])
+  let tokens = tokensReply.tokens
+  let fresh = null // the token just created, kept only in this page's memory
+  let method = 'claude'
+
+  const tokenCard = h('div', { class: 'card flush' })
+  const connectCard = h('div', { class: 'card' })
+  const secretBox = h('div')
+
+  // ---- tokens --------------------------------------------------------------
+  const nameInput = h('input', { class: 'input', placeholder: 'Name, e.g. laptop or ci-runner', maxlength: '60', 'aria-label': 'Token name', style: { width: '250px' } })
+  const createBtn = h('button', { class: 'btn primary', type: 'button' }, icon('plus'), 'Create token')
+
+  async function create() {
+    createBtn.disabled = true
+    try {
+      const made = await api('tokens', { body: { name: nameInput.value } })
+      fresh = made.token
+      nameInput.value = ''
+      tokens = (await api('tokens')).tokens
+      secretBox.replaceChildren(
+        h(
+          'div',
+          { class: 'callout warn stack', style: { gap: '10px', margin: '0 18px 16px' } },
+          h('b', null, `Token "${made.info.name}" created. Copy it now: it is shown only once.`),
+          h('div', { class: 'secret' }, made.token),
+          h('div', { class: 'row' }, h('button', { class: 'btn', type: 'button', onclick: () => copyText(made.token, 'Token copied') }, icon('copy'), 'Copy token'), h('span', { class: 'hint' }, 'Only a hash is stored on the server.')),
+        ),
+      )
+      drawTokens()
+      drawConnect()
+    } catch (error) {
+      toast(error.message)
+    } finally {
+      createBtn.disabled = false
+    }
+  }
+  createBtn.addEventListener('click', create)
+  nameInput.addEventListener('keydown', e => e.key === 'Enter' && create())
+
+  async function revoke(t) {
+    if (!confirm(`Revoke "${t.name}"? Anything using it stops working immediately.`)) return
+    try {
+      await api(`tokens/${t.id}`, { method: 'DELETE' })
+      tokens = (await api('tokens')).tokens
+      drawTokens()
+    } catch (error) {
+      toast(error.message)
+    }
+  }
+
+  function drawTokens() {
+    const active = tokens.filter(t => !t.revokedAt)
+    tokenCard.replaceChildren(
+      h('div', { class: 'head' }, h('div', null, h('h2', null, 'Access tokens'), h('div', { class: 'hint' }, `${active.length} active · agents and the cairn CLI send one as a bearer token`)), h('div', { class: 'tools' }, nameInput, createBtn)),
+      secretBox,
+      tokens.length
+        ? h('div', { class: 'scroll', style: { maxHeight: '340px' } }, h('table', { class: 'tbl' }, h('thead', null, h('tr', null, ['Name', 'Token', 'Created', 'Last used', 'Status', ''].map(t => h('th', null, t)))),
+            h('tbody', null, tokens.map(t => h('tr', { style: { opacity: t.revokedAt ? 0.55 : 1 } },
+              h('td', null, h('span', { class: 'tool-name' }, t.name)),
+              h('td', { class: 'mono' }, `${t.prefix}…`),
+              h('td', null, ago(t.createdAt), t.createdBy && h('span', { class: 'sub' }, `by ${t.createdBy}`)),
+              h('td', null, t.lastUsedAt ? ago(t.lastUsedAt) : h('span', { class: 'muted' }, 'never')),
+              h('td', null, t.revokedAt ? h('span', { class: 'badge err' }, icon('x'), 'revoked') : h('span', { class: 'badge ok' }, icon('check'), 'active')),
+              h('td', { class: 'num' }, !t.revokedAt && h('button', { class: 'btn sm danger', type: 'button', onclick: () => revoke(t) }, icon('trash'), 'Revoke')),
+            )))))
+        : emptyState('key', 'No tokens yet', 'Create one, then connect an agent below.'),
+      tokens.length > 0 && active.length === 0 && h('div', { class: 'hint', style: { padding: '0 18px 16px' } }, 'All tokens are revoked: agents cannot connect until you create a new one.'),
+    )
+  }
+
+  // ---- connect -------------------------------------------------------------
+  const origin = h('input', { class: 'input mono', value: location.origin, 'aria-label': 'Server address', style: { width: '280px' } })
+  const projectSelect = h('select', { 'aria-label': 'Project' }, projects.map(p => h('option', { value: p.id }, p.id)), h('option', { value: '' }, 'A new project id…'))
+  const customProject = h('input', { class: 'input', placeholder: 'project-id', 'aria-label': 'Project id', style: { display: 'none', width: '160px' } })
+  if (query.project) projectSelect.value = query.project
+  else if (!projects.length) projectSelect.value = ''
+  projectSelect.addEventListener('change', () => {
+    customProject.style.display = projectSelect.value === '' ? '' : 'none'
+    drawConnect()
+  })
+  for (const el of [origin, customProject]) el.addEventListener('input', drawConnect)
+
+  const METHODS = [
+    ['claude', 'Claude Code', 'One command, once per machine. It works in every folder: the project comes from .cairn.json or the git remote. Needs Node 20+.'],
+    ['http', 'Direct HTTP', 'No Node needed. Run it inside the project folder; the project header tells the server which brain to use.'],
+    ['mcp', '.mcp.json', 'Commit this with the repo. Each person sets CAIRN_URL and CAIRN_TOKEN in their environment, so no secret is committed.'],
+    ['cli', 'cairn CLI', 'Also installs the Claude Code hooks (briefing at session start, checkpoint reminder) and a CLAUDE.md block.'],
+    ['check', 'Check it', 'Two requests: the server is up and can reach Neo4j, and your token and project are accepted.'],
+  ]
+
+  function drawConnect() {
+    const base = origin.value.replace(/\/+$/, '')
+    const project = projectSelect.value || customProject.value.trim() || 'my-project'
+    const token = fresh ?? '<your-token>'
+    const known = projects.some(p => p.id === project)
+    const snippets = {
+      claude: `claude mcp add cairn --scope user -e CAIRN_URL=${base} -e CAIRN_TOKEN=${token} -- npx -y agentcairn mcp`,
+      http: `claude mcp add --transport http cairn ${base}/mcp --header "Authorization: Bearer ${token}" --header "X-Cairn-Project: ${project}"`,
+      mcp: JSON.stringify({ mcpServers: { 'cairn': { type: 'http', url: '${CAIRN_URL}/mcp', headers: { Authorization: 'Bearer ${CAIRN_TOKEN}', 'X-Cairn-Project': project } } } }, null, 2),
+      cli: `export CAIRN_URL=${base}\nexport CAIRN_TOKEN=${token}\nbrain init ${project}`,
+      check: `curl ${base}/healthz\ncurl -H "Authorization: Bearer ${token}" -H "X-Cairn-Project: ${project}" ${base}/api/project`,
+    }
+    const [, , blurb] = METHODS.find(([k]) => k === method)
+    const tabs = h('div', { class: 'seg', role: 'tablist', 'aria-label': 'Connection method' }, ...METHODS.map(([k, label]) => h('button', { type: 'button', 'aria-pressed': String(k === method), onclick: () => { method = k; drawConnect() } }, label)))
+    connectCard.replaceChildren(
+      h('div', { class: 'head' }, h('div', null, h('h2', null, 'Connect an agent'), h('div', { class: 'hint' }, 'Pick a project, then copy the snippet for your tool.')), tabs),
+      h('div', { class: 'row', style: { marginBottom: '14px', alignItems: 'flex-end', gap: '14px' } },
+        h('div', { class: 'field', style: { margin: 0 } }, h('label', null, 'Server address, as your computers see it'), origin),
+        h('div', { class: 'field', style: { margin: 0 } }, h('label', null, 'Project'), h('div', { class: 'row tight' }, projectSelect, customProject)),
+      ),
+      !known && h('div', { class: 'callout warn', style: { marginBottom: '12px' } }, `"${project}" does not exist yet. Create it under Projects → New project before an agent writes its first memory.`),
+      !fresh && h('div', { class: 'hint', style: { marginBottom: '10px' } }, 'Create a token above and it is filled in here automatically. Tokens are never shown again, so these snippets use a placeholder until then.'),
+      codeBox(snippets[method]),
+      h('p', { class: 'hint', style: { margin: '10px 0 0' } }, blurb),
+    )
+  }
+
+  container.append(
+    h('div', { class: 'page-head' }, h('div', null, h('h1', null, 'Access'), h('div', { class: 'sub' }, 'Who can talk to this server, and how to connect an agent in under a minute.'))),
+    h('div', { class: 'stack', style: { gap: '16px' } }, tokenCard, connectCard),
+  )
+  drawTokens()
+  drawConnect()
+}

package/ui/js/views/auth.js

@@ -0,0 +1,102 @@
+import { api } from '../api.js'
+import { clear, h, svg } from '../dom.js'
+
+function brand() {
+  return h(
+    'div',
+    { class: 'brand' },
+    svg(
+      'svg',
+      { viewBox: '0 0 32 32', 'aria-hidden': 'true' },
+      svg('g', { stroke: 'var(--s1)', 'stroke-width': 2, 'stroke-linecap': 'round' }, svg('path', { d: 'M9 21 16 10M16 10l8 11M9 21h15' })),
+      svg('circle', { cx: 9, cy: 21, r: 3, fill: 'var(--text)' }),
+      svg('circle', { cx: 16, cy: 10, r: 3.4, fill: 'var(--s1)' }),
+      svg('circle', { cx: 24, cy: 21, r: 3, fill: 'var(--text)' }),
+    ),
+    'Agent Cairn',
+  )
+}
+
+function field(label, input, hint) {
+  const id = `f-${Math.random().toString(36).slice(2, 8)}`
+  input.id = id
+  return h('div', { class: 'field' }, h('label', { for: id }, label), input, hint && h('span', { class: 'hint' }, hint))
+}
+
+function page(...children) {
+  return h('div', { class: 'auth-page' }, h('div', { class: 'card panel' }, brand(), ...children))
+}
+
+async function submit(form, button, errorEl, work) {
+  errorEl.textContent = ''
+  button.disabled = true
+  try {
+    await work()
+  } catch (error) {
+    errorEl.textContent = error.message
+    button.disabled = false
+  }
+}
+
+export function mountSetup(root, done) {
+  const error = h('p', { class: 'error', role: 'alert' })
+  const code = h('input', { class: 'input mono', autocomplete: 'off', autocapitalize: 'characters', spellcheck: 'false', placeholder: 'XXXX-XXXX-XXXX', maxlength: '14', required: true })
+  code.addEventListener('input', () => {
+    const raw = code.value.toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, 12)
+    code.value = raw.replace(/(.{4})(?=.)/g, '$1-')
+  })
+  const username = h('input', { class: 'input', autocomplete: 'username', required: true, minlength: '3', maxlength: '32', value: 'admin' })
+  const password = h('input', { class: 'input', type: 'password', autocomplete: 'new-password', required: true, minlength: '10' })
+  const confirm = h('input', { class: 'input', type: 'password', autocomplete: 'new-password', required: true })
+  const button = h('button', { class: 'btn primary', type: 'submit', style: { width: '100%', justifyContent: 'center' } }, 'Create admin account')
+  const form = h(
+    'form',
+    null,
+    field('One-time setup code', code, 'Printed in the server log when it started.'),
+    field('Admin username', username),
+    field('Password', password, 'At least 10 characters.'),
+    field('Repeat password', confirm),
+    error,
+    button,
+  )
+  form.addEventListener('submit', e => {
+    e.preventDefault()
+    submit(form, button, error, async () => {
+      if (password.value !== confirm.value) throw new Error('The passwords do not match.')
+      await api('setup', { body: { code: code.value, username: username.value, password: password.value } })
+      done()
+    })
+  })
+  clear(root).append(
+    page(
+      h('h1', null, 'Set up Agent Cairn'),
+      h('p', { class: 'lead' }, 'Create the admin account for this dashboard.'),
+      h(
+        'div',
+        { class: 'callout', style: { marginBottom: '16px' } },
+        'The one-time setup code is printed in the server log when it starts. With Docker: ',
+        h('code', null, 'docker logs <container>'),
+        ' (or open the container’s Logs in your Docker UI).',
+      ),
+      form,
+    ),
+  )
+  code.focus()
+}
+
+export function mountLogin(root, done) {
+  const error = h('p', { class: 'error', role: 'alert' })
+  const username = h('input', { class: 'input', autocomplete: 'username', required: true })
+  const password = h('input', { class: 'input', type: 'password', autocomplete: 'current-password', required: true })
+  const button = h('button', { class: 'btn primary', type: 'submit', style: { width: '100%', justifyContent: 'center' } }, 'Sign in')
+  const form = h('form', null, field('Username', username), field('Password', password), error, button)
+  form.addEventListener('submit', e => {
+    e.preventDefault()
+    submit(form, button, error, async () => {
+      await api('login', { body: { username: username.value, password: password.value } })
+      done()
+    })
+  })
+  clear(root).append(page(h('h1', null, 'Sign in'), h('p', { class: 'lead' }, 'The looking glass for your project memory.'), form))
+  username.focus()
+}

package/ui/js/views/eventDrawer.js

@@ -0,0 +1,106 @@
+import { api } from '../api.js'
+import { copyText, fmt, h, icon, statusBadge, codeBox } from '../dom.js'
+import { openDrawer } from '../drawer.js'
+import { jsonView } from '../json.js'
+
+const label = e => e.tool ?? e.method
+
+/** Opens the full record of one request: what came in, what went back, and which memories it touched. */
+export function openEvent(summary, navigate) {
+  const body = h('div', null, h('div', { class: 'muted' }, 'Loading…'))
+  const title = h('div', { class: 'row', style: { minWidth: 0 } }, h('h2', { class: 'mono' }, label(summary)), statusBadge(summary))
+  const drawer = openDrawer(title, body)
+
+  api(`events/${summary.id}`)
+    .then(event => drawer.body.replaceChildren(render(event, navigate, drawer.close)))
+    .catch(error => drawer.body.replaceChildren(h('p', { class: 'error' }, error.message)))
+}
+
+function kv(rows) {
+  return h('dl', { class: 'kv' }, rows.filter(Boolean).flatMap(([k, v]) => [h('dt', null, k), h('dd', null, v)]))
+}
+
+function render(event, navigate, close) {
+  const tabs = ['Overview', 'Request', 'Response', 'Raw']
+  const panels = {
+    Overview: overview(event, navigate, close),
+    Request: panel(event.request, 'No request payload was captured (capture mode is "meta" or the request had no body).'),
+    Response: responsePanel(event),
+    Raw: codeBox(JSON.stringify(event, null, 2)),
+  }
+  const content = h('div')
+  const bar = h('div', { class: 'tabs', role: 'tablist' })
+  const show = name => {
+    for (const b of bar.children) b.setAttribute('aria-selected', String(b.textContent === name))
+    content.replaceChildren(panels[name])
+  }
+  for (const name of tabs) bar.append(h('button', { type: 'button', role: 'tab', onclick: () => show(name) }, name))
+  show(event.tool || event.request ? 'Overview' : 'Overview')
+  return h('div', null, bar, content)
+}
+
+function panel(value, empty) {
+  if (value === undefined) return h('div', { class: 'muted' }, empty)
+  return h('div', { class: 'stack' }, h('div', { class: 'row' }, h('button', { class: 'btn sm', type: 'button', onclick: () => copyText(JSON.stringify(value, null, 2)) }, icon('copy'), 'Copy JSON')), jsonView(value))
+}
+
+function responsePanel(event) {
+  const r = event.response
+  if (r === undefined) return h('div', { class: 'muted' }, 'No response payload was captured.')
+  if (typeof r?.text === 'string') {
+    return h(
+      'div',
+      { class: 'stack' },
+      h('div', { class: 'row' }, h('span', { class: 'muted' }, `${fmt.int(event.tokensOut)} tokens (est.) sent to the agent`), h('span', { class: 'grow' }), h('button', { class: 'btn sm', type: 'button', onclick: () => copyText(r.text) }, icon('copy'), 'Copy text')),
+      h('pre', { class: 'pre' }, r.text),
+    )
+  }
+  return panel(r, '')
+}
+
+function overview(event, navigate, close) {
+  const client = event.client
+  const refs = event.memoryRefs.length
+    ? h(
+        'span',
+        { class: 'tags' },
+        event.memoryRefs.map(ref =>
+          h(
+            'span',
+            {
+              class: 'tag ref',
+              role: 'link',
+              tabindex: '0',
+              title: 'Show in the graph',
+              onclick: () => {
+                close()
+                navigate(`#/graph?project=${encodeURIComponent(event.project ?? '')}&focus=${ref}`)
+              },
+            },
+            `#${ref}`,
+          ),
+        ),
+      )
+    : h('span', { class: 'muted' }, 'none')
+  return h(
+    'div',
+    { class: 'stack' },
+    event.error && h('div', { class: 'callout warn' }, event.error),
+    kv([
+      ['Time', fmt.dateTime(event.ts)],
+      ['Source', event.source === 'mcp' ? 'MCP (agent)' : event.source === 'api' ? 'JSON API (CLI / hooks)' : 'Rejected request'],
+      ['Call', h('span', { class: 'mono' }, event.tool ? `${event.method} → ${event.tool}` : event.method)],
+      ['Project', event.project ?? h('span', { class: 'muted' }, 'not specified')],
+      ['Token', client.token ?? h('span', { class: 'muted' }, 'none')],
+      ['Agent', client.agent ?? '–'],
+      ['IP address', client.ip ?? '–'],
+      ['User-Agent', client.userAgent ? h('span', { class: 'mono' }, client.userAgent) : '–'],
+      ['Duration', fmt.ms(event.durationMs)],
+      ['HTTP status', String(event.httpStatus)],
+      ['Request size', fmt.bytes(event.bytesIn)],
+      ['Response size', fmt.bytes(event.bytesOut)],
+      ['Tokens out (est.)', fmt.int(event.tokensOut)],
+      ['Memories touched', refs],
+    ]),
+  )
+}