@latentforce/shift 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# shift-mcp
+
+A minimal utility server built for the Model Context Protocol (MCP). It exposes tools that call the Shift Lite webapp backend for file summary, dependencies, and blast radius (using the project's knowledge graph).
+
+## Environment variables
+
+- **`SHIFT_PROJECT_ID`** (optional if you pass per call): The default Shift Lite project UUID. If set, all tools use this project unless overridden by the `project_id` parameter in a tool call.
+  - Example: `export SHIFT_PROJECT_ID=9af16a19-d073-4134-a0cd-272b0baf912e`
+- **`SHIFT_BACKEND_URL`** (optional): Webapp backend base URL. Default: `http://127.0.0.1:9000`.
+
+## Project ID: env vs per-call
+
+- **Default:** Set `SHIFT_PROJECT_ID` in the MCP config (or env). All tools use that project.
+- **Override per call:** Each tool (`blast_radius`, `dependencies`, `file_summary`) accepts an optional **`project_id`** parameter. If you pass it, that call uses that project; otherwise the tool uses `SHIFT_PROJECT_ID`. So you can use one MCP for multiple projects by passing `project_id` in the call (e.g. "blast radius for project abc-123").
+
+## Installation
+
+### Option 1: Install globally (simple, persistent)
+
+```bash
+npm install -g @latentforce/shift
+```
+
+Verify it works:
+```bash
+shift
+```
+
+You should see:
+```bash
+Shift-lite MCP Server running on stdio
+```
+
+
+## Claude Code setup
+
+Claude Code does not auto-discover MCP servers. You must register it manually.
+
+### Install the Package (if not already)
+You can use this package without installing it globally by using npx, or install it globally for faster access.
+
+```bash
+npm install -g @latentforce/shift
+```
+
+### Add to Claude Code
+- Replace SHIFT_BACKEND_URL and SHIFT_PROJECT_ID with correct values.
+- SHIFT_PROJECT_ID may be ignored as every tool accepts an optional **`project_id`** parameter.
+For Windows Users
+```bash
+claude mcp add --scope user --transport stdio --env SHIFT_BACKEND_URL=BACKEND_URL --env SHIFT_PROJECT_ID=9af16a19-d073-4134-a0cd-272b0baf912e shift -- cmd /c npx -y @latentforce/shift
+```
+
+For macOS/Linux Users
+```bash
+claude mcp add --scope user --transport stdio --env SHIFT_BACKEND_URL=BACKEND_URL --env SHIFT_PROJECT_ID=9af16a19-d073-4134-a0cd-272b0baf912e shift -- npx -y @latentforce/shift
+```
+
+### Verify Installation
+```bash
+claude mcp list
+```
+
+### Use It
+Start a Claude Code session:
+```bash
+claude
+```
+
+## Claude Desktop setup
+
+Claude Desktop does not auto-discover MCP servers. You must register it manually.
+
+### Config file location
+
+**macOS (Claude Desktop app):**
+```bash
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+*(In Claude Desktop: Claude menu → Settings… → Developer → Edit Config)*
+
+**Linux (if different):**
+```bash
+~/.config/claude-desktop/claude_desktop_config.json
+```
+
+**Windows:**
+```bash
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+Add this (replace `YOUR_PROJECT_UUID` with your Shift Lite project ID):
+```json
+{
+  "mcpServers": {
+    "shift": {
+      "command": "shift",
+      "env": {
+        "SHIFT_BACKEND_URL": "BACKEND URL",
+        "SHIFT_PROJECT_ID": "YOUR_PROJECT_UUID"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+## Development
+
+Clone and build:
+```bash
+npm install
+npm run build
+```
+
+Run locally:
+```bash
+node build/index.js
+```
+

package/build/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from 'zod';
+// Create server instance
+const server = new McpServer({
+    name: "shift",
+    version: "1.0.0",
+});
+const BASE_URL = process.env.SHIFT_BACKEND_URL || "http://127.0.0.1:9000";
+function getProjectIdFromEnv() {
+    const projectId = process.env.SHIFT_PROJECT_ID;
+    if (!projectId || projectId.trim() === "") {
+        throw new Error("SHIFT_PROJECT_ID environment variable is not set. " +
+            "Set it to your Shift Lite project UUID, or pass project_id in each tool call.");
+    }
+    return projectId.trim();
+}
+/** Resolve project_id: use tool arg if provided, else fall back to env. */
+function resolveProjectId(args) {
+    const fromArgs = args.project_id?.trim();
+    if (fromArgs)
+        return fromArgs;
+    return getProjectIdFromEnv();
+}
+// helper
+async function callBackendAPI(endpoint, data) {
+    try {
+        const response = await fetch(`${BASE_URL}${endpoint}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(data),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`API call failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        console.error(`Error calling ${endpoint}:`, error);
+        throw error;
+    }
+}
+// Tools:
+// Blast radius
+server.registerTool("blast_radius", {
+    description: "Analyzes the blast radius of a file or component - shows what would be affected if this file were modified or deleted",
+    inputSchema: z.object({
+        file_path: z.string().describe("Path to the file (relative to project root)"),
+        project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
+        project_path: z.string().optional().describe("Path to the root of the project (optional)"),
+        level: z.number().optional().describe("Max depth of blast radius (optional)"),
+    })
+}, async (args) => {
+    const projectId = resolveProjectId(args);
+    const data = await callBackendAPI('/api/v1/mcp/blast-radius', {
+        path: args.file_path,
+        project_id: projectId,
+        ...(args.level != null && { level: args.level }),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            },
+        ],
+    };
+});
+// Dependencies
+server.registerTool("dependencies", {
+    description: "Retrieves all dependencies for a given file or component, including direct and transitive dependencies",
+    inputSchema: z.object({
+        file_path: z.string().describe("Path to the file"),
+        project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
+        project_path: z.string().optional().describe("Path to the root of the project (optional)"),
+    })
+}, async (args) => {
+    const projectId = resolveProjectId(args);
+    const data = await callBackendAPI('/api/v1/mcp/dependency', {
+        path: args.file_path,
+        project_id: projectId,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            },
+        ],
+    };
+});
+// File summary (maps to what-is-this-file)
+server.registerTool("file_summary", {
+    description: "Generates a comprehensive summary of a file including its purpose, exports, imports, and key functions, with optional parent directory context",
+    inputSchema: z.object({
+        file_path: z.string().describe("Path to the file to summarize"),
+        project_id: z.string().optional().describe("Shift Lite project UUID; overrides SHIFT_PROJECT_ID if provided"),
+        project_path: z.string().optional().describe("Path to the root of the project (optional)"),
+        level: z.number().optional().describe("Number of parent directory levels to include (default 0)"),
+    })
+}, async (args) => {
+    const projectId = resolveProjectId(args);
+    const data = await callBackendAPI('/api/v1/mcp/what-is-this-file', {
+        path: args.file_path,
+        project_id: projectId,
+        level: args.level ?? 0,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Shift MCP Server running on stdio");
+    if (!process.env.SHIFT_PROJECT_ID) {
+        console.error("Warning: SHIFT_PROJECT_ID is not set. Pass project_id in each tool call, or set the env var.");
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "@latentforce/shift",
+    "version": "1.0.0",
+    "description": "This is latenforce shift MCP",
+    "type": "module",
+    "main": "./build/index.js",
+    "exports": {
+        ".": "./build/index.js"
+    },
+    "bin": {
+        "shift": "./build/index.js"
+    },
+    "files": [
+        "build"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build",
+        "test": "echo \"No tests yet\""
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "cli",
+        "node",
+        "typescript"
+    ],
+    "author": "Latentforce",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": ""
+    },
+    "homepage": "",
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.25.3",
+        "zod": "^3.25.76"
+    },
+    "devDependencies": {
+        "@types/node": "^25.0.9",
+        "typescript": "^5.9.3"
+    }
+}