@tightknitai/tightknit 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,167 @@
+# @tightknitai/tightknit
+
+Command-line interface and MCP server for the [Tightknit API](https://docs.tightknit.ai/api-reference/introduction).
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+ (for native `fetch`)
+- A Tightknit API key
+
+### Create an API Key
+
+1. Go to **Studio > Settings > Integrations > API Keys**
+2. Click **Create API key**
+3. Give it a descriptive name (e.g. "CLI")
+4. Select the permissions for the APIs the key needs access to. Enable all permissions the CLI commands you plan to use require:
+   - **Calendar Events** — `events list`, `events get`, `events create`, `events delete`, `events update-attendee`
+   - **Feeds** — `feeds list`, `feeds get`, `feeds posts`
+   - **Posts** — `posts get`
+   - **Members** — `members add` (Enterprise), `members check`
+   - **Messages** — `messages send`
+   - **Groups** — `groups add-member`
+   - **Awards** — `awards assign`
+   - **Search** — `search query` (Beta)
+5. Copy the key (starts with `sk_`) — it is only shown once
+
+### Install and Configure
+
+```bash
+# Via npm
+npx -p @tightknitai/tightknit@alpha tightknit config set api-key sk_your_key_here
+
+# Or from the monorepo root
+pnpm install
+npx tsx packages/tightknit-cli/bin/tightknit.ts config set api-key sk_your_key_here
+```
+
+The API key is stored locally at `~/.config/tightknit/config.json`. Alternatively, set the `TIGHTKNIT_API_KEY` environment variable (takes precedence over stored config).
+
+## Usage
+
+### CLI Commands
+
+```bash
+# Alias for convenience
+alias tightknit="npx tsx packages/tightknit-cli/bin/tightknit.ts"
+
+# Calendar Events
+tightknit events list
+tightknit events list --time-filter upcoming --status published --json
+tightknit events get <event-id>
+tightknit events create --title "Meetup" --description "Join us" --start-date "2025-06-01T18:00:00Z" --end-date "2025-06-01T20:00:00Z"
+tightknit events delete <event-id>
+tightknit events update-attendee <event-id> --email user@example.com --personal-join-link "https://zoom.us/..."
+
+# Awards
+tightknit awards assign <award-uuid> --recipient-email user@example.com
+
+# Feeds & Posts
+tightknit feeds list
+tightknit feeds get <feed-id>
+tightknit feeds posts <feed-id> --sort newest
+tightknit posts get <post-id>
+
+# Members
+tightknit members add --email user@example.com --full-name "Jane Doe"
+tightknit members check user@example.com
+
+# Messages
+tightknit messages send --channel C0123456 --text "Hello from CLI!"
+
+# Groups
+tightknit groups add-member <group-id> --email user@example.com
+
+# Search (Beta)
+tightknit search query "community meetup" --type post
+
+# Config
+tightknit config set api-key <key>
+tightknit config get api-key
+tightknit config set default-output json
+```
+
+Every command supports `--json` for structured JSON output and `--help` for usage info.
+
+### MCP Server (for Claude Code)
+
+The MCP server exposes all CLI commands as tools over STDIO.
+
+Add to your Claude Code MCP config (`.claude/settings.json` or `~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "tightknit": {
+      "command": "npx",
+      "args": ["-p", "@tightknitai/tightknit@alpha", "tightknit-mcp"],
+      "env": {
+        "TIGHTKNIT_API_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Or if installed locally in the monorepo:
+
+```json
+{
+  "mcpServers": {
+    "tightknit": {
+      "command": "npx",
+      "args": ["tsx", "packages/tightknit-cli/src/mcp/server.ts"],
+      "cwd": "/path/to/colombo",
+      "env": {
+        "TIGHTKNIT_API_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+This gives Claude access to 17 tools: `tightknit_events_list`, `tightknit_events_create`, `tightknit_feeds_list`, `tightknit_messages_send`, etc.
+
+**Authentication:** The API key can be provided two ways:
+- **`TIGHTKNIT_API_KEY` env var** (recommended for MCP) — pass it in the MCP config as shown above
+- **`tightknit config set api-key <key>`** — persists to `~/.config/tightknit/config.json`, good for CLI usage
+
+The env var takes precedence if both are set.
+
+## Development
+
+```bash
+# Run tests
+pnpm --filter @tightknitai/tightknit test
+
+# Type check
+pnpm --filter @tightknitai/tightknit typecheck
+
+# Run CLI in dev mode
+npx tsx packages/tightknit-cli/bin/tightknit.ts --help
+```
+
+## API Coverage
+
+All endpoints from the [Tightknit Admin API](https://api.tightknit.ai/doc) (`/admin/v0/`) are supported:
+
+| Method | Path | CLI Command |
+|--------|------|-------------|
+| GET | `/calendar_events` | `events list` |
+| POST | `/calendar_events` | `events create` |
+| GET | `/calendar_events/:id` | `events get` |
+| DELETE | `/calendar_events/:id` | `events delete` |
+| PATCH | `/calendar_events/:id/attendees` | `events update-attendee` |
+| POST | `/awards/:id/assign` | `awards assign` |
+| GET | `/feeds` | `feeds list` |
+| GET | `/feeds/:id` | `feeds get` |
+| GET | `/feeds/:id/posts` | `feeds posts` |
+| GET | `/posts/:id` | `posts get` |
+| POST | `/members` | `members add` |
+| POST | `/members/check` | `members check` |
+| POST | `/messages` | `messages send` |
+| POST | `/groups/:id/members` | `groups add-member` |
+| GET | `/search` | `search query` |
+
+Not yet implemented: `POST /files` (file upload — requires multipart form handling).

package/bin/tightknit-mcp.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const tsx = join(__dirname, "..", "node_modules", ".bin", "tsx");
+const script = join(__dirname, "..", "src", "mcp", "server.ts");
+
+try {
+  execFileSync(tsx, [script], { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/bin/tightknit.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const tsx = join(__dirname, "..", "node_modules", ".bin", "tsx");
+const script = join(__dirname, "tightknit.ts");
+
+try {
+  execFileSync(tsx, [script, ...process.argv.slice(2)], { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/bin/tightknit.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { createProgram } from "../src/cli/index";
+
+const program = createProgram();
+
+// Set version from package.json dynamically
+// Using a static version here to avoid JSON import complexity
+program.version("0.1.0-alpha.0");
+
+program.parseAsync(process.argv).catch(() => {
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tightknitai/tightknit",
+  "version": "0.1.0-alpha.0",
+  "description": "CLI and MCP server for the Tightknit API",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "tightknit": "bin/tightknit.js",
+    "tightknit-mcp": "bin/tightknit-mcp.js"
+  },
+  "exports": {
+    ".": "./src/cli/index.ts",
+    "./mcp": "./src/mcp/server.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx --watch bin/tightknit.ts",
+    "start": "tsx bin/tightknit.ts",
+    "start:mcp": "tsx src/mcp/server.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:unit-silent": "vitest run --reporter=dot",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "conf": "^13.0.1",
+    "tsx": "^4.19.4",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

package/src/cli/awards/assign.ts

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+import { assignAward } from "../../core/client";
+import { printOutput, printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const assignAwardCommand = new Command("assign")
+  .description("Assign an award to a user")
+  .argument("<award-id>", "Award UUID")
+  .requiredOption("--recipient-email <email>", "Recipient email address")
+  .option("--sender-email <email>", "Sender email address")
+  .option("--anonymous", "Send the award anonymously")
+  .option("--json", "Output as JSON")
+  .action(async (awardId: string, opts) => {
+    try {
+      const result = await assignAward(awardId, {
+        recipient: { email: opts.recipientEmail },
+        sender: opts.senderEmail ? { email: opts.senderEmail } : undefined,
+        send_anonymously: opts.anonymous,
+      });
+      if (opts.json) {
+        printOutput(result, { json: true });
+      } else {
+        printSuccess("Award assigned successfully");
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/config/get.ts

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import { getConfigPath, getConfigValue } from "../../core/config";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const getConfigCommand = new Command("get")
+  .description("Get a configuration value")
+  .argument("<key>", "Config key (api-key, community-id, default-output)")
+  .option("--json", "Output as JSON")
+  .option("--show-path", "Show the config file path")
+  .action(async (key: string, opts) => {
+    try {
+      if (opts.showPath) {
+        console.log(getConfigPath());
+        return;
+      }
+      const value = getConfigValue(key);
+      const displayValue = key === "api-key" && value ? `${value.slice(0, 8)}...` : value;
+      if (opts.json) {
+        printOutput({ key, value: displayValue }, { json: true });
+      } else {
+        console.log(displayValue || "(not set)");
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/config/set.ts

@@ -0,0 +1,23 @@
+import { Command } from "commander";
+import { setConfigValue } from "../../core/config";
+import { printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const setConfigCommand = new Command("set")
+  .description("Set a configuration value")
+  .argument("<key>", "Config key (api-key, community-id, default-output)")
+  .argument("<value>", "Config value")
+  .option("--json", "Output as JSON")
+  .action(async (key: string, value: string, opts) => {
+    try {
+      setConfigValue(key, value);
+      if (opts.json) {
+        console.log(JSON.stringify({ success: true, key, value: key === "api-key" ? "***" : value }, null, 2));
+      } else {
+        const displayValue = key === "api-key" ? "***" : value;
+        printSuccess(`Set ${key} = ${displayValue}`);
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/error-handler.ts

@@ -0,0 +1,26 @@
+import { TightknitApiError } from "../core/client";
+import { printError } from "../core/output";
+
+/** Handle errors in CLI commands with consistent formatting */
+export function handleCommandError(error: unknown, json?: boolean): never {
+  if (error instanceof TightknitApiError) {
+    if (json) {
+      console.error(JSON.stringify(error.toJSON(), null, 2));
+    } else {
+      printError(error.message);
+    }
+    process.exit(1);
+  }
+
+  if (error instanceof Error) {
+    if (json) {
+      console.error(JSON.stringify({ error: true, message: error.message }, null, 2));
+    } else {
+      printError(error.message);
+    }
+    process.exit(1);
+  }
+
+  printError("An unknown error occurred");
+  process.exit(1);
+}

package/src/cli/events/create.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { createEvent } from "../../core/client";
+import { printOutput, printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const createEventCommand = new Command("create")
+  .description("Create a new calendar event")
+  .requiredOption("--title <title>", "Event title (3-70 chars)")
+  .requiredOption("--description <text>", "Event description")
+  .requiredOption("--start-date <datetime>", "Start date/time (ISO 8601)")
+  .requiredOption("--end-date <datetime>", "End date/time (ISO 8601)")
+  .option("--location <location>", "Event location")
+  .option("--link <url>", "Event link/URL")
+  .option("--slug <slug>", "URL slug (3-70 chars)")
+  .option("--status <status>", "Status: needs_approval or published", "published")
+  .option("--publish-to-site", "Publish to companion site")
+  .option("--no-publish-to-site", "Do not publish to companion site")
+  .option("--enable-registration", "Enable registration button")
+  .option("--triggers-webhooks", "Trigger webhooks on creation")
+  .option("--json", "Output as JSON")
+  .action(async (opts) => {
+    try {
+      const result = await createEvent({
+        title: opts.title,
+        description: opts.description,
+        start_date: opts.startDate,
+        end_date: opts.endDate,
+        location: opts.location,
+        link: opts.link,
+        slug: opts.slug,
+        status: opts.status,
+        publish_to_site: opts.publishToSite,
+        enable_registration_button: opts.enableRegistration,
+        triggers_webhooks: opts.triggersWebhooks,
+      });
+      if (opts.json) {
+        printOutput(result, { json: true });
+      } else {
+        printSuccess(`Event created: ${result.data.calendar_event_id}`);
+        printOutput(result, {});
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/events/delete.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+import { deleteEvent } from "../../core/client";
+import { printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const deleteEventCommand = new Command("delete")
+  .description("Delete a calendar event")
+  .argument("<id>", "Event ID")
+  .option("--json", "Output as JSON")
+  .action(async (id: string, opts) => {
+    try {
+      await deleteEvent(id);
+      if (opts.json) {
+        console.log(JSON.stringify({ success: true, message: "Event deleted" }, null, 2));
+      } else {
+        printSuccess("Event deleted successfully");
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/events/get.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { getEvent } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const getEventCommand = new Command("get")
+  .description("Get a calendar event by ID")
+  .argument("<id>", "Event ID")
+  .option("--json", "Output as JSON")
+  .action(async (id: string, opts) => {
+    try {
+      const result = await getEvent(id);
+      printOutput(result, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/events/list.ts

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+import { listEvents } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const listEventsCommand = new Command("list")
+  .description("List calendar events")
+  .option("--page <number>", "Page number (0-indexed)", "0")
+  .option("--per-page <number>", "Records per page", "25")
+  .option("--time-filter <filter>", "Filter by time: upcoming or past")
+  .option("--status <status>", "Filter by status: draft, needs_approval, published")
+  .option("--feed-id <id>", "Filter by feed ID")
+  .option("--tag-ids <ids>", "Comma-separated tag UUIDs")
+  .option("--json", "Output as JSON")
+  .action(async (opts) => {
+    try {
+      const result = await listEvents({
+        page: Number(opts.page),
+        per_page: Number(opts.perPage),
+        time_filter: opts.timeFilter,
+        status: opts.status,
+        feed_id: opts.feedId,
+        tag_ids: opts.tagIds,
+      });
+      printOutput(result.data, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/events/update.ts

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import { updateAttendee } from "../../core/client";
+import { printOutput, printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const updateAttendeeCommand = new Command("update-attendee")
+  .description("Update a calendar event attendee")
+  .argument("<event-id>", "Calendar event ID")
+  .requiredOption("--email <email>", "Attendee email (user identifier)")
+  .option("--personal-join-link <url>", "Personal join link for the attendee")
+  .option("--json", "Output as JSON")
+  .action(async (eventId: string, opts) => {
+    try {
+      const result = await updateAttendee(eventId, {
+        user: { email: opts.email },
+        personal_join_link: opts.personalJoinLink,
+      });
+      if (opts.json) {
+        printOutput(result, { json: true });
+      } else {
+        printSuccess("Attendee updated successfully");
+        printOutput(result, {});
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/feeds/get.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { getFeed } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const getFeedCommand = new Command("get")
+  .description("Retrieve a feed by ID")
+  .argument("<feed-id>", "Feed ID")
+  .option("--json", "Output as JSON")
+  .action(async (feedId: string, opts) => {
+    try {
+      const result = await getFeed(feedId);
+      printOutput(result, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/feeds/list.ts

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { listFeeds } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const listFeedsCommand = new Command("list")
+  .description("List feeds")
+  .option("--page <number>", "Page number (0-indexed)", "0")
+  .option("--per-page <number>", "Records per page", "25")
+  .option("--is-unlisted", "Filter to unlisted feeds only")
+  .option("--is-archived", "Filter to archived feeds only")
+  .option("--json", "Output as JSON")
+  .action(async (opts) => {
+    try {
+      const result = await listFeeds({
+        page: Number(opts.page),
+        per_page: Number(opts.perPage),
+        is_unlisted: opts.isUnlisted,
+        is_archived: opts.isArchived,
+      });
+      printOutput(result.data, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/feeds/posts.ts

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { listPostsInFeed } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const listPostsInFeedCommand = new Command("posts")
+  .description("List posts in a feed")
+  .argument("<feed-id>", 'Feed ID or "home" for the Home feed')
+  .option("--page <number>", "Page number (0-indexed)", "0")
+  .option("--per-page <number>", "Records per page", "25")
+  .option("--sort <method>", "Sort: oldest, newest, most-recent-activity")
+  .option("--json", "Output as JSON")
+  .action(async (feedId: string, opts) => {
+    try {
+      const result = await listPostsInFeed(feedId, {
+        page: Number(opts.page),
+        per_page: Number(opts.perPage),
+        sort: opts.sort,
+      });
+      printOutput(result.data, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/groups/add-member.ts

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { addUserToGroup } from "../../core/client";
+import { printOutput, printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const addGroupMemberCommand = new Command("add-member")
+  .description("Add a user to a group")
+  .argument("<group-id>", "Group ID")
+  .requiredOption("--email <email>", "User email address")
+  .option("--json", "Output as JSON")
+  .action(async (groupId: string, opts) => {
+    try {
+      const result = await addUserToGroup(groupId, {
+        user: { email: opts.email },
+      });
+      if (opts.json) {
+        printOutput(result, { json: true });
+      } else {
+        printSuccess("User added to group");
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });