gramatr 0.3.56 → 0.3.57

package/chatgpt/README.md

@@ -0,0 +1,95 @@
+# gramatr - ChatGPT Desktop Integration
+
+Tier 3 integration: MCP only (no hooks, no status line).
+
+## Prerequisites
+
+- **ChatGPT Plus, Team, or Enterprise** subscription (free accounts do not support MCP)
+- **ChatGPT Desktop** app installed ([download](https://openai.com/chatgpt/desktop))
+- **Developer Mode** enabled in ChatGPT Desktop settings
+- A **gramatr API key** — get one at [gramatr.com/settings](https://gramatr.com/settings)
+
+## Installation
+
+### Method 1: Installer script (recommended)
+
+```bash
+cd packages/client
+bun chatgpt/install.ts
+```
+
+The installer will:
+1. Find your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompt you
+2. Validate connectivity to the gramatr server
+3. Detect your platform and locate the ChatGPT config file
+4. Merge the gramatr MCP server entry without overwriting existing servers
+5. Print verification instructions
+
+### Method 2: Environment variable
+
+```bash
+GRAMATR_API_KEY=your-key-here bun chatgpt/install.ts
+```
+
+### Method 3: Manual configuration
+
+Add to your ChatGPT MCP config file:
+
+**macOS:** `~/.chatgpt/mcp.json`
+**Windows:** `%APPDATA%\ChatGPT\mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "gramatr": {
+      "url": "https://mcp.gramatr.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Verification
+
+1. Open ChatGPT Desktop
+2. Go to **Settings > Developer > MCP Servers**
+3. Confirm "gramatr" appears in the list with a green status indicator
+4. Start a new conversation and type: "What gramatr tools are available?"
+5. ChatGPT should list the available MCP tools from the gramatr server
+
+## Config file locations
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/.chatgpt/mcp.json` |
+| Windows | `%APPDATA%\ChatGPT\mcp.json` |
+
+## Limitations
+
+ChatGPT Desktop is a **Tier 3** integration:
+
+- MCP tools are available (search, create entities, route requests, etc.)
+- No PostToolUse hooks (no automatic metrics tracking)
+- No status line
+- No prompt enrichment hooks
+
+For the full gramatr experience with hooks, status line, and prompt enrichment, use Claude Code or Codex.
+
+## Troubleshooting
+
+**"gramatr" not showing in MCP servers:**
+- Ensure Developer Mode is enabled in ChatGPT Desktop settings
+- Check that the config file exists at the correct path
+- Restart ChatGPT Desktop after editing the config
+
+**Connection errors:**
+- Verify your API key is valid: `bun bin/gmtr-login.ts --status`
+- Check server health: `curl https://api.gramatr.com/health`
+- Ensure you have an active internet connection
+
+**Tools not appearing in conversation:**
+- MCP tools may take a moment to load after connecting
+- Try starting a new conversation
+- Check the MCP server status indicator in Settings > Developer

package/chatgpt/install.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import {
+  getChatGPTConfigPath,
+  mergeChatGPTConfig,
+  buildMcpServerEntry,
+  type ChatGPTConfig,
+} from './lib/chatgpt-install-utils.ts';
+
+const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
+const VALIDATION_ENDPOINT = 'https://api.gramatr.com/health';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function readJsonFile<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Resolve API key from available sources.
+ * Priority: CLI arg > GRAMATR_API_KEY env > ~/.gmtr.json token > gmtr-client/settings.json
+ */
+function resolveApiKey(): string | null {
+  const home = homedir();
+
+  // 1. GRAMATR_API_KEY env var
+  if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
+
+  // 2. GMTR_TOKEN env var (legacy compat)
+  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
+
+  // 3. ~/.gmtr.json
+  try {
+    const gmtrJsonPath = join(home, '.gmtr.json');
+    const gmtrJson = JSON.parse(readFileSync(gmtrJsonPath, 'utf8'));
+    if (gmtrJson.token) return gmtrJson.token;
+  } catch {
+    // Not found or parse error
+  }
+
+  // 4. ~/gmtr-client/settings.json
+  try {
+    const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
+    const settingsPath = join(gmtrDir, 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    if (settings.auth?.api_key && settings.auth.api_key !== 'REPLACE_WITH_YOUR_API_KEY') {
+      return settings.auth.api_key;
+    }
+  } catch {
+    // Not found or parse error
+  }
+
+  return null;
+}
+
+/**
+ * Validate token against gramatr server health endpoint.
+ * Returns true if server is reachable (we don't enforce auth for install — server validates on use).
+ */
+async function validateServer(serverUrl: string): Promise<boolean> {
+  try {
+    const baseUrl = serverUrl.replace(/\/mcp$/, '');
+    const response = await fetch(`${baseUrl}/health`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(5000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function promptForInput(prompt: string): Promise<string> {
+  process.stdout.write(prompt);
+  const reader = process.stdin;
+  reader.resume();
+  return new Promise((resolve) => {
+    reader.once('data', (data) => {
+      reader.pause();
+      resolve(data.toString().trim());
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  const home = homedir();
+  const platform = process.platform;
+
+  log('');
+  log('gramatr - ChatGPT Desktop installer');
+  log('====================================');
+  log('');
+
+  // Step 1: Resolve auth
+  log('Step 1: Resolving authentication...');
+  let apiKey = resolveApiKey();
+
+  if (!apiKey) {
+    log('  No API key found in ~/.gmtr.json, GRAMATR_API_KEY env, or gmtr-client/settings.json.');
+    apiKey = await promptForInput('  Enter your gramatr API key: ');
+    if (!apiKey) {
+      log('');
+      log('ERROR: API key is required. Get one at https://gramatr.com/settings');
+      log('  Or set GRAMATR_API_KEY environment variable before running this installer.');
+      process.exit(1);
+    }
+  } else {
+    log('  OK Found existing API key');
+  }
+
+  // Step 2: Validate server connectivity
+  log('');
+  log('Step 2: Validating server connectivity...');
+  const serverUrl = process.env.GMTR_URL || DEFAULT_MCP_URL;
+  const serverReachable = await validateServer(serverUrl);
+  if (serverReachable) {
+    log(`  OK Server reachable at ${serverUrl.replace(/\/mcp$/, '')}`);
+  } else {
+    log(`  WARN Server not reachable at ${serverUrl.replace(/\/mcp$/, '')} — config will be written anyway`);
+  }
+
+  // Step 3: Detect platform and config path
+  log('');
+  log('Step 3: Detecting ChatGPT Desktop...');
+  const configPath = getChatGPTConfigPath(home, platform);
+  const configDir = dirname(configPath);
+
+  if (platform === 'darwin') {
+    log('  Platform: macOS');
+  } else if (platform === 'win32') {
+    log('  Platform: Windows');
+  } else {
+    log(`  Platform: ${platform} (ChatGPT Desktop may not be available)`);
+  }
+  log(`  Config: ${configPath}`);
+
+  // Step 4: Read existing config
+  log('');
+  log('Step 4: Reading existing config...');
+  const existing = readJsonFile<ChatGPTConfig>(configPath, {});
+
+  const existingServerCount = existing.mcpServers ? Object.keys(existing.mcpServers).length : 0;
+  if (existingServerCount > 0) {
+    log(`  Found ${existingServerCount} existing MCP server(s)`);
+    if (existing.mcpServers?.gramatr) {
+      log('  Existing gramatr entry will be updated');
+    }
+  } else {
+    log('  No existing config (will create new)');
+  }
+
+  // Step 5: Merge and write config
+  log('');
+  log('Step 5: Writing config...');
+  const gramatrEntry = buildMcpServerEntry(apiKey, serverUrl);
+  const merged = mergeChatGPTConfig(existing, gramatrEntry);
+
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+    log(`  Created directory: ${configDir}`);
+  }
+
+  writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  log(`  OK Written to ${configPath}`);
+
+  // Summary
+  log('');
+  log('Installation complete.');
+  log('');
+  log('Next steps:');
+  log('  1. Open ChatGPT Desktop');
+  log('  2. Go to Settings > Developer > MCP Servers');
+  log('  3. Verify "gramatr" appears in the server list');
+  log('  4. Start a conversation and gramatr tools will be available');
+  log('');
+  log('What was configured:');
+  log(`  MCP server:  ${serverUrl}`);
+  log(`  Config file: ${configPath}`);
+  log('');
+  log('Note: ChatGPT Desktop is Tier 3 (MCP only). Hooks and status line are not');
+  log('available — use Claude Code or Codex for the full gramatr experience.');
+}
+
+main().catch((err) => {
+  log(`ERROR: ${err.message}`);
+  process.exit(1);
+});

package/chatgpt/lib/chatgpt-install-utils.ts

@@ -0,0 +1,89 @@
+import { join } from 'path';
+
+const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
+
+export interface ChatGPTMcpServerEntry {
+  gramatr: {
+    url?: string;
+    headers?: {
+      Authorization: string;
+    };
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+  };
+}
+
+export interface ChatGPTConfig {
+  mcpServers?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Returns the ChatGPT Desktop config file path for the given platform.
+ *
+ * macOS: ~/.chatgpt/mcp.json
+ * Windows: %APPDATA%\ChatGPT\mcp.json (APPDATA = <home>\AppData\Roaming)
+ */
+export function getChatGPTConfigPath(
+  home: string,
+  platform: string = process.platform,
+): string {
+  if (platform === 'win32') {
+    return join(home, 'AppData', 'Roaming', 'ChatGPT', 'mcp.json');
+  }
+
+  // macOS (darwin) and fallback for other platforms
+  return join(home, '.chatgpt', 'mcp.json');
+}
+
+/**
+ * Build the mcpServers.gramatr entry for ChatGPT Desktop config.
+ *
+ * Two modes:
+ * - 'http' (default): StreamableHTTP transport — ChatGPT connects directly to the remote URL.
+ * - 'stdio': Local bridge process — ChatGPT spawns a local process that proxies to the server.
+ */
+export function buildMcpServerEntry(
+  apiKey: string,
+  serverUrl: string = DEFAULT_MCP_URL,
+  mode: 'http' | 'stdio' = 'http',
+): ChatGPTMcpServerEntry {
+  if (mode === 'stdio') {
+    return {
+      gramatr: {
+        command: 'npx',
+        args: ['-y', '@anthropic-ai/mcp-proxy', serverUrl],
+        env: {
+          GRAMATR_API_KEY: apiKey,
+        },
+      },
+    };
+  }
+
+  return {
+    gramatr: {
+      url: serverUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+  };
+}
+
+/**
+ * Safely merge a gramatr MCP server entry into an existing ChatGPT Desktop config.
+ * Preserves all other mcpServers and top-level config keys.
+ */
+export function mergeChatGPTConfig(
+  existing: ChatGPTConfig,
+  gramatrEntry: ChatGPTMcpServerEntry,
+): ChatGPTConfig {
+  return {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers || {}),
+      ...gramatrEntry,
+    },
+  };
+}

package/desktop/README.md

@@ -0,0 +1,72 @@
+# gramatr - Claude Desktop Integration
+
+Claude Desktop is a **Tier 3** integration target: MCP only, no hooks.
+
+gramatr connects to Claude Desktop via StreamableHTTP MCP transport. All intelligence (decision routing, memory, pattern learning) runs server-side.
+
+## Installation
+
+```bash
+# Interactive installer — resolves auth, detects platform, merges config
+bun packages/client/desktop/install.ts
+```
+
+The installer:
+1. Resolves your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompts
+2. Validates connectivity to the gramatr server
+3. Detects platform (macOS or Windows)
+4. Reads existing `claude_desktop_config.json` without overwriting other MCP servers
+5. Writes the gramatr MCP server entry
+
+### Config Locations
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+### Manual Setup
+
+If you prefer to configure manually, add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gramatr": {
+      "url": "https://mcp.gramatr.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## .mcpb Package
+
+Build a `.mcpb` extension package for distribution:
+
+```bash
+bun packages/client/desktop/build-mcpb.ts
+# Output: dist/gramatr.mcpb/manifest.json
+```
+
+The `.mcpb` format follows [Anthropic's manifest v0.3 spec](https://github.com/anthropics/mcpb/blob/main/MANIFEST.md).
+
+## What Works
+
+Claude Desktop gets full access to gramatr's MCP tools:
+- Semantic search, entity management, knowledge graph
+- Decision routing, skill matching, pattern learning
+- Session state, handoffs, reflections
+
+## What Does Not Work
+
+Claude Desktop has no hook system, so these features are unavailable:
+- PreToolUse / PostToolUse hooks (security validation, algorithm tracking)
+- Session lifecycle hooks (auto session-start, session-end)
+- Prompt enrichment (intelligence packet injection)
+- Rating capture
+- Status line
+
+For the full gramatr experience, use Claude Code or Codex.

package/desktop/build-mcpb.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+/**
+ * Build a .mcpb package for Claude Desktop.
+ *
+ * The .mcpb format (manifest v0.3) is Anthropic's extension packaging format
+ * for Claude Desktop. gramatr is a remote MCP server, so the package contains
+ * only the manifest — no local server binary.
+ *
+ * Reference: https://github.com/anthropics/mcpb/blob/main/MANIFEST.md
+ *
+ * Usage: bun desktop/build-mcpb.ts [--out <path>]
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const currentFile = fileURLToPath(import.meta.url);
+const desktopDir = dirname(currentFile);
+const clientDir = dirname(desktopDir);
+const packagesDir = dirname(clientDir);
+const repoRoot = dirname(packagesDir);
+
+interface McpbManifest {
+  manifest_version: string;
+  name: string;
+  display_name: string;
+  version: string;
+  description: string;
+  long_description: string;
+  author: {
+    name: string;
+    url: string;
+  };
+  homepage: string;
+  documentation: string;
+  repository: {
+    type: string;
+    url: string;
+  };
+  license: string;
+  keywords: string[];
+  server: {
+    type: string;
+    transport: string;
+    url: string;
+  };
+  user_config: Record<string, {
+    type: string;
+    title: string;
+    description: string;
+    sensitive?: boolean;
+    required: boolean;
+  }>;
+  compatibility: {
+    claude_desktop: string;
+    platforms: string[];
+  };
+  privacy_policies: string[];
+  tools_generated: boolean;
+  prompts_generated: boolean;
+}
+
+function readPackageVersion(): string {
+  try {
+    const pkgPath = join(clientDir, 'package.json');
+    const { readFileSync } = require('fs');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function buildManifest(version: string): McpbManifest {
+  return {
+    manifest_version: '0.3',
+    name: 'gramatr',
+    display_name: 'gramatr',
+    version,
+    description: 'Intelligent AI middleware — decision routing, vector memory, and pattern learning for Claude Desktop.',
+    long_description: [
+      'gramatr is an intelligent middleware layer that makes Claude smarter and cheaper.',
+      'It pre-classifies every request using a lightweight model before expensive models burn tokens on routing overhead.',
+      '',
+      '**What you get:**',
+      '- Decision routing — effort level, intent, and skill classification',
+      '- Vector memory — persistent knowledge graph with semantic search',
+      '- Pattern learning — usage patterns that improve routing over time',
+      '- Token savings — ~2,700 tokens saved per request at scale',
+      '',
+      'Claude Desktop connects to the gramatr server via StreamableHTTP MCP transport.',
+      'All intelligence runs server-side — no local compute required.',
+    ].join('\n'),
+    author: {
+      name: 'gramatr',
+      url: 'https://gramatr.com',
+    },
+    homepage: 'https://gramatr.com',
+    documentation: 'https://docs.gramatr.com',
+    repository: {
+      type: 'git',
+      url: 'https://github.com/gramatr/gramatr',
+    },
+    license: 'MIT',
+    keywords: [
+      'ai',
+      'memory',
+      'routing',
+      'intelligence',
+      'mcp',
+      'knowledge-graph',
+      'vector-search',
+      'decision-routing',
+    ],
+    server: {
+      type: 'remote',
+      transport: 'streamable-http',
+      url: 'https://mcp.gramatr.com/mcp',
+    },
+    user_config: {
+      api_key: {
+        type: 'string',
+        title: 'API Key',
+        description: 'Your gramatr API key. Get one at https://gramatr.com/settings',
+        sensitive: true,
+        required: true,
+      },
+    },
+    compatibility: {
+      claude_desktop: '>=1.0.0',
+      platforms: ['darwin', 'win32'],
+    },
+    privacy_policies: ['https://gramatr.com/privacy'],
+    tools_generated: true,
+    prompts_generated: true,
+  };
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const outIndex = args.indexOf('--out');
+  const outDir = outIndex >= 0 && args[outIndex + 1]
+    ? args[outIndex + 1]
+    : join(repoRoot, 'dist');
+
+  const version = readPackageVersion();
+  const manifest = buildManifest(version);
+
+  // Create output directory
+  const mcpbDir = join(outDir, 'gramatr.mcpb');
+  if (!existsSync(mcpbDir)) {
+    mkdirSync(mcpbDir, { recursive: true });
+  }
+
+  // Write manifest.json
+  const manifestPath = join(mcpbDir, 'manifest.json');
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+  process.stdout.write(`OK Built .mcpb package\n`);
+  process.stdout.write(`   Manifest: ${manifestPath}\n`);
+  process.stdout.write(`   Version:  ${version}\n`);
+  process.stdout.write(`   Server:   ${manifest.server.url}\n`);
+}
+
+main();

package/desktop/install.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import {
+  getDesktopConfigPath,
+  mergeDesktopConfig,
+  buildMcpServerEntry,
+  type DesktopConfig,
+} from './lib/desktop-install-utils.ts';
+
+const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
+const VALIDATION_ENDPOINT = 'https://api.gramatr.com/health';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function readJsonFile<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Resolve API key from available sources.
+ * Priority: CLI arg > GRAMATR_API_KEY env > ~/.gmtr.json token > gmtr-client/settings.json
+ */
+function resolveApiKey(): string | null {
+  const home = homedir();
+
+  // 1. GRAMATR_API_KEY env var
+  if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
+
+  // 2. GMTR_TOKEN env var (legacy compat)
+  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
+
+  // 3. ~/.gmtr.json
+  try {
+    const gmtrJsonPath = join(home, '.gmtr.json');
+    const gmtrJson = JSON.parse(readFileSync(gmtrJsonPath, 'utf8'));
+    if (gmtrJson.token) return gmtrJson.token;
+  } catch {
+    // Not found or parse error
+  }
+
+  // 4. ~/gmtr-client/settings.json
+  try {
+    const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
+    const settingsPath = join(gmtrDir, 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    if (settings.auth?.api_key && settings.auth.api_key !== 'REPLACE_WITH_YOUR_API_KEY') {
+      return settings.auth.api_key;
+    }
+  } catch {
+    // Not found or parse error
+  }
+
+  return null;
+}
+
+/**
+ * Validate token against gramatr server health endpoint.
+ * Returns true if server is reachable (we don't enforce auth for install — server validates on use).
+ */
+async function validateServer(serverUrl: string): Promise<boolean> {
+  try {
+    const baseUrl = serverUrl.replace(/\/mcp$/, '');
+    const response = await fetch(`${baseUrl}/health`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(5000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function promptForInput(prompt: string): Promise<string> {
+  process.stdout.write(prompt);
+  const reader = process.stdin;
+  reader.resume();
+  return new Promise((resolve) => {
+    reader.once('data', (data) => {
+      reader.pause();
+      resolve(data.toString().trim());
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  const home = homedir();
+  const platform = process.platform;
+
+  log('');
+  log('gramatr - Claude Desktop installer');
+  log('===================================');
+  log('');
+
+  // Step 1: Resolve auth
+  log('Step 1: Resolving authentication...');
+  let apiKey = resolveApiKey();
+
+  if (!apiKey) {
+    log('  No API key found in ~/.gmtr.json, GRAMATR_API_KEY env, or gmtr-client/settings.json.');
+    apiKey = await promptForInput('  Enter your gramatr API key: ');
+    if (!apiKey) {
+      log('');
+      log('ERROR: API key is required. Get one at https://gramatr.com/settings');
+      log('  Or set GRAMATR_API_KEY environment variable before running this installer.');
+      process.exit(1);
+    }
+  } else {
+    log('  OK Found existing API key');
+  }
+
+  // Step 2: Validate server connectivity
+  log('');
+  log('Step 2: Validating server connectivity...');
+  const serverUrl = process.env.GMTR_URL || DEFAULT_MCP_URL;
+  const serverReachable = await validateServer(serverUrl);
+  if (serverReachable) {
+    log(`  OK Server reachable at ${serverUrl.replace(/\/mcp$/, '')}`);
+  } else {
+    log(`  WARN Server not reachable at ${serverUrl.replace(/\/mcp$/, '')} — config will be written anyway`);
+  }
+
+  // Step 3: Detect platform and config path
+  log('');
+  log('Step 3: Detecting Claude Desktop...');
+  const configPath = getDesktopConfigPath(home, platform);
+  const configDir = dirname(configPath);
+
+  if (platform === 'darwin') {
+    log('  Platform: macOS');
+  } else if (platform === 'win32') {
+    log('  Platform: Windows');
+  } else {
+    log(`  Platform: ${platform} (Claude Desktop may not be available)`);
+  }
+  log(`  Config: ${configPath}`);
+
+  // Step 4: Read existing config
+  log('');
+  log('Step 4: Reading existing config...');
+  const existing = readJsonFile<DesktopConfig>(configPath, {});
+
+  const existingServerCount = existing.mcpServers ? Object.keys(existing.mcpServers).length : 0;
+  if (existingServerCount > 0) {
+    log(`  Found ${existingServerCount} existing MCP server(s)`);
+    if (existing.mcpServers?.gramatr) {
+      log('  Existing gramatr entry will be updated');
+    }
+  } else {
+    log('  No existing config (will create new)');
+  }
+
+  // Step 5: Merge and write config
+  log('');
+  log('Step 5: Writing config...');
+  const gramatrEntry = buildMcpServerEntry(apiKey, serverUrl);
+  const merged = mergeDesktopConfig(existing, gramatrEntry);
+
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+    log(`  Created directory: ${configDir}`);
+  }
+
+  writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  log(`  OK Written to ${configPath}`);
+
+  // Summary
+  log('');
+  log('Installation complete.');
+  log('');
+  log('Restart Claude Desktop to connect to gramatr.');
+  log('');
+  log('What was configured:');
+  log(`  MCP server:  ${serverUrl}`);
+  log(`  Config file: ${configPath}`);
+  log('');
+  log('Note: Claude Desktop is Tier 3 (MCP only). Hooks and status line are not');
+  log('available — use Claude Code or Codex for the full gramatr experience.');
+}
+
+main().catch((err) => {
+  log(`ERROR: ${err.message}`);
+  process.exit(1);
+});

package/desktop/lib/desktop-install-utils.ts

@@ -0,0 +1,70 @@
+import { join } from 'path';
+
+const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
+
+export interface DesktopMcpServerEntry {
+  gramatr: {
+    url: string;
+    headers: {
+      Authorization: string;
+    };
+  };
+}
+
+export interface DesktopConfig {
+  mcpServers?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Returns the Claude Desktop config file path for the given platform.
+ *
+ * macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+ * Windows: %APPDATA%\Claude\claude_desktop_config.json (APPDATA = <home>\AppData\Roaming)
+ */
+export function getDesktopConfigPath(
+  home: string,
+  platform: string = process.platform,
+): string {
+  if (platform === 'win32') {
+    return join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+  }
+
+  // macOS (darwin) and fallback for other platforms
+  return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+}
+
+/**
+ * Build the mcpServers.gramatr entry for Claude Desktop config.
+ * Uses StreamableHTTP transport — Claude Desktop connects directly to the remote URL.
+ */
+export function buildMcpServerEntry(
+  apiKey: string,
+  serverUrl: string = DEFAULT_MCP_URL,
+): DesktopMcpServerEntry {
+  return {
+    gramatr: {
+      url: serverUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+  };
+}
+
+/**
+ * Safely merge a gramatr MCP server entry into an existing Claude Desktop config.
+ * Preserves all other mcpServers and top-level config keys.
+ */
+export function mergeDesktopConfig(
+  existing: DesktopConfig,
+  gramatrEntry: DesktopMcpServerEntry,
+): DesktopConfig {
+  return {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers || {}),
+      ...gramatrEntry,
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gramatr",
-  "version": "0.3.56",
+  "version": "0.3.57",
   "description": "grāmatr — context engineering layer for AI coding agents. Every prompt gets a pre-computed intelligence packet: decision routing, capability audit, behavioral directives, memory pre-load, and ISC scaffolds. Continuity across sessions for Claude Code, Codex, and Gemini CLI.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {