sencre-mcp 1.3.0

package/README.md

@@ -0,0 +1,56 @@
+# sencre-mcp
+
+MCP server for [Sencre](https://todos.sencre.tr) Kanban boards.
+
+## Install
+
+```bash
+npx -y sencre-mcp
+```
+
+Or after `npm i -g sencre-mcp`, run `sencre-mcp`.
+
+## Env
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SENCRE_API_BASE` | no | Default `https://todos.sencre.tr` |
+| `SENCRE_PROJECT_ID` | no | Override bound project |
+| `SENCRE_AGENT_KEY` | no | Admin key (operators); users use pair login |
+
+## First use
+
+1. Add MCP to your client (see https://todos.sencre.tr/mcp).
+2. In chat: `/sencre` or call tool `login` (shown as `sencre_login`).
+3. Browser opens → log in → pick project.
+4. Session: `~/.sencre/session.json`.
+
+## Tools (short names)
+
+`login`, `logout`, `auth_status`, `list_projects`, `get_board`, `list_tasks`, `create_task`, `update_task`, `move_task`, `complete_task`, `whats_left`
+
+With server id `sencre`, clients typically display `sencre_whats_left`, etc.
+
+## Kilo example
+
+```json
+{
+  "mcp": {
+    "sencre": {
+      "type": "local",
+      "command": ["npx", "-y", "sencre-mcp"],
+      "enabled": true,
+      "environment": {
+        "SENCRE_API_BASE": "https://todos.sencre.tr"
+      }
+    }
+  }
+}
+```
+
+From a git checkout (no npm publish):
+
+```json
+"command": ["node", "path/to/mcp/sencre/index.mjs"],
+"cwd": "path/to/mcp/sencre"
+```

package/index.mjs

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+/**
+ * Plain-Node MCP entry (no tsx). Windows / Kilo spawn safe.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { exec } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+function logErr(...args) {
+  console.error("[sencre-mcp]", ...args);
+}
+
+// ——— session (~/.sencre/session.json) ———
+function sessionDir() {
+  return join(homedir(), ".sencre");
+}
+function sessionFile() {
+  return join(sessionDir(), "session.json");
+}
+function loadSession() {
+  try {
+    const p = sessionFile();
+    if (!existsSync(p)) return null;
+    const s = JSON.parse(readFileSync(p, "utf8"));
+    if (!s.token || !s.projectId) return null;
+    if (s.expiresAt && new Date(s.expiresAt).getTime() < Date.now()) {
+      clearSession();
+      return null;
+    }
+    return s;
+  } catch {
+    return null;
+  }
+}
+function saveSession(s) {
+  const d = sessionDir();
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+  writeFileSync(sessionFile(), `${JSON.stringify(s, null, 2)}\n`, "utf8");
+}
+function clearSession() {
+  try {
+    unlinkSync(sessionFile());
+  } catch {
+    /* ignore */
+  }
+}
+
+// ——— project bind ———
+function resolveProjectIdFromCwd(cwd = process.cwd()) {
+  if (process.env.SENCRE_PROJECT_ID?.trim()) {
+    return process.env.SENCRE_PROJECT_ID.trim();
+  }
+  let dir = cwd;
+  for (let i = 0; i < 12; i++) {
+    const p = join(dir, ".sencre.json");
+    if (existsSync(p)) {
+      try {
+        const j = JSON.parse(readFileSync(p, "utf8"));
+        if (j.projectId) return String(j.projectId);
+      } catch {
+        /* ignore */
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+function apiBase() {
+  return (
+    process.env.SENCRE_API_BASE ||
+    loadSession()?.apiBase ||
+    "https://todos.sencre.tr"
+  ).replace(/\/$/, "");
+}
+
+function authKey() {
+  const s = loadSession();
+  if (s?.token) return s.token;
+  return process.env.SENCRE_AGENT_KEY || process.env.APPWRITE_API_KEY || "";
+}
+
+async function agentFetch(path, init) {
+  const token = authKey();
+  if (!token && !path.includes("/pair/")) {
+    throw new Error(
+      "Not logged in. Call the login tool (or /sencre login) first.",
+    );
+  }
+  const res = await fetch(`${apiBase()}${path}`, {
+    ...init,
+    headers: {
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      "Content-Type": "application/json",
+      ...(init?.headers || {}),
+    },
+  });
+  const data = await res.json();
+  if (!res.ok || data.ok === false) {
+    throw new Error(String(data.error || `HTTP ${res.status}`));
+  }
+  return data;
+}
+
+async function publicFetch(path, init) {
+  const res = await fetch(`${apiBase()}${path}`, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(init?.headers || {}),
+    },
+  });
+  const data = await res.json();
+  if (!res.ok || data.ok === false) {
+    throw new Error(String(data.error || `HTTP ${res.status}`));
+  }
+  return data;
+}
+
+function text(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+function pid(explicit) {
+  return (
+    explicit?.trim() ||
+    loadSession()?.projectId ||
+    resolveProjectIdFromCwd() ||
+    process.env.SENCRE_PROJECT_ID?.trim() ||
+    ""
+  );
+}
+
+function requirePid(explicit) {
+  const id = pid(explicit);
+  if (!id) {
+    throw new Error(
+      "No project bound. Call the login tool first (opens browser).",
+    );
+  }
+  return id;
+}
+
+function openBrowser(url) {
+  if (process.platform === "win32") {
+    exec(`cmd /c start "" "${url}"`, () => undefined);
+  } else if (process.platform === "darwin") {
+    exec(`open "${url}"`, () => undefined);
+  } else {
+    exec(`xdg-open "${url}"`, () => undefined);
+  }
+}
+
+async function main() {
+  const server = new McpServer({ name: "sencre", version: "1.3.0" });
+
+  server.tool(
+    "login",
+    "Open browser to log in to Sencre and select a project. No API key needed.",
+    {
+      openBrowser: z.boolean().optional(),
+      timeoutSeconds: z.number().optional(),
+    },
+    async ({ openBrowser: doOpen, timeoutSeconds }) => {
+      const start = await publicFetch("/api/agent/pair/start", {
+        method: "POST",
+        body: "{}",
+      });
+      if (doOpen !== false) openBrowser(start.url);
+      const timeoutMs = (timeoutSeconds ?? 180) * 1000;
+      const began = Date.now();
+      while (Date.now() - began < timeoutMs) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const st = await publicFetch(
+          `/api/agent/pair/status?code=${encodeURIComponent(start.code)}`,
+        );
+        if (st.status === "completed" && st.token && st.projectId) {
+          saveSession({
+            token: st.token,
+            projectId: st.projectId,
+            apiBase: apiBase(),
+          });
+          try {
+            const board = await agentFetch(
+              `/api/agent/board?projectId=${encodeURIComponent(st.projectId)}`,
+            );
+            saveSession({
+              token: st.token,
+              projectId: st.projectId,
+              projectName: String(board.projectName || ""),
+              apiBase: apiBase(),
+            });
+          } catch {
+            /* ok */
+          }
+          return text({
+            ok: true,
+            message: "Logged in and project bound",
+            projectId: st.projectId,
+            sessionFile: sessionFile(),
+            url: start.url,
+          });
+        }
+        if (st.status === "expired" || st.status === "invalid") {
+          throw new Error(`Pair ${st.status}. Run login again.`);
+        }
+      }
+      return text({
+        ok: false,
+        message: "Timed out. Open the URL, finish login, run login again.",
+        url: start.url,
+        code: start.code,
+      });
+    },
+  );
+
+  server.tool("logout", "Clear local Sencre agent session", {}, async () => {
+    clearSession();
+    return text({ ok: true, message: "Session cleared", sessionFile: sessionFile() });
+  });
+
+  server.tool(
+    "auth_status",
+    "Show login status and bound project",
+    {},
+    async () => {
+      const s = loadSession();
+      if (!s) {
+        return text({
+          ok: true,
+          loggedIn: false,
+          message: "Not logged in. Call login.",
+          apiBase: apiBase(),
+        });
+      }
+      return text({
+        ok: true,
+        loggedIn: true,
+        projectId: s.projectId,
+        projectName: s.projectName,
+        sessionFile: sessionFile(),
+        apiBase: apiBase(),
+      });
+    },
+  );
+
+  server.tool(
+    "list_projects",
+    "List projects for logged-in user",
+    {},
+    async () => text(await agentFetch("/api/agent/projects")),
+  );
+
+  server.tool(
+    "get_board",
+    "Get board for bound project",
+    { projectId: z.string().optional() },
+    async ({ projectId }) => {
+      const id = requirePid(projectId);
+      return text(
+        await agentFetch(
+          `/api/agent/board?projectId=${encodeURIComponent(id)}`,
+        ),
+      );
+    },
+  );
+
+  server.tool(
+    "list_tasks",
+    "List tasks",
+    {
+      projectId: z.string().optional(),
+      column: z.string().optional(),
+      type: z.string().optional(),
+      source: z.string().optional(),
+    },
+    async (args) => {
+      const id = requirePid(args.projectId);
+      const q = new URLSearchParams({ projectId: id });
+      if (args.column) q.set("column", args.column);
+      if (args.type) q.set("type", args.type);
+      if (args.source) q.set("source", args.source);
+      return text(await agentFetch(`/api/agent/tasks?${q}`));
+    },
+  );
+
+  server.tool(
+    "create_task",
+    "Create task (source=agent). Optional: type, priority, estimateHours, startAt, dueAt (ISO).",
+    {
+      projectId: z.string().optional(),
+      title: z.string(),
+      description: z.string().optional(),
+      column: z.string().optional(),
+      type: z.enum(["task", "deficiency"]).optional(),
+      priority: z.enum(["none", "low", "medium", "high"]).optional(),
+      estimateHours: z.number().optional(),
+      startAt: z.string().nullable().optional(),
+      dueAt: z.string().nullable().optional(),
+    },
+    async (args) => {
+      const projectId = requirePid(args.projectId);
+      return text(
+        await agentFetch("/api/agent/tasks", {
+          method: "POST",
+          body: JSON.stringify({
+            projectId,
+            title: args.title,
+            description: args.description,
+            column: args.column,
+            type: args.type,
+            priority: args.priority,
+            estimateHours: args.estimateHours,
+            startAt: args.startAt,
+            dueAt: args.dueAt,
+          }),
+        }),
+      );
+    },
+  );
+
+  server.tool(
+    "update_task",
+    "Update task fields including type, priority, estimateHours, startAt, dueAt (null clears dates).",
+    {
+      id: z.string(),
+      title: z.string().optional(),
+      description: z.string().optional(),
+      type: z.enum(["task", "deficiency"]).optional(),
+      priority: z.enum(["none", "low", "medium", "high"]).optional(),
+      estimateHours: z.number().nullable().optional(),
+      startAt: z.string().nullable().optional(),
+      dueAt: z.string().nullable().optional(),
+    },
+    async (args) => {
+      const { id, ...patch } = args;
+      return text(
+        await agentFetch(
+          `/api/agent/tasks/by-id?id=${encodeURIComponent(id)}`,
+          { method: "PATCH", body: JSON.stringify(patch) },
+        ),
+      );
+    },
+  );
+
+  server.tool(
+    "move_task",
+    "Move task to column",
+    { id: z.string(), column: z.string() },
+    async ({ id, column }) =>
+      text(
+        await agentFetch(
+          `/api/agent/tasks/by-id?id=${encodeURIComponent(id)}&action=move`,
+          { method: "POST", body: JSON.stringify({ column }) },
+        ),
+      ),
+  );
+
+  server.tool(
+    "complete_task",
+    "Move task to Done",
+    { id: z.string() },
+    async ({ id }) =>
+      text(
+        await agentFetch(
+          `/api/agent/tasks/by-id?id=${encodeURIComponent(id)}&action=complete`,
+          { method: "POST", body: "{}" },
+        ),
+      ),
+  );
+
+  server.tool(
+    "whats_left",
+    "Open tasks numbered",
+    { projectId: z.string().optional() },
+    async ({ projectId }) => {
+      const id = requirePid(projectId);
+      return text(
+        await agentFetch(
+          `/api/agent/whats-left?projectId=${encodeURIComponent(id)}`,
+        ),
+      );
+    },
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logErr("ready", apiBase());
+}
+
+main().catch((err) => {
+  logErr("fatal", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "sencre-mcp",
+  "version": "1.3.0",
+  "description": "Sencre Kanban MCP server — pair login, board tools for coding agents",
+  "homepage": "https://todos.sencre.tr",
+  "author": "fraunhofer",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "sencre-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "sencre",
+    "kanban",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  }
+}