@mseep/telegram-api-mcp 0.1.0

package/dist/trail.d.ts

@@ -0,0 +1,86 @@
+/**
+ * trail.ts — TRAIL Protocol v2.1 (Tracking Records Across Isolated Logs)
+ *
+ * Reference implementation for TypeScript MCP servers.
+ * https://github.com/timoncool/trail-spec
+ *
+ * Usage:
+ *   import { Trail } from "./trail";
+ *   const trail = new Trail("./data", "my-mcp-server");
+ *   await trail.append("civitai:image:12345", "posted", "daily-post", { details: { platform: "telegram" } });
+ *   const { entries, total } = await trail.query({ content_id: "civitai:image:12345" });
+ */
+export interface TrailEntry {
+    version: number;
+    timestamp: string;
+    content_id: string;
+    action: string;
+    requester: string;
+    details?: Record<string, unknown>;
+    trace_id?: string;
+    server?: string;
+    entry_id?: string;
+    caused_by?: string;
+    tags?: string[];
+}
+export interface TrailQuery {
+    /** Filter by content ID (exact match, or prefix ending with ':') */
+    content_id?: string;
+    /** Filter by action (string or array for multi-action filtering) */
+    action?: string | string[];
+    /** Filter by requester */
+    requester?: string;
+    /** Filter by trace ID */
+    trace_id?: string;
+    /** Filter by server name */
+    server?: string;
+    /** Filter entries that have ALL specified tags */
+    tags?: string[];
+    /** ISO 8601 timestamp — only return entries after this time */
+    since?: string;
+    /** Max entries to return, newest first (0 = unlimited, default 50) */
+    limit?: number;
+    /** Number of entries to skip for pagination */
+    offset?: number;
+}
+export interface TrailAppendOptions {
+    details?: Record<string, unknown>;
+    trace_id?: string;
+    server?: string;
+    entry_id?: string;
+    caused_by?: string;
+    tags?: string[];
+}
+export interface TrailQueryResult {
+    entries: TrailEntry[];
+    total: number;
+}
+export interface TrailStats {
+    total_entries: number;
+    by_action: Record<string, number>;
+    unique_content_ids: number;
+    first_entry: string | null;
+    last_entry: string | null;
+}
+export declare class Trail {
+    private static readonly FILENAME;
+    private static readonly VERSION;
+    private readonly filePath;
+    private readonly serverName?;
+    private readonly _mutex;
+    constructor(dataDir: string, server?: string);
+    /**
+     * Append an event to the trail.
+     * Thread-safe — serialized via async mutex.
+     */
+    append(content_id: string, action: string, requester: string, options?: TrailAppendOptions): Promise<TrailEntry>;
+    /** Query the trail with filters. Returns entries newest first + total count. */
+    query(q?: TrailQuery): Promise<TrailQueryResult>;
+    /** Get summary statistics for the trail. */
+    stats(requester?: string, since?: string): Promise<TrailStats>;
+    /** Check if content was already posted. */
+    isUsed(content_id: string, requester?: string): Promise<boolean>;
+    /** Get set of all posted content IDs. */
+    getUsedIds(requester?: string): Promise<Set<string>>;
+}
+//# sourceMappingURL=trail.d.ts.map

package/dist/trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.d.ts","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"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"}

package/dist/trail.js

@@ -0,0 +1,185 @@
+/**
+ * trail.ts — TRAIL Protocol v2.1 (Tracking Records Across Isolated Logs)
+ *
+ * Reference implementation for TypeScript MCP servers.
+ * https://github.com/timoncool/trail-spec
+ *
+ * Usage:
+ *   import { Trail } from "./trail";
+ *   const trail = new Trail("./data", "my-mcp-server");
+ *   await trail.append("civitai:image:12345", "posted", "daily-post", { details: { platform: "telegram" } });
+ *   const { entries, total } = await trail.query({ content_id: "civitai:image:12345" });
+ */
+import { readFile, appendFile, mkdir, access } from "fs/promises";
+import { join, dirname } from "path";
+/**
+ * Async mutex for serializing writes.
+ * Ensures append-only integrity without external dependencies.
+ */
+class Mutex {
+    _queue = [];
+    _locked = false;
+    async acquire() {
+        if (!this._locked) {
+            this._locked = true;
+            return;
+        }
+        return new Promise((resolve) => {
+            this._queue.push(resolve);
+        });
+    }
+    release() {
+        const next = this._queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this._locked = false;
+        }
+    }
+}
+/** Check if content_id filter matches an entry's content_id.
+ *  - Exact match: "civitai:image:12345" matches "civitai:image:12345"
+ *  - Prefix match: "civitai:image:" matches "civitai:image:12345" (prefix must end with ':')
+ */
+function matchContentId(filter, entryId) {
+    if (entryId === filter)
+        return true;
+    if (filter.endsWith(":") && entryId.startsWith(filter))
+        return true;
+    return false;
+}
+export class Trail {
+    static FILENAME = "trail.jsonl";
+    static VERSION = 2;
+    filePath;
+    serverName;
+    _mutex = new Mutex();
+    constructor(dataDir, server) {
+        this.filePath = join(dataDir, Trail.FILENAME);
+        this.serverName = server;
+        mkdir(dirname(this.filePath), { recursive: true }).catch(() => { });
+    }
+    /**
+     * Append an event to the trail.
+     * Thread-safe — serialized via async mutex.
+     */
+    async append(content_id, action, requester, options) {
+        const entry = {
+            version: Trail.VERSION,
+            timestamp: new Date().toISOString(),
+            content_id,
+            action,
+            requester,
+        };
+        const srv = options?.server ?? this.serverName;
+        if (srv)
+            entry.server = srv;
+        if (options?.details)
+            entry.details = options.details;
+        if (options?.trace_id)
+            entry.trace_id = options.trace_id;
+        if (options?.entry_id)
+            entry.entry_id = options.entry_id;
+        if (options?.caused_by)
+            entry.caused_by = options.caused_by;
+        if (options?.tags)
+            entry.tags = options.tags;
+        await this._mutex.acquire();
+        try {
+            await appendFile(this.filePath, JSON.stringify(entry) + "\n", "utf-8");
+        }
+        finally {
+            this._mutex.release();
+        }
+        return entry;
+    }
+    /** Query the trail with filters. Returns entries newest first + total count. */
+    async query(q = {}) {
+        const { content_id, action, requester, trace_id, server, tags, since, limit = 50, offset = 0, } = q;
+        const fileExists = await access(this.filePath)
+            .then(() => true)
+            .catch(() => false);
+        if (!fileExists)
+            return { entries: [], total: 0 };
+        const actionSet = action
+            ? new Set(Array.isArray(action) ? action : [action])
+            : null;
+        const data = await readFile(this.filePath, "utf-8");
+        const lines = data.split("\n").filter(Boolean);
+        const matched = [];
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (content_id && !matchContentId(content_id, entry.content_id))
+                    continue;
+                if (actionSet && !actionSet.has(entry.action))
+                    continue;
+                if (requester && entry.requester !== requester)
+                    continue;
+                if (trace_id && entry.trace_id !== trace_id)
+                    continue;
+                if (server && entry.server !== server)
+                    continue;
+                if (tags && !tags.every((t) => entry.tags?.includes(t)))
+                    continue;
+                if (since && entry.timestamp < since)
+                    continue;
+                matched.push(entry);
+            }
+            catch {
+                continue;
+            }
+        }
+        const total = matched.length;
+        let result = matched.reverse();
+        if (offset)
+            result = result.slice(offset);
+        if (limit)
+            result = result.slice(0, limit);
+        return { entries: result, total };
+    }
+    /** Get summary statistics for the trail. */
+    async stats(requester, since) {
+        const { entries } = await this.query({ requester, since, limit: 0 });
+        const byAction = {};
+        const cids = new Set();
+        const timestamps = [];
+        for (const e of entries) {
+            byAction[e.action] = (byAction[e.action] ?? 0) + 1;
+            cids.add(e.content_id);
+            timestamps.push(e.timestamp);
+        }
+        return {
+            total_entries: entries.length,
+            by_action: byAction,
+            unique_content_ids: cids.size,
+            first_entry: timestamps.length
+                ? timestamps.reduce((a, b) => (a < b ? a : b))
+                : null,
+            last_entry: timestamps.length
+                ? timestamps.reduce((a, b) => (a > b ? a : b))
+                : null,
+        };
+    }
+    /** Check if content was already posted. */
+    async isUsed(content_id, requester) {
+        const { entries } = await this.query({
+            content_id,
+            action: "posted",
+            requester,
+            limit: 1,
+        });
+        return entries.length > 0;
+    }
+    /** Get set of all posted content IDs. */
+    async getUsedIds(requester) {
+        const { entries } = await this.query({
+            action: "posted",
+            requester,
+            limit: 0,
+        });
+        return new Set(entries.map((e) => e.content_id));
+    }
+}
+//# sourceMappingURL=trail.js.map

package/dist/trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.js","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mseep/telegram-api-mcp",
+  "version": "0.1.0",
+  "description": "Ultimate Telegram Bot API v9.6 MCP Server \u2014 169 methods, meta-mode, rate limiting, circuit breaker",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "telegram-api-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "telegram",
+    "bot-api",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "ai-agent",
+    "mseep"
+  ],
+  "author": "timoncool",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json",
+    "smithery.yaml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timoncool/telegram-api-mcp.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.2.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "publisher": "mseep"
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://registry.modelcontextprotocol.io/schema/server.json",
+  "name": "io.github.timoncool/telegram-api-mcp",
+  "description": "Ultimate Telegram Bot API v9.6 MCP server — 169 methods, meta-mode, rate limiting, circuit breaker, Zod validation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timoncool/telegram-api-mcp.git"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "name": "telegram-api-mcp",
+      "type": "npm",
+      "version": "0.1.0",
+      "transport": "stdio"
+    }
+  ]
+}

package/smithery.yaml

@@ -0,0 +1,27 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required:
+      - telegramBotToken
+    properties:
+      telegramBotToken:
+        type: string
+        description: Telegram Bot API token from @BotFather
+      defaultChatId:
+        type: string
+        description: Default chat ID for all tools (optional)
+      metaMode:
+        type: boolean
+        description: Use 2-tool meta mode instead of 169 tools (saves ~99% context tokens)
+        default: false
+  commandFunction: |-
+    (config) => ({
+      command: 'npx',
+      args: ['-y', 'telegram-api-mcp'],
+      env: {
+        TELEGRAM_BOT_TOKEN: config.telegramBotToken,
+        ...(config.defaultChatId ? { TELEGRAM_DEFAULT_CHAT_ID: config.defaultChatId } : {}),
+        ...(config.metaMode ? { TELEGRAM_META_MODE: 'true' } : {})
+      }
+    })