systematics-mcp 1.0.0 → 1.0.2

package/README.md

@@ -6,7 +6,7 @@ Claude Code MCP server for the [Systematics](https://app.dovito.com) platform by
 
 ### 1. Add to Claude Code
 
-Add this to your `~/.claude/settings.json`:
+Add this to your project or global `.mcp.json` file:
 
 ```json
 {
@@ -21,12 +21,14 @@ Add this to your `~/.claude/settings.json`:
 
 ### 2. Authenticate
 
-Start a Claude Code session. The first time you use a Systematics tool, your browser will open to sign in. Click **Authorize Claude Code** and you're connected. Your token is saved locally at `~/.systematics/token` and reused automatically for 90 days.
+Restart Claude Code, then use `/mcp` to see Systematics listed. The first time you use a Systematics tool, your browser will open to sign in. Click **Authorize Claude Code** and you're connected. Your token is saved locally at `~/.systematics/token` and reused automatically for 90 days.
 
 That's it. No API keys, no repo access, no manual setup.
 
 ## How It Works
 
+- The MCP server starts silently -- no browser popup on launch
+- Authentication only triggers when you actually use a Systematics tool
 - You sign in with your normal Systematics account (Google or email)
 - Claude Code gets the same permissions as your account
 - Clients see only their business data
@@ -61,9 +63,32 @@ That's it. No API keys, no repo access, no manual setup.
 | `SYSTEMATICS_TOKEN` | - | Skip browser auth by providing a token directly |
 | `DOVITO_APP_URL` | `https://app.dovito.com` | Custom app URL (for self-hosted instances) |
 
+## Development
+
+The MCP server lives in `mcp-server/` inside the [app.dovito.com](https://github.com/dovito-dev/app.dovito.com) repository.
+
+```bash
+cd mcp-server
+npm install
+npm run dev    # Run locally with tsx
+npm run build  # Compile TypeScript
+```
+
+### CI/CD
+
+Publishing to npm is automated via GitHub Actions. To release a new version:
+
+1. Make changes in `mcp-server/`
+2. Bump the version in `mcp-server/package.json`
+3. Push to `main`
+4. GitHub Actions builds and publishes to npm automatically
+
+If you push without bumping the version, the workflow skips the publish step.
+
 ## Security
 
-- Tokens are hashed before storage in the database
-- Token file is stored with `0o600` permissions (owner-only)
+- Tokens are hashed (HMAC-SHA256) before storage in the database
+- Token file is stored with `0o600` permissions in a `0o700` directory
 - Auth callback uses POST (token never appears in URLs or browser history)
 - All API calls go through the same validation and rate limiting as the web UI
+- SSRF prevention: `DOVITO_APP_URL` is validated against an allowlist before any network call

package/dist/api-client.d.ts

@@ -5,7 +5,8 @@
 export declare class ApiClient {
     private baseUrl;
     private token;
-    constructor(baseUrl: string, token: string);
+    private onAuthError?;
+    constructor(baseUrl: string, token: string, onAuthError?: () => void);
     private request;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;

package/dist/api-client.js

@@ -5,9 +5,11 @@
 export class ApiClient {
     baseUrl;
     token;
-    constructor(baseUrl, token) {
+    onAuthError;
+    constructor(baseUrl, token, onAuthError) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
         this.token = token;
+        this.onAuthError = onAuthError;
     }
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
@@ -21,6 +23,9 @@ export class ApiClient {
             body: body ? JSON.stringify(body) : undefined,
         });
         if (!res.ok) {
+            if (res.status === 401 && this.onAuthError) {
+                this.onAuthError();
+            }
             const text = await res.text();
             let msg;
             try {
@@ -29,7 +34,6 @@ export class ApiClient {
             catch {
                 msg = text;
             }
-            // Truncate error message to avoid leaking internal details
             const safeMsg = msg.length > 500 ? msg.slice(0, 500) + "..." : msg;
             throw new Error(`API ${method} ${path} returned ${res.status}: ${safeMsg}`);
         }

package/dist/auth.d.ts

@@ -2,6 +2,10 @@
  * Get the stored personal access token, or null if not found/expired.
  */
 export declare function getStoredToken(): string | null;
+/**
+ * Delete the stored token (e.g. on 401 so re-auth triggers next time).
+ */
+export declare function clearStoredToken(): void;
 /**
  * Run the browser-based authentication flow:
  * 1. Start a temporary local HTTP server

package/dist/auth.js

@@ -21,6 +21,17 @@ export function getStoredToken() {
         return null;
     }
 }
+/**
+ * Delete the stored token (e.g. on 401 so re-auth triggers next time).
+ */
+export function clearStoredToken() {
+    try {
+        if (existsSync(TOKEN_FILE)) {
+            writeFileSync(TOKEN_FILE, "", { mode: 0o600 });
+        }
+    }
+    catch { /* ignore */ }
+}
 /**
  * Save a token to the local config directory.
  */
@@ -100,7 +111,7 @@ export async function authenticateViaBrowser(appUrl) {
   <div class="card">
     <div class="check"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6L9 17l-5-5"/></svg></div>
     <h1>Connected to Systematics</h1>
-    <p>You can close this tab and return to Claude Code.</p>
+    <p>You can close this tab and return to your application.</p>
   </div>
 </body>
 </html>`);
@@ -126,7 +137,8 @@ export async function authenticateViaBrowser(appUrl) {
                 return;
             }
             const callbackUrl = `http://127.0.0.1:${addr.port}/callback`;
-            const authUrl = `${appUrl}/auth/mcp?callback=${encodeURIComponent(callbackUrl)}`;
+            const clientName = process.env.MCP_CLIENT_NAME || "Claude Code";
+            const authUrl = `${appUrl}/auth/mcp?callback=${encodeURIComponent(callbackUrl)}&client=${encodeURIComponent(clientName)}`;
             // Write to stderr so Claude Code can show it (stdout is MCP protocol)
             process.stderr.write(`\nOpening browser to authenticate with Systematics...\n`);
             process.stderr.write(`If the browser doesn't open, visit: ${authUrl}\n\n`);

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ApiClient } from "./api-client.js";
-import { getStoredToken, authenticateViaBrowser } from "./auth.js";
+import { getStoredToken, authenticateViaBrowser, clearStoredToken } from "./auth.js";
 // Validate DOVITO_APP_URL against allowed hostnames to prevent SSRF
 const rawUrl = process.env.DOVITO_APP_URL || "https://app.dovito.com";
 const parsedUrl = new URL(rawUrl);
@@ -13,32 +13,43 @@ if (!ALLOWED_HOSTS.includes(parsedUrl.hostname)) {
     process.exit(1);
 }
 const BASE_URL = parsedUrl.origin;
-// Resolve token: env var > stored token > browser auth flow
-async function resolveToken() {
-    // 1. Explicit env var (highest priority)
-    const envToken = process.env.SYSTEMATICS_TOKEN || process.env.MCP_API_KEY;
-    if (envToken)
-        return envToken;
-    // 2. Previously stored token from browser auth
-    const stored = getStoredToken();
-    if (stored)
-        return stored;
-    // 3. Run browser auth flow
-    return authenticateViaBrowser(BASE_URL);
+// Resolve token silently (env var or stored file only -- no browser popup)
+function getToken() {
+    return process.env.SYSTEMATICS_TOKEN || process.env.MCP_API_KEY || getStoredToken();
+}
+// On 401, clear stored token so next call re-authenticates
+function handleAuthError() {
+    clearStoredToken();
+    api = null;
+}
+// Lazy API client -- initialized on first use or after auth
+let api = null;
+const token = getToken();
+if (token) {
+    api = new ApiClient(BASE_URL, token, handleAuthError);
+}
+/**
+ * Get the API client, triggering browser auth if not yet authenticated.
+ * Returns the client or throws with an auth-required message.
+ */
+async function getApi() {
+    if (api)
+        return api;
+    const newToken = await authenticateViaBrowser(BASE_URL);
+    api = new ApiClient(BASE_URL, newToken, handleAuthError);
+    return api;
 }
-const token = await resolveToken();
-const api = new ApiClient(BASE_URL, token);
 const server = new McpServer({
     name: "dovito",
     version: "1.0.0",
 });
 // ── Businesses ─────────────────────────────────────────────────────────────
 server.tool("list_businesses", "List all businesses (clients) in the Dovito portal", {}, async () => {
-    const data = await api.get("/api/businesses");
+    const data = await (await getApi()).get("/api/businesses");
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("get_business", "Get a single business by ID", { businessId: z.string().describe("Business UUID") }, async ({ businessId }) => {
-    const data = await api.get(`/api/businesses/${businessId}`);
+    const data = await (await getApi()).get(`/api/businesses/${businessId}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_business", "Create a new business (client company)", {
@@ -51,7 +62,7 @@ server.tool("create_business", "Create a new business (client company)", {
     status: z.enum(["pending", "approved", "active"]).optional(),
     ownerUserId: z.string().optional().describe("User ID of the business owner, or 'none'"),
 }, async (params) => {
-    const data = await api.post("/api/businesses", params);
+    const data = await (await getApi()).post("/api/businesses", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_business", "Update an existing business", {
@@ -66,16 +77,16 @@ server.tool("update_business", "Update an existing business", {
     status: z.enum(["pending", "approved", "active"]).optional(),
     assignedAmId: z.string().nullable().optional().describe("Account manager user ID"),
 }, async ({ businessId, ...updates }) => {
-    const data = await api.patch(`/api/businesses/${businessId}`, updates);
+    const data = await (await getApi()).patch(`/api/businesses/${businessId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Projects ───────────────────────────────────────────────────────────────
 server.tool("list_projects", "List all projects across businesses", {}, async () => {
-    const data = await api.get("/api/projects");
+    const data = await (await getApi()).get("/api/projects");
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("get_project", "Get a single project by ID", { projectId: z.string().describe("Project UUID") }, async ({ projectId }) => {
-    const data = await api.get(`/api/projects/${projectId}`);
+    const data = await (await getApi()).get(`/api/projects/${projectId}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_project", "Create a new project under a business", {
@@ -89,7 +100,7 @@ server.tool("create_project", "Create a new project under a business", {
     startDate: z.string().optional().describe("ISO date"),
     estimatedEndDate: z.string().optional().describe("ISO date"),
 }, async (params) => {
-    const data = await api.post("/api/projects", params);
+    const data = await (await getApi()).post("/api/projects", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_project", "Update an existing project", {
@@ -102,7 +113,7 @@ server.tool("update_project", "Update an existing project", {
     startDate: z.string().optional().describe("ISO date"),
     estimatedEndDate: z.string().optional().describe("ISO date"),
 }, async ({ projectId, ...updates }) => {
-    const data = await api.patch(`/api/projects/${projectId}`, updates);
+    const data = await (await getApi()).patch(`/api/projects/${projectId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Tasks ──────────────────────────────────────────────────────────────────
@@ -113,11 +124,11 @@ server.tool("list_tasks", "List all tasks, optionally filtered by business", {
     if (businessId)
         params.set("businessId", businessId);
     const query = params.toString() ? `?${params}` : "";
-    const data = await api.get(`/api/tasks${query}`);
+    const data = await (await getApi()).get(`/api/tasks${query}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("list_project_tasks", "List tasks for a specific project", { projectId: z.string().describe("Project UUID") }, async ({ projectId }) => {
-    const data = await api.get(`/api/projects/${projectId}/tasks`);
+    const data = await (await getApi()).get(`/api/projects/${projectId}/tasks`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_task", "Create a task under a project", {
@@ -129,7 +140,7 @@ server.tool("create_task", "Create a task under a project", {
     startDate: z.string().optional().describe("ISO date"),
     dueDate: z.string().optional().describe("ISO date"),
 }, async ({ projectId, ...body }) => {
-    const data = await api.post(`/api/projects/${projectId}/tasks`, body);
+    const data = await (await getApi()).post(`/api/projects/${projectId}/tasks`, body);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_task", "Update an existing task", {
@@ -143,7 +154,7 @@ server.tool("update_task", "Update an existing task", {
     startDate: z.string().optional().describe("ISO date"),
     dueDate: z.string().optional().describe("ISO date"),
 }, async ({ projectId, taskId, ...updates }) => {
-    const data = await api.patch(`/api/projects/${projectId}/tasks/${taskId}`, updates);
+    const data = await (await getApi()).patch(`/api/projects/${projectId}/tasks/${taskId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("delete_task", "Delete a task (set confirm=true to proceed)", {
@@ -151,13 +162,13 @@ server.tool("delete_task", "Delete a task (set confirm=true to proceed)", {
     taskId: z.string().describe("Task UUID"),
     confirm: z.literal(true).describe("Must be true to confirm deletion"),
 }, async ({ projectId, taskId }) => {
-    await api.delete(`/api/projects/${projectId}/tasks/${taskId}`);
+    await (await getApi()).delete(`/api/projects/${projectId}/tasks/${taskId}`);
     return { content: [{ type: "text", text: "Task deleted." }] };
 });
 // ── Catalog ────────────────────────────────────────────────────────────────
 server.tool("list_catalog_items", "List all items in the line item catalog", { all: z.boolean().optional().describe("Include inactive items") }, async ({ all }) => {
     const query = all ? "?all=true" : "";
-    const data = await api.get(`/api/catalog${query}`);
+    const data = await (await getApi()).get(`/api/catalog${query}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_catalog_item", "Add an item to the line item catalog", {
@@ -168,7 +179,7 @@ server.tool("create_catalog_item", "Add an item to the line item catalog", {
     unitAmount: z.number().int().min(0).describe("Price in cents"),
     unit: z.string().optional().describe("hour, each, month, project, per seat, quarterly, annual"),
 }, async (params) => {
-    const data = await api.post("/api/catalog", params);
+    const data = await (await getApi()).post("/api/catalog", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_catalog_item", "Update a catalog item", {
@@ -181,7 +192,7 @@ server.tool("update_catalog_item", "Update a catalog item", {
     unit: z.string().optional(),
     isActive: z.boolean().optional(),
 }, async ({ itemId, ...updates }) => {
-    const data = await api.patch(`/api/catalog/${itemId}`, updates);
+    const data = await (await getApi()).patch(`/api/catalog/${itemId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Users ──────────────────────────────────────────────────────────────────
@@ -195,12 +206,12 @@ server.tool("list_users", "List all users in the portal", {
     if (includeStaff)
         params.set("includeStaff", "true");
     const query = params.toString() ? `?${params}` : "";
-    const data = await api.get(`/api/admin/users${query}`);
+    const data = await (await getApi()).get(`/api/admin/users${query}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Proposals ──────────────────────────────────────────────────────────────
 server.tool("list_proposals", "List proposals for a project", { projectId: z.string().describe("Project UUID") }, async ({ projectId }) => {
-    const data = await api.get(`/api/projects/${projectId}/proposals`);
+    const data = await (await getApi()).get(`/api/projects/${projectId}/proposals`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_proposal", "Create a proposal (quote) for a project", {
@@ -214,12 +225,12 @@ server.tool("create_proposal", "Create a proposal (quote) for a project", {
     })).describe("Line items for the proposal"),
     expiresAt: z.string().optional().describe("ISO date for expiration"),
 }, async ({ projectId, ...body }) => {
-    const data = await api.post(`/api/projects/${projectId}/proposals`, body);
+    const data = await (await getApi()).post(`/api/projects/${projectId}/proposals`, body);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Conversations & Messages ───────────────────────────────────────────────
 server.tool("list_conversations", "List all conversations (message threads) for the service account", {}, async () => {
-    const data = await api.get("/api/messages");
+    const data = await (await getApi()).get("/api/messages");
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("get_conversation_messages", "Get messages in a conversation thread", {
@@ -230,7 +241,7 @@ server.tool("get_conversation_messages", "Get messages in a conversation thread"
     if (cursor)
         params.set("cursor", cursor);
     const query = params.toString() ? `?${params}` : "";
-    const data = await api.get(`/api/messages/${conversationId}${query}`);
+    const data = await (await getApi()).get(`/api/messages/${conversationId}${query}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_conversation", "Create a new conversation (DM, group, project, or business thread)", {
@@ -240,7 +251,7 @@ server.tool("create_conversation", "Create a new conversation (DM, group, projec
     projectId: z.string().optional().describe("Project UUID (for project type)"),
     businessId: z.string().optional().describe("Business UUID (for business type)"),
 }, async (params) => {
-    const data = await api.post("/api/conversations", params);
+    const data = await (await getApi()).post("/api/conversations", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("send_message", "Send a message in a conversation", {
@@ -248,12 +259,12 @@ server.tool("send_message", "Send a message in a conversation", {
     content: z.string().describe("Message content (1-10000 chars)"),
     parentMessageId: z.string().optional().describe("Reply to a specific message"),
 }, async ({ conversationId, ...body }) => {
-    const data = await api.post(`/api/messages/${conversationId}`, body);
+    const data = await (await getApi()).post(`/api/messages/${conversationId}`, body);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Deliverables ───────────────────────────────────────────────────────────
 server.tool("list_deliverables", "List deliverables for a project", { projectId: z.string().describe("Project UUID") }, async ({ projectId }) => {
-    const data = await api.get(`/api/projects/${projectId}/deliverables`);
+    const data = await (await getApi()).get(`/api/projects/${projectId}/deliverables`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_deliverable", "Create a deliverable under a project", {
@@ -262,7 +273,7 @@ server.tool("create_deliverable", "Create a deliverable under a project", {
     description: z.string().optional(),
     status: z.enum(["pending", "in_progress", "completed"]).optional(),
 }, async ({ projectId, ...body }) => {
-    const data = await api.post(`/api/projects/${projectId}/deliverables`, body);
+    const data = await (await getApi()).post(`/api/projects/${projectId}/deliverables`, body);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_deliverable", "Update a deliverable", {
@@ -272,12 +283,12 @@ server.tool("update_deliverable", "Update a deliverable", {
     description: z.string().optional(),
     status: z.enum(["pending", "in_progress", "completed"]).optional(),
 }, async ({ projectId, deliverableId, ...updates }) => {
-    const data = await api.patch(`/api/projects/${projectId}/deliverables/${deliverableId}`, updates);
+    const data = await (await getApi()).patch(`/api/projects/${projectId}/deliverables/${deliverableId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Applications (Pipeline) ───────────────────────────────────────────────
 server.tool("list_applications", "List all applications in the pipeline", {}, async () => {
-    const data = await api.get("/api/admin/applications");
+    const data = await (await getApi()).get("/api/admin/applications");
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Start server ───────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systematics-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "Claude Code MCP server for the Systematics platform by Dovito Business Solutions",
   "bin": {