systematics-mcp 1.0.2 → 1.1.1

package/README.md

@@ -4,26 +4,20 @@ Claude Code MCP server for the [Systematics](https://app.dovito.com) platform by
 
 ## Quick Start
 
-### 1. Add to Claude Code
-
-Add this to your project or global `.mcp.json` file:
-
-```json
-{
-  "mcpServers": {
-    "systematics": {
-      "command": "npx",
-      "args": ["-y", "systematics-mcp"]
-    }
-  }
-}
+### 1. Install and Register
+
+```bash
+npm install -g systematics-mcp
+claude mcp add systematics --scope user -- systematics-mcp
 ```
 
+Use `--scope user` for global access across all projects, or `--scope project` for a single project.
+
 ### 2. Authenticate
 
-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.
+Restart Claude Code, then use `/mcp` to verify Systematics shows as "Connected." The first time you use a Systematics tool, run the `authenticate` tool to sign in via your browser. 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.
+That's it. No API keys, no repo access, no manual config files.
 
 ## How It Works
 

package/dist/index.js

@@ -21,35 +21,81 @@ function getToken() {
 function handleAuthError() {
     clearStoredToken();
     api = null;
+    authenticated = false;
 }
-// Lazy API client -- initialized on first use or after auth
+// Track auth state
+let authenticated = false;
 let api = null;
 const token = getToken();
 if (token) {
     api = new ApiClient(BASE_URL, token, handleAuthError);
+    authenticated = true;
 }
 /**
- * Get the API client, triggering browser auth if not yet authenticated.
- * Returns the client or throws with an auth-required message.
+ * Get the API client. Returns null if not authenticated.
+ * Does NOT auto-trigger browser auth -- use the authenticate tool instead.
  */
-async function getApi() {
-    if (api)
-        return api;
-    const newToken = await authenticateViaBrowser(BASE_URL);
-    api = new ApiClient(BASE_URL, newToken, handleAuthError);
+function getApi() {
     return api;
 }
+/**
+ * Returns an auth-required response for tools when not authenticated.
+ */
+function authRequiredResponse() {
+    return {
+        content: [{
+                type: "text",
+                text: "Not authenticated with Systematics. Please run the 'authenticate' tool first to connect your account.",
+            }],
+        isError: true,
+    };
+}
 const server = new McpServer({
-    name: "dovito",
-    version: "1.0.0",
+    name: "systematics",
+    version: "1.0.2",
+});
+// ── Authentication ────────────────────────────────────────────────────────
+server.tool("authenticate", `Sign in to Systematics via your browser. ${authenticated ? "(Currently authenticated)" : "(Not authenticated -- run this first)"}`, {}, async () => {
+    if (authenticated && api) {
+        return { content: [{ type: "text", text: "Already authenticated with Systematics. To re-authenticate, run 'reauthenticate'." }] };
+    }
+    try {
+        const newToken = await authenticateViaBrowser(BASE_URL);
+        api = new ApiClient(BASE_URL, newToken, handleAuthError);
+        authenticated = true;
+        return { content: [{ type: "text", text: "Successfully authenticated with Systematics. You can now use all other tools." }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Authentication failed: ${err instanceof Error ? err.message : "Unknown error"}` }], isError: true };
+    }
+});
+server.tool("reauthenticate", "Clear stored credentials and sign in again with a new token", {}, async () => {
+    clearStoredToken();
+    api = null;
+    authenticated = false;
+    try {
+        const newToken = await authenticateViaBrowser(BASE_URL);
+        api = new ApiClient(BASE_URL, newToken, handleAuthError);
+        authenticated = true;
+        return { content: [{ type: "text", text: "Re-authenticated successfully with a new token." }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Authentication failed: ${err instanceof Error ? err.message : "Unknown error"}` }], isError: true };
+    }
 });
 // ── Businesses ─────────────────────────────────────────────────────────────
 server.tool("list_businesses", "List all businesses (clients) in the Dovito portal", {}, async () => {
-    const data = await (await getApi()).get("/api/businesses");
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get(`/api/businesses/${businessId}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.get(`/api/businesses/${businessId}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("create_business", "Create a new business (client company)", {
@@ -62,7 +108,10 @@ 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 (await getApi()).post("/api/businesses", params);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.post("/api/businesses", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_business", "Update an existing business", {
@@ -77,16 +126,25 @@ 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 (await getApi()).patch(`/api/businesses/${businessId}`, updates);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get("/api/projects");
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get(`/api/projects/${projectId}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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", {
@@ -100,7 +158,10 @@ 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 (await getApi()).post("/api/projects", params);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.post("/api/admin/projects", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_project", "Update an existing project", {
@@ -113,7 +174,10 @@ 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 (await getApi()).patch(`/api/projects/${projectId}`, updates);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.patch(`/api/admin/projects/${projectId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Tasks ──────────────────────────────────────────────────────────────────
@@ -124,11 +188,17 @@ 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 (await getApi()).get(`/api/tasks${query}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get(`/api/projects/${projectId}/tasks`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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", {
@@ -140,7 +210,10 @@ 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 (await getApi()).post(`/api/projects/${projectId}/tasks`, body);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.post(`/api/projects/${projectId}/tasks`, body);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_task", "Update an existing task", {
@@ -154,7 +227,10 @@ 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 (await getApi()).patch(`/api/projects/${projectId}/tasks/${taskId}`, updates);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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)", {
@@ -162,13 +238,19 @@ 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 (await getApi()).delete(`/api/projects/${projectId}/tasks/${taskId}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    await client.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 (await getApi()).get(`/api/catalog${query}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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", {
@@ -179,7 +261,10 @@ 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 (await getApi()).post("/api/catalog", params);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.post("/api/catalog", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_catalog_item", "Update a catalog item", {
@@ -192,7 +277,10 @@ server.tool("update_catalog_item", "Update a catalog item", {
     unit: z.string().optional(),
     isActive: z.boolean().optional(),
 }, async ({ itemId, ...updates }) => {
-    const data = await (await getApi()).patch(`/api/catalog/${itemId}`, updates);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.patch(`/api/catalog/${itemId}`, updates);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 // ── Users ──────────────────────────────────────────────────────────────────
@@ -206,12 +294,18 @@ server.tool("list_users", "List all users in the portal", {
     if (includeStaff)
         params.set("includeStaff", "true");
     const query = params.toString() ? `?${params}` : "";
-    const data = await (await getApi()).get(`/api/admin/users${query}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get(`/api/projects/${projectId}/proposals`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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", {
@@ -225,12 +319,18 @@ 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 (await getApi()).post(`/api/projects/${projectId}/proposals`, body);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get("/api/messages");
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.get("/api/messages");
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("get_conversation_messages", "Get messages in a conversation thread", {
@@ -241,7 +341,10 @@ 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 (await getApi()).get(`/api/messages/${conversationId}${query}`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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)", {
@@ -251,7 +354,10 @@ 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 (await getApi()).post("/api/conversations", params);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.post("/api/conversations", params);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("send_message", "Send a message in a conversation", {
@@ -259,12 +365,18 @@ 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 (await getApi()).post(`/api/messages/${conversationId}`, body);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get(`/api/projects/${projectId}/deliverables`);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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", {
@@ -273,7 +385,10 @@ 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 (await getApi()).post(`/api/projects/${projectId}/deliverables`, body);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.post(`/api/projects/${projectId}/deliverables`, body);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("update_deliverable", "Update a deliverable", {
@@ -283,12 +398,18 @@ 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 (await getApi()).patch(`/api/projects/${projectId}/deliverables/${deliverableId}`, updates);
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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 (await getApi()).get("/api/admin/applications");
+    const client = getApi();
+    if (!client)
+        return authRequiredResponse();
+    const data = await client.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.2",
+  "version": "1.1.1",
   "type": "module",
   "description": "Claude Code MCP server for the Systematics platform by Dovito Business Solutions",
   "bin": {