mcp-pachca 0.1.0

package/src/setup.ts

@@ -0,0 +1,211 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as rl from "node:readline/promises";
+
+const CLIENTS = ["Claude Code", "Cursor"] as const;
+type Client = (typeof CLIENTS)[number];
+
+const SCOPES = ["Project", "Global"] as const;
+type Scope = (typeof SCOPES)[number];
+
+function stderr(msg: string): void {
+  process.stderr.write(msg);
+}
+
+function stderrln(msg: string = ""): void {
+  process.stderr.write(msg + "\n");
+}
+
+// --- Prompt helpers ---
+
+/** Collect all lines from a non-TTY stdin upfront (avoids readline buffering issues). */
+function readAllLines(): Promise<string[]> {
+  return new Promise((resolve) => {
+    const lines: string[] = [];
+    const iface = rl.createInterface({ input: process.stdin });
+    iface.on("line", (line) => lines.push(line));
+    iface.on("close", () => resolve(lines));
+  });
+}
+
+/** Simple line-based prompter backed by a pre-read array (non-TTY). */
+function makePipePrompter(lines: string[]) {
+  let idx = 0;
+  return {
+    ask(question: string): string {
+      stderr(question);
+      if (idx >= lines.length) {
+        stderrln("\nError: not enough input lines.");
+        process.exit(1);
+      }
+      const answer = lines[idx++]!.trim();
+      stderrln(answer);
+      return answer;
+    },
+  };
+}
+
+/** Interactive TTY prompter using readline/promises. */
+function makeTTYPrompter() {
+  const iface = rl.createInterface({ input: process.stdin, output: process.stderr });
+  return {
+    async ask(question: string): Promise<string> {
+      const answer = await iface.question(question);
+      return answer.trim();
+    },
+    close() {
+      iface.close();
+    },
+  };
+}
+
+function askMaskedTTY(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    stderr(question);
+    const buf: string[] = [];
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    const onData = (ch: string): void => {
+      const c = ch.toString();
+      switch (c) {
+        case "\n":
+        case "\r":
+        case "\u0004": // Ctrl-D
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          stderrln();
+          resolve(buf.join(""));
+          break;
+        case "\u0003": // Ctrl-C
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          stderrln("\nAborted.");
+          process.exit(1);
+          break;
+        case "\u007F": // Backspace
+          if (buf.length > 0) {
+            buf.pop();
+            stderr("\b \b");
+          }
+          break;
+        default:
+          buf.push(c);
+          stderr("*");
+      }
+    };
+
+    process.stdin.on("data", onData);
+  });
+}
+
+// --- Choice helper ---
+
+async function askChoice<T extends string>(
+  ask: (q: string) => string | Promise<string>,
+  question: string,
+  choices: readonly T[],
+): Promise<T> {
+  stderrln(question);
+  for (let i = 0; i < choices.length; i++) {
+    stderrln(`  ${i + 1}) ${choices[i]}`);
+  }
+  while (true) {
+    const raw = await ask("Enter choice: ");
+    const n = parseInt(raw, 10);
+    if (n >= 1 && n <= choices.length) {
+      return choices[n - 1]!;
+    }
+    stderrln(`Please enter a number between 1 and ${choices.length}.`);
+  }
+}
+
+// --- Config helpers ---
+
+function resolveConfigPath(client: Client, scope: Scope): string {
+  if (client === "Claude Code") {
+    return scope === "Project"
+      ? path.join(process.cwd(), ".mcp.json")
+      : path.join(os.homedir(), ".mcp.json");
+  }
+  // Cursor
+  return scope === "Project"
+    ? path.join(process.cwd(), ".cursor", "mcp.json")
+    : path.join(os.homedir(), ".cursor", "mcp.json");
+}
+
+function buildEntry(token: string): Record<string, unknown> {
+  return {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "mcp-pachca@latest"],
+    env: {
+      PACHCA_ACCESS_TOKEN: token,
+    },
+  };
+}
+
+// --- Main ---
+
+export async function runSetup(): Promise<void> {
+  stderrln("mcp-pachca setup wizard\n");
+
+  let client: Client;
+  let scope: Scope;
+  let token: string;
+
+  if (process.stdin.isTTY) {
+    const prompter = makeTTYPrompter();
+    client = await askChoice(prompter.ask, "Select your MCP client:", CLIENTS);
+    scope = await askChoice(prompter.ask, "Select config scope:", SCOPES);
+    prompter.close();
+    token = await askMaskedTTY("Enter your PACHCA_ACCESS_TOKEN: ");
+  } else {
+    const lines = await readAllLines();
+    const prompter = makePipePrompter(lines);
+    client = await askChoice(prompter.ask, "Select your MCP client:", CLIENTS);
+    scope = await askChoice(prompter.ask, "Select config scope:", SCOPES);
+    token = prompter.ask("Enter your PACHCA_ACCESS_TOKEN: ");
+  }
+
+  if (!token) {
+    stderrln("Error: token cannot be empty.");
+    process.exit(1);
+  }
+
+  const configPath = resolveConfigPath(client, scope);
+  const dir = path.dirname(configPath);
+
+  // Ensure parent directories exist
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Read existing config or start fresh
+  let config: Record<string, unknown>;
+
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, "utf8");
+    try {
+      config = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      stderrln(`Error: ${configPath} contains malformed JSON. Fix it manually before re-running setup.`);
+      process.exit(1);
+    }
+  } else {
+    config = {};
+  }
+
+  // Merge
+  const servers = (config["mcpServers"] ?? {}) as Record<string, unknown>;
+  servers["pachca"] = buildEntry(token);
+  config["mcpServers"] = servers;
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+
+  stderrln(`\nConfig written to ${configPath}`);
+  stderrln("Restart your MCP client to apply changes.");
+}

package/src/tools/handlers.ts

@@ -0,0 +1,138 @@
+import type { PachcaClient } from "../client.js";
+import type {
+  CursorPaginatedResponse,
+  PagePaginatedResponse,
+  SingleResponse,
+  PachcaUser,
+  PachcaChat,
+  PachcaMessage,
+  PachcaTag,
+  PachcaThread,
+} from "./types.js";
+
+type HandlerFn = (
+  client: PachcaClient,
+  args: Record<string, unknown>,
+) => Promise<unknown>;
+
+async function handleListUsers(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const params: Record<string, string> = {};
+  if (args["query"]) params["query"] = String(args["query"]);
+  if (args["limit"]) params["limit"] = String(args["limit"]);
+  if (args["cursor"]) params["cursor"] = String(args["cursor"]);
+  return client.get<CursorPaginatedResponse<PachcaUser>>("/users", params);
+}
+
+async function handleGetUser(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  return client.get<SingleResponse<PachcaUser>>(`/users/${args["id"]}`);
+}
+
+async function handleListChats(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const params: Record<string, string> = {};
+  if (args["availability"]) params["availability"] = String(args["availability"]);
+  if (args["limit"]) params["limit"] = String(args["limit"]);
+  if (args["cursor"]) params["cursor"] = String(args["cursor"]);
+  if (args["personal"] !== undefined) params["personal"] = String(args["personal"]);
+  if (args["sort"]) {
+    const sort = String(args["sort"]);
+    if (sort.startsWith("id_")) {
+      params["sort[id]"] = sort.replace("id_", "");
+    } else if (sort.startsWith("last_message_at_")) {
+      params["sort[last_message_at]"] = sort.replace("last_message_at_", "");
+    }
+  }
+  return client.get<CursorPaginatedResponse<PachcaChat>>("/chats", params);
+}
+
+async function handleGetChat(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  return client.get<SingleResponse<PachcaChat>>(`/chats/${args["id"]}`);
+}
+
+async function handleGetChatMembers(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const params: Record<string, string> = {};
+  if (args["role"]) params["role"] = String(args["role"]);
+  if (args["limit"]) params["limit"] = String(args["limit"]);
+  if (args["cursor"]) params["cursor"] = String(args["cursor"]);
+  return client.get<CursorPaginatedResponse<PachcaUser>>(
+    `/chats/${args["id"]}/members`,
+    params,
+  );
+}
+
+async function handleListMessages(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const params: Record<string, string> = {
+    chat_id: String(args["chat_id"]),
+  };
+  if (args["per"]) params["per"] = String(args["per"]);
+  if (args["page"]) params["page"] = String(args["page"]);
+  return client.get<PagePaginatedResponse<PachcaMessage>>("/messages", params);
+}
+
+async function handleGetMessage(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  return client.get<SingleResponse<PachcaMessage>>(`/messages/${args["id"]}`);
+}
+
+async function handleListTags(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const params: Record<string, string> = {};
+  if (args["per"]) params["per"] = String(args["per"]);
+  if (args["page"]) params["page"] = String(args["page"]);
+  return client.get<PagePaginatedResponse<PachcaTag>>("/group_tags", params);
+}
+
+async function handleGetThread(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  return client.get<SingleResponse<PachcaThread>>(`/threads/${args["id"]}`);
+}
+
+async function handleSendMessage(
+  client: PachcaClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const message: Record<string, unknown> = {
+    entity_id: args["entity_id"],
+    content: args["content"],
+  };
+  if (args["entity_type"]) message["entity_type"] = args["entity_type"];
+  if (args["parent_message_id"])
+    message["parent_message_id"] = args["parent_message_id"];
+  return client.post<SingleResponse<PachcaMessage>>("/messages", { message });
+}
+
+export const handlerRegistry: Record<string, HandlerFn> = {
+  pachca_list_users: handleListUsers,
+  pachca_get_user: handleGetUser,
+  pachca_list_chats: handleListChats,
+  pachca_get_chat: handleGetChat,
+  pachca_get_chat_members: handleGetChatMembers,
+  pachca_list_messages: handleListMessages,
+  pachca_get_message: handleGetMessage,
+  pachca_list_tags: handleListTags,
+  pachca_get_thread: handleGetThread,
+  pachca_send_message: handleSendMessage,
+};

package/src/tools/schemas.ts

@@ -0,0 +1,193 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+
+export const toolDefinitions: Tool[] = [
+  {
+    name: "pachca_list_users",
+    description:
+      "List users (employees) in Pachca workspace. Supports search by name/email/nickname and cursor-based pagination.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "Search by first_name, last_name, email, phone_number, or nickname",
+        },
+        limit: {
+          type: "number",
+          description: "Results per page (max 50, default 50)",
+        },
+        cursor: {
+          type: "string",
+          description: "Pagination cursor from previous response",
+        },
+      },
+    },
+  },
+  {
+    name: "pachca_get_user",
+    description: "Get a single user by ID.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: { type: "number", description: "User ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "pachca_list_chats",
+    description:
+      "List chats (discussions, channels) in Pachca. Supports filtering and cursor-based pagination.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        availability: {
+          type: "string",
+          enum: ["is_member", "public"],
+          description:
+            "Filter: is_member (default) = chats you belong to, public = public chats",
+        },
+        sort: {
+          type: "string",
+          enum: ["id_asc", "id_desc", "last_message_at_asc", "last_message_at_desc"],
+          description: "Sort order (default: last_message_at_desc)",
+        },
+        personal: {
+          type: "boolean",
+          description: "true = personal chats only, false = group chats only",
+        },
+        limit: {
+          type: "number",
+          description: "Results per page (max 50, default 50)",
+        },
+        cursor: {
+          type: "string",
+          description: "Pagination cursor from previous response",
+        },
+      },
+    },
+  },
+  {
+    name: "pachca_get_chat",
+    description: "Get a single chat by ID.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: { type: "number", description: "Chat ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "pachca_get_chat_members",
+    description:
+      "Get members of a chat. Supports role filtering and cursor-based pagination.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: { type: "number", description: "Chat ID" },
+        role: {
+          type: "string",
+          enum: ["all", "owner", "admin", "editor", "member"],
+          description: "Filter by role (default: all)",
+        },
+        limit: {
+          type: "number",
+          description: "Results per page (max 50, default 50)",
+        },
+        cursor: {
+          type: "string",
+          description: "Pagination cursor from previous response",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "pachca_list_messages",
+    description:
+      "List messages in a chat. Uses page-based pagination. Returns newest messages first by default.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        chat_id: { type: "number", description: "Chat ID (required)" },
+        per: {
+          type: "number",
+          description: "Results per page (max 50, default 25)",
+        },
+        page: {
+          type: "number",
+          description: "Page number (default 1)",
+        },
+      },
+      required: ["chat_id"],
+    },
+  },
+  {
+    name: "pachca_get_message",
+    description: "Get a single message by ID.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: { type: "number", description: "Message ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "pachca_list_tags",
+    description:
+      "List group tags in Pachca workspace. Uses page-based pagination.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        per: {
+          type: "number",
+          description: "Results per page (max 50, default 25)",
+        },
+        page: {
+          type: "number",
+          description: "Page number (default 1)",
+        },
+      },
+    },
+  },
+  {
+    name: "pachca_get_thread",
+    description: "Get thread details by ID.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: { type: "number", description: "Thread ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "pachca_send_message",
+    description:
+      "Send a message to a chat, user, or thread in Pachca.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        entity_id: {
+          type: "number",
+          description: "Target ID: chat ID, user ID, or thread ID",
+        },
+        content: { type: "string", description: "Message text" },
+        entity_type: {
+          type: "string",
+          enum: ["discussion", "user", "thread"],
+          description:
+            "Target type: discussion (chat, default), user (DM), thread",
+        },
+        parent_message_id: {
+          type: "number",
+          description: "Reply to a specific message ID",
+        },
+      },
+      required: ["entity_id", "content"],
+    },
+  },
+];

package/src/tools/types.ts

@@ -0,0 +1,106 @@
+export interface PachcaUser {
+  id: number;
+  first_name: string;
+  last_name: string;
+  nickname: string;
+  email: string;
+  phone_number: string | null;
+  department: string | null;
+  title: string | null;
+  role: "admin" | "user" | "multi_guest";
+  suspended: boolean;
+  invite_status: "confirmed" | "sent";
+  list_tags: string[];
+  custom_properties: PachcaCustomProperty[];
+  user_status: PachcaUserStatus | null;
+  bot: boolean;
+  sso: boolean;
+  created_at: string;
+  last_activity_at: string | null;
+  time_zone: string;
+  image_url: string | null;
+}
+
+export interface PachcaCustomProperty {
+  id: number;
+  name: string;
+  data_type: string;
+  value: string;
+}
+
+export interface PachcaUserStatus {
+  emoji: string;
+  title: string;
+  expires_at: string | null;
+}
+
+export interface PachcaChat {
+  id: number;
+  name: string;
+  owner_id: number;
+  created_at: string;
+  member_ids: number[];
+  group_tag_ids: number[];
+  channel: boolean;
+  personal: boolean;
+  public: boolean;
+  last_message_at: string | null;
+  meet_room_url: string | null;
+}
+
+export interface PachcaMessage {
+  id: number;
+  entity_type: "discussion" | "thread" | "user";
+  entity_id: number;
+  chat_id: number;
+  content: string;
+  user_id: number;
+  created_at: string;
+  url: string;
+  files: PachcaFile[];
+  thread: PachcaThreadRef | null;
+  parent_message_id: number | null;
+}
+
+export interface PachcaFile {
+  id: number;
+  key: string;
+  name: string;
+  file_type: "file" | "image";
+  url: string;
+}
+
+export interface PachcaThreadRef {
+  id: number;
+  chat_id: number;
+  message_id: number;
+  message_chat_id: number;
+  updated_at: string;
+}
+
+export interface PachcaThread {
+  id: number;
+  chat_id: number;
+  message_id: number;
+  message_chat_id: number;
+  updated_at: string;
+}
+
+export interface PachcaTag {
+  id: number;
+  name: string;
+  users_count: number;
+}
+
+export interface CursorPaginatedResponse<T> {
+  meta: { paginate: { next_page: string | null } };
+  data: T[];
+}
+
+export interface PagePaginatedResponse<T> {
+  data: T[];
+}
+
+export interface SingleResponse<T> {
+  data: T;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "isolatedModules": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}