givememy-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 givememy.report contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# givememy-mcp
+
+Local stdio MCP server for publishing private HTML reports to givememy.report.
+
+The server runs on the same machine as your agent, so it can read local files and upload their contents with your givememy.report API key.
+
+## Install
+
+```json
+{
+  "mcpServers": {
+    "givememy": {
+      "command": "npx",
+      "args": ["-y", "givememy-mcp"],
+      "env": {
+        "GIVEMEMY_API_KEY": "gmr_...",
+        "GIVEMEMY_BASE_URL": "https://givememy.report"
+      }
+    }
+  }
+}
+```
+
+For local development from this repo:
+
+```json
+{
+  "mcpServers": {
+    "givememy": {
+      "command": "node",
+      "args": ["/absolute/path/to/givememy.report/mcp/src/index.js"],
+      "env": {
+        "GIVEMEMY_API_KEY": "gmr_..."
+      }
+    }
+  }
+}
+```
+
+Optional environment variables:
+
+- `GIVEMEMY_BASE_URL` defaults to `https://givememy.report`.
+- `GIVEMEMY_MAX_REPORT_BYTES` defaults to `1000000`.
+
+## Tool
+
+### `publish_report`
+
+Arguments:
+
+- `title?: string`
+- `html?: string`
+- `file_path?: string`
+
+Pass either `html` or `file_path`, not both.
+
+Examples an agent can call:
+
+```json
+{ "title": "Weekly revenue", "file_path": "./report.html" }
+```
+
+```json
+{ "title": "Inline report", "html": "<h1>Hello</h1>" }
+```
+
+The tool returns the private Cloudflare Access protected report URL.
+
+## Notes
+
+This is a stdio MCP server, so logs must go to stderr. Do not write human logs to stdout because stdout carries the MCP JSON-RPC protocol.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "givememy-mcp",
+  "version": "0.1.0",
+  "description": "Local stdio MCP server for publishing private HTML reports to givememy.report.",
+  "type": "module",
+  "bin": {
+    "givememy-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "reports",
+    "givememy"
+  ],
+  "license": "MIT",
+  "homepage": "https://givememy.report",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  }
+}

package/src/client.js

@@ -0,0 +1,130 @@
+import { stat, readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+export const DEFAULT_BASE_URL = 'https://givememy.report';
+export const DEFAULT_MAX_REPORT_BYTES = 1_000_000;
+
+export function normalizeBaseUrl(value = DEFAULT_BASE_URL) {
+  const raw = String(value || DEFAULT_BASE_URL).trim();
+  return raw.replace(/\/+$/, '') || DEFAULT_BASE_URL;
+}
+
+export function getConfig(env = process.env) {
+  const apiKey = String(env.GIVEMEMY_API_KEY || '').trim();
+  if (!apiKey) {
+    throw new Error('GIVEMEMY_API_KEY is required');
+  }
+
+  const maxBytes = Number.parseInt(env.GIVEMEMY_MAX_REPORT_BYTES || `${DEFAULT_MAX_REPORT_BYTES}`, 10);
+  return {
+    apiKey,
+    baseUrl: normalizeBaseUrl(env.GIVEMEMY_BASE_URL),
+    maxBytes: Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : DEFAULT_MAX_REPORT_BYTES,
+  };
+}
+
+export async function readReportFile(filePath, maxBytes = DEFAULT_MAX_REPORT_BYTES) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('file_path must be a non-empty string');
+  }
+
+  const absolutePath = resolve(filePath);
+  const info = await stat(absolutePath).catch((error) => {
+    if (error?.code === 'ENOENT') throw new Error(`file not found: ${absolutePath}`);
+    throw error;
+  });
+
+  if (!info.isFile()) {
+    throw new Error(`not a file: ${absolutePath}`);
+  }
+  if (info.size > maxBytes) {
+    throw new Error(`file too large: ${info.size} bytes exceeds ${maxBytes}`);
+  }
+
+  const html = await readFile(absolutePath, 'utf8');
+  return { html, absolutePath, bytes: info.size, title: basename(absolutePath) };
+}
+
+export async function resolveReportInput(args = {}, options = {}) {
+  const maxBytes = options.maxBytes || DEFAULT_MAX_REPORT_BYTES;
+  const hasHtml = typeof args.html === 'string' && args.html.trim().length > 0;
+  const hasFilePath = typeof args.file_path === 'string' && args.file_path.trim().length > 0;
+
+  if (hasHtml && hasFilePath) {
+    throw new Error('provide either html or file_path, not both');
+  }
+  if (!hasHtml && !hasFilePath) {
+    throw new Error('publish_report requires html or file_path');
+  }
+
+  if (hasFilePath) {
+    const file = await readReportFile(args.file_path, maxBytes);
+    return {
+      html: file.html,
+      title: args.title || file.title,
+      source: file.absolutePath,
+      bytes: file.bytes,
+    };
+  }
+
+  return {
+    html: args.html,
+    title: args.title || 'Untitled report',
+    source: 'inline html',
+    bytes: Buffer.byteLength(args.html, 'utf8'),
+  };
+}
+
+export async function publishReport({ title, html }, options = {}) {
+  const apiKey = options.apiKey;
+  if (!apiKey) throw new Error('GIVEMEMY_API_KEY is required');
+  if (!html || !html.trim()) throw new Error('empty_report');
+
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') throw new Error('fetch is not available in this Node runtime');
+
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const response = await fetchImpl(`${baseUrl}/api/reports`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${apiKey}`,
+      'content-type': 'text/html; charset=utf-8',
+      'x-report-title': title || 'Untitled report',
+      'user-agent': 'givememy-mcp/0.1.0',
+    },
+    body: html,
+  });
+
+  const responseText = await response.text();
+  let body = {};
+  try {
+    body = responseText ? JSON.parse(responseText) : {};
+  } catch {
+    body = { error: responseText };
+  }
+
+  if (!response.ok) {
+    const message = body.error || response.statusText || 'upload_failed';
+    throw new Error(`givememy.report upload failed (${response.status}): ${message}`);
+  }
+  if (!body.url) {
+    throw new Error('givememy.report upload response did not include a url');
+  }
+
+  return { title: title || 'Untitled report', url: body.url };
+}
+
+export async function publishFromArgs(args = {}, options = {}) {
+  const config = options.config || getConfig(options.env || process.env);
+  const input = await resolveReportInput(args, { maxBytes: config.maxBytes });
+  const result = await publishReport(
+    { title: input.title, html: input.html },
+    {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      fetchImpl: options.fetchImpl,
+    },
+  );
+
+  return { ...result, source: input.source, bytes: input.bytes };
+}

package/src/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { publishFromArgs } from './client.js';
+
+export function createServer(options = {}) {
+  const server = new McpServer({
+    name: 'givememy',
+    version: '0.1.0',
+  });
+
+  server.registerTool(
+    'publish_report',
+    {
+      description: 'Publish a private HTML report to givememy.report. Pass either html or a local file_path.',
+      inputSchema: {
+        title: z.string().optional().describe('Short report title. Defaults to the filename when file_path is used.'),
+        html: z.string().optional().describe('Complete HTML document or fragment to publish.'),
+        file_path: z.string().optional().describe('Local path to an HTML file to read and publish from this machine.'),
+      },
+    },
+    async (args) => {
+      try {
+        const result = await publishFromArgs(args, options);
+        return {
+          content: [{ type: 'text', text: `Published ${result.url}` }],
+          structuredContent: result,
+        };
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: error?.message || String(error) }],
+        };
+      }
+    },
+  );
+
+  return server;
+}
+
+export async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('givememy MCP server running on stdio');
+}
+
+export function isMainEntry(argv = process.argv) {
+  if (!argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+if (isMainEntry()) {
+  main().catch((error) => {
+    console.error('Fatal error in givememy MCP server:', error);
+    process.exit(1);
+  });
+}