@viewert/mcp 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @viewert/mcp
+
+MCP server for [Viewert](https://viewert.com) — expose your Librams (AI context collections) to any MCP-compatible AI client.
+
+## What it does
+
+Connects Claude Desktop, Cursor, Windsurf, or any MCP client to your Viewert Librams. Each Libram is a curated collection of Vellums (notes/documents) that you've marked as available for AI context.
+
+## Setup
+
+### 1. Get an API key
+
+Go to **Settings → API Keys** on Viewert and create a key. Copy it — it's shown only once.
+
+### 2. Add to your MCP client config
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "viewert": {
+      "command": "npx",
+      "args": ["-y", "@viewert/mcp"],
+      "env": {
+        "VIEWERT_API_KEY": "vwt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** (`.cursor/mcp.json` or `.windsurf/mcp.json` in your project, or global config):
+
+```json
+{
+  "mcpServers": {
+    "viewert": {
+      "command": "npx",
+      "args": ["-y", "@viewert/mcp"],
+      "env": {
+        "VIEWERT_API_KEY": "vwt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart your AI client
+
+The Viewert tools will appear automatically.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_librams` | List all Librams in your account with names and IDs |
+| `get_libram_context` | Fetch all AI-enabled Vellums from a Libram as **markdown** |
+| `get_libram_context_json` | Fetch AI-enabled Vellums as **structured JSON** (id, title, content) |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `librams://list` | JSON list of all your Librams |
+| `librams://{id}/context` | Markdown context for a specific Libram |
+
+---
+
+## Environment variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `VIEWERT_API_KEY` | ✅ Yes | — |
+| `VIEWERT_API_URL` | No | `https://viewert.com/api` |
+
+---
+
+## Example usage in Claude
+
+> "Load my **Project Notes** Libram and summarise the key points."
+
+Claude will call `list_librams` to find the ID, then `get_libram_context` to pull the content — all inline in the conversation.
+
+---
+
+## Local development
+
+```bash
+cd mcp
+pnpm install
+VIEWERT_API_KEY=vwt_... pnpm dev
+```

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Viewert MCP Server
+ *
+ * Exposes Viewert Librams as context resources and tools to any MCP-compatible
+ * AI client (Claude Desktop, Cursor, Windsurf, etc.).
+ *
+ * Required env vars:
+ *   VIEWERT_API_KEY   — your vwt_... API key from viewert.com/settings
+ *
+ * Optional env vars:
+ *   VIEWERT_API_URL   — defaults to https://viewert.com/api
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * Viewert MCP Server
+ *
+ * Exposes Viewert Librams as context resources and tools to any MCP-compatible
+ * AI client (Claude Desktop, Cursor, Windsurf, etc.).
+ *
+ * Required env vars:
+ *   VIEWERT_API_KEY   — your vwt_... API key from viewert.com/settings
+ *
+ * Optional env vars:
+ *   VIEWERT_API_URL   — defaults to https://viewert.com/api
+ */
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_KEY = process.env.VIEWERT_API_KEY;
+const API_BASE = (process.env.VIEWERT_API_URL ?? 'https://viewert.com/api').replace(/\/$/, '');
+if (!API_KEY) {
+    process.stderr.write('[viewert-mcp] ERROR: VIEWERT_API_KEY is not set.\n' +
+        'Generate a key at https://viewert.com/settings and add it to your MCP config.\n');
+    process.exit(1);
+}
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+async function apiFetch(path, opts = {}) {
+    return fetch(`${API_BASE}${path}`, {
+        ...opts,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json',
+            ...(opts.headers ?? {}),
+        },
+    });
+}
+async function apiJSON(path) {
+    const res = await apiFetch(path);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Viewert API ${res.status}: ${body}`);
+    }
+    return res.json();
+}
+async function apiText(path) {
+    const res = await apiFetch(path);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Viewert API ${res.status}: ${body}`);
+    }
+    return res.text();
+}
+// ── Server ────────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: 'viewert',
+    version: '0.1.0',
+});
+// ── Tool: list_librams ────────────────────────────────────────────────────────
+server.tool('list_librams', 'List all Librams (AI context collections) in your Viewert account.', {}, async () => {
+    const data = await apiJSON('/librams/mine');
+    const librams = data.librams ?? [];
+    if (librams.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'You have no Librams yet. Create one at https://viewert.com/librams' }],
+        };
+    }
+    const lines = librams.map((l) => `• ${l.emoji || '📁'} **${l.name}** (id: \`${l.id}\`)` +
+        ` — ${l.ai_count} AI vellums` +
+        (l.description ? ` — ${l.description}` : ''));
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `**Your Viewert Librams (${librams.length})**\n\n${lines.join('\n')}\n\nUse \`get_libram_context\` with a libram id to load its content.`,
+            },
+        ],
+    };
+});
+// ── Tool: get_libram_context ──────────────────────────────────────────────────
+server.tool('get_libram_context', 'Fetch the full AI-enabled Vellum contents of a Viewert Libram as markdown. ' +
+    'Use this to inject knowledge from your Libram into the current conversation.', {
+    libram_id: z.string().describe('The ID of the Libram to fetch. Use list_librams to find IDs.'),
+}, async ({ libram_id }) => {
+    const markdown = await apiText(`/librams/${libram_id}/context?format=markdown`);
+    return {
+        content: [{ type: 'text', text: markdown }],
+    };
+});
+// ── Tool: get_libram_context_json ─────────────────────────────────────────────
+server.tool('get_libram_context_json', 'Fetch AI-enabled Vellums from a Libram as structured JSON (id, title, content per vellum). ' +
+    'Use this when you need to reference individual vellums by title or process them separately.', {
+    libram_id: z.string().describe('The ID of the Libram to fetch.'),
+}, async ({ libram_id }) => {
+    const data = await apiJSON(`/librams/${libram_id}/context?format=json`);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// ── Resource: librams://list ──────────────────────────────────────────────────
+server.resource('librams', 'librams://list', { mimeType: 'application/json', description: 'All Librams in your Viewert account' }, async () => {
+    const data = await apiJSON('/librams/mine');
+    return {
+        contents: [
+            {
+                uri: 'librams://list',
+                mimeType: 'application/json',
+                text: JSON.stringify(data.librams ?? [], null, 2),
+            },
+        ],
+    };
+});
+// ── Resource: librams://{id}/context ─────────────────────────────────────────
+server.resource('libram-context', new ResourceTemplate('librams://{id}/context', { list: undefined }), { mimeType: 'text/markdown', description: 'AI-enabled Vellum contents of a Libram as markdown' }, async (uri, variables) => {
+    const libramId = variables['id'];
+    if (!libramId)
+        throw new Error(`Missing libram id in URI: ${uri.href}`);
+    const markdown = await apiText(`/librams/${libramId}/context?format=markdown`);
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: markdown,
+            },
+        ],
+    };
+});
+// ── Start ─────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write('[viewert-mcp] Server started. Waiting for MCP client...\n');

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@viewert/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Viewert Librams — expose AI-enabled Vellums as context to any MCP-compatible AI client",
+  "keywords": ["mcp", "viewert", "libram", "ai-context", "model-context-protocol"],
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "viewert-mcp": "dist/index.js"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Viewert MCP Server
+ *
+ * Exposes Viewert Librams as context resources and tools to any MCP-compatible
+ * AI client (Claude Desktop, Cursor, Windsurf, etc.).
+ *
+ * Required env vars:
+ *   VIEWERT_API_KEY   — your vwt_... API key from viewert.com/settings
+ *
+ * Optional env vars:
+ *   VIEWERT_API_URL   — defaults to https://viewert.com/api
+ */
+
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+const API_KEY = process.env.VIEWERT_API_KEY
+const API_BASE = (process.env.VIEWERT_API_URL ?? 'https://viewert.com/api').replace(/\/$/, '')
+
+if (!API_KEY) {
+  process.stderr.write(
+    '[viewert-mcp] ERROR: VIEWERT_API_KEY is not set.\n' +
+    'Generate a key at https://viewert.com/settings and add it to your MCP config.\n'
+  )
+  process.exit(1)
+}
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+async function apiFetch(path: string, opts: RequestInit = {}): Promise<Response> {
+  return fetch(`${API_BASE}${path}`, {
+    ...opts,
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+      ...(opts.headers as Record<string, string> ?? {}),
+    },
+  })
+}
+
+async function apiJSON<T>(path: string): Promise<T> {
+  const res = await apiFetch(path)
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(`Viewert API ${res.status}: ${body}`)
+  }
+  return res.json() as Promise<T>
+}
+
+async function apiText(path: string): Promise<string> {
+  const res = await apiFetch(path)
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(`Viewert API ${res.status}: ${body}`)
+  }
+  return res.text()
+}
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+interface Libram {
+  id: string
+  name: string
+  description: string
+  emoji: string
+  is_public: boolean
+  vellum_count: number
+  ai_count: number
+  updated_at: string
+}
+
+// ── Server ────────────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'viewert',
+  version: '0.1.0',
+})
+
+// ── Tool: list_librams ────────────────────────────────────────────────────────
+
+server.tool(
+  'list_librams',
+  'List all Librams (AI context collections) in your Viewert account.',
+  {},
+  async () => {
+    const data = await apiJSON<{ librams: Libram[] }>('/librams/mine')
+    const librams = data.librams ?? []
+
+    if (librams.length === 0) {
+      return {
+        content: [{ type: 'text', text: 'You have no Librams yet. Create one at https://viewert.com/librams' }],
+      }
+    }
+
+    const lines = librams.map((l) =>
+      `• ${l.emoji || '📁'} **${l.name}** (id: \`${l.id}\`)` +
+      ` — ${l.ai_count} AI vellums` +
+      (l.description ? ` — ${l.description}` : '')
+    )
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `**Your Viewert Librams (${librams.length})**\n\n${lines.join('\n')}\n\nUse \`get_libram_context\` with a libram id to load its content.`,
+        },
+      ],
+    }
+  }
+)
+
+// ── Tool: get_libram_context ──────────────────────────────────────────────────
+
+server.tool(
+  'get_libram_context',
+  'Fetch the full AI-enabled Vellum contents of a Viewert Libram as markdown. ' +
+  'Use this to inject knowledge from your Libram into the current conversation.',
+  {
+    libram_id: z.string().describe('The ID of the Libram to fetch. Use list_librams to find IDs.'),
+  },
+  async ({ libram_id }) => {
+    const markdown = await apiText(`/librams/${libram_id}/context?format=markdown`)
+    return {
+      content: [{ type: 'text', text: markdown }],
+    }
+  }
+)
+
+// ── Tool: get_libram_context_json ─────────────────────────────────────────────
+
+server.tool(
+  'get_libram_context_json',
+  'Fetch AI-enabled Vellums from a Libram as structured JSON (id, title, content per vellum). ' +
+  'Use this when you need to reference individual vellums by title or process them separately.',
+  {
+    libram_id: z.string().describe('The ID of the Libram to fetch.'),
+  },
+  async ({ libram_id }) => {
+    const data = await apiJSON<{
+      libram_name: string
+      vellums: Array<{ id: string; title: string; content: string }>
+    }>(`/librams/${libram_id}/context?format=json`)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(data, null, 2),
+        },
+      ],
+    }
+  }
+)
+
+// ── Resource: librams://list ──────────────────────────────────────────────────
+
+server.resource(
+  'librams',
+  'librams://list',
+  { mimeType: 'application/json', description: 'All Librams in your Viewert account' },
+  async () => {
+    const data = await apiJSON<{ librams: Libram[] }>('/librams/mine')
+    return {
+      contents: [
+        {
+          uri: 'librams://list',
+          mimeType: 'application/json',
+          text: JSON.stringify(data.librams ?? [], null, 2),
+        },
+      ],
+    }
+  }
+)
+
+// ── Resource: librams://{id}/context ─────────────────────────────────────────
+
+server.resource(
+  'libram-context',
+  new ResourceTemplate('librams://{id}/context', { list: undefined }),
+  { mimeType: 'text/markdown', description: 'AI-enabled Vellum contents of a Libram as markdown' },
+  async (uri: URL, variables: Record<string, string | string[]>) => {
+    const libramId = variables['id'] as string
+    if (!libramId) throw new Error(`Missing libram id in URI: ${uri.href}`)
+    const markdown = await apiText(`/librams/${libramId}/context?format=markdown`)
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: 'text/markdown',
+          text: markdown,
+        },
+      ],
+    }
+  }
+)
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+process.stderr.write('[viewert-mcp] Server started. Waiting for MCP client...\n')

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}