cloudsense-customer-compass 0.1.0__tar.gz

cloudsense_customer_compass-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.swp
+.DS_Store

cloudsense_customer_compass-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: cloudsense-customer-compass
+Version: 0.1.0
+Summary: MCP server for CloudSense customer upgrade assessment, analysis, and impact verification.
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CloudSense Customer Compass
+
+MCP server for CloudSense customer upgrade assessment, analysis, and impact verification.

cloudsense_customer_compass-0.1.0/README.md

@@ -0,0 +1,3 @@
+# CloudSense Customer Compass
+
+MCP server for CloudSense customer upgrade assessment, analysis, and impact verification.

cloudsense_customer_compass-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cloudsense-customer-compass"
+version = "0.1.0"
+description = "MCP server for CloudSense customer upgrade assessment, analysis, and impact verification."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+cloudsense-customer-compass = "cloudsense_customer_compass.server:main"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cloudsense_customer_compass"]

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/__init__.py

@@ -0,0 +1,3 @@
+"""CloudSense Customer Compass - MCP server for upgrade assessment and analysis."""
+
+__version__ = "0.1.0"

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m cloudsense_customer_compass"""
+
+from .server import main
+
+main()

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/server.py

@@ -0,0 +1,96 @@
+"""CloudSense Customer Compass MCP server.
+
+Run with: python -m cloudsense_customer_compass.server
+Or via CLI: cloudsense-customer-compass
+"""
+
+import asyncio
+import logging
+import sys
+
+from anyio import BrokenResourceError, ClosedResourceError
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+import mcp.types as types
+
+from . import __version__
+from .tools import connect_lma
+
+logger = logging.getLogger(__name__)
+
+server = Server("cloudsense-customer-compass")
+
+TOOLS = {
+    "connect_lma": connect_lma,
+}
+
+SERVER_INSTRUCTIONS = (
+    "You are connected to the CloudSense Customer Compass MCP server.\n\n"
+    "SAFETY: This server is STRICTLY READ-ONLY against customer Salesforce orgs. "
+    "NEVER deploy, push, insert, update, delete, or modify anything in the org.\n\n"
+    "WORKFLOW:\n"
+    "1. connect_lma -- Connect to the License Management Portal (FIRST step)\n"
+    "2. (more tools coming soon)\n\n"
+    "ORG RESOLUTION: If the user mentions an org, pass it as org_alias. "
+    "If not, omit — the tool uses defaults or state.\n"
+)
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name=mod.TOOL_DEFINITION["name"],
+            description=mod.TOOL_DEFINITION["description"],
+            inputSchema=mod.TOOL_DEFINITION["inputSchema"],
+        )
+        for mod in TOOLS.values()
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    tool_module = TOOLS.get(name)
+    if tool_module is None:
+        raise ValueError(f"Unknown tool: {name}")
+    result = await tool_module.run(arguments)
+    return [types.TextContent(type="text", text=result)]
+
+
+def _is_disconnect(exc: BaseException) -> bool:
+    if isinstance(exc, (BrokenResourceError, ClosedResourceError)):
+        return True
+    if isinstance(exc, BaseExceptionGroup):
+        return all(_is_disconnect(e) for e in exc.exceptions)
+    return False
+
+
+async def _run_server():
+    logger.info("CloudSense Customer Compass v%s starting...", __version__)
+    try:
+        async with stdio_server() as (read_stream, write_stream):
+            init_options = server.create_initialization_options()
+            init_options.instructions = SERVER_INSTRUCTIONS
+            await server.run(read_stream, write_stream, init_options)
+    except BaseExceptionGroup as eg:
+        if _is_disconnect(eg):
+            logger.info("Client disconnected — shutting down.")
+        else:
+            raise
+    except (BrokenResourceError, ClosedResourceError):
+        logger.info("Client disconnected — shutting down.")
+
+
+def main():
+    logging.basicConfig(level=logging.INFO)
+    try:
+        asyncio.run(_run_server())
+    except KeyboardInterrupt:
+        pass
+    except (BrokenPipeError, EOFError):
+        logger.info("Pipe closed — exiting.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/tools/__init__.py

@@ -0,0 +1,5 @@
+from . import connect_lma
+
+__all__ = [
+    "connect_lma",
+]

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/tools/connect_lma.py

@@ -0,0 +1,118 @@
+"""connect_lma -- Authorize the CloudSense License Management Portal.
+
+Entry point for the workflow. Checks if the LMA org is already
+authorized, opens browser login if not, and saves connection info
+to assessment.json.
+"""
+
+import logging
+from typing import Any
+
+from ..utils import sf_cli, state
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ALIAS = "cs-lma"
+DEFAULT_LOGIN_URL = "https://login.salesforce.com"
+
+TOOL_DEFINITION = {
+    "name": "connect_lma",
+    "description": (
+        "Authorize the CloudSense License Management Portal. "
+        "This is the FIRST tool to call for any customer inquiry. "
+        "Checks if the LMA org is already authorized, opens browser "
+        "login if not, and saves connection info to state."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "org_alias": {
+                "type": "string",
+                "description": (
+                    "Alias for the LMA org. Defaults to 'cs-lma'. "
+                    "If already authorized under this alias, login is skipped."
+                ),
+            },
+            "instance_url": {
+                "type": "string",
+                "description": (
+                    "Salesforce login URL. Defaults to "
+                    "'https://login.salesforce.com'. Override for custom domains."
+                ),
+            },
+            "working_directory": {
+                "type": "string",
+                "description": "Workspace directory. The AI passes this automatically.",
+            },
+        },
+        "required": [],
+    },
+}
+
+
+def _validate_org(alias: str) -> dict[str, Any] | None:
+    """Check if an org is authorized and accessible."""
+    try:
+        data = sf_cli.display_org(alias)
+        return data.get("result", {})
+    except sf_cli.SfCliError:
+        return None
+
+
+async def run(arguments: dict[str, Any]) -> str:
+    """Execute the connect_lma tool."""
+    state.set_working_dir(arguments.get("working_directory"))
+
+    sf_check = sf_cli.check_sf_installed()
+    if not sf_check["installed"]:
+        return (
+            "## BLOCKER: Salesforce CLI not found\n\n"
+            "Install from: https://developer.salesforce.com/tools/salesforcecli\n"
+            "Then call connect_lma again."
+        )
+
+    alias = arguments.get("org_alias") or DEFAULT_ALIAS
+    instance_url = arguments.get("instance_url")
+
+    org_info = _validate_org(alias)
+
+    if not org_info:
+        login_url = instance_url or DEFAULT_LOGIN_URL
+        try:
+            sf_cli.run_sf(
+                f"org login web --alias {alias} --instance-url {login_url}",
+                timeout=300, json_output=False,
+            )
+        except sf_cli.SfCliError as e:
+            return (
+                f"## BLOCKER: Login failed\n\n"
+                f"Error: {e}\n\n"
+                f"Run manually if browser didn't open:\n"
+                f"```\nsf org login web --alias {alias} --instance-url {login_url}\n```"
+            )
+
+        org_info = _validate_org(alias)
+        if not org_info:
+            return (
+                "## BLOCKER: Login succeeded but validation failed\n\n"
+                "Call connect_lma again to retry."
+            )
+
+    username = org_info.get("username", "unknown")
+    org_id = org_info.get("id", "unknown")
+    instance = org_info.get("instanceUrl", "unknown")
+
+    state.update(
+        lma_org_alias=alias,
+        lma_org_username=username,
+        lma_org_id=org_id,
+        lma_instance_url=instance,
+    )
+
+    return (
+        f"## LMA Connected\n\n"
+        f"- **Alias:** {alias}\n"
+        f"- **Username:** {username}\n"
+        f"- **Org ID:** {org_id}\n"
+        f"- **Instance:** {instance}\n"
+    )

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/utils/safety.py

@@ -0,0 +1,106 @@
+"""Safety policy enforcement for Salesforce CLI commands.
+
+Every sf CLI command MUST pass through validate_sf_command() before execution.
+If a command is not on the whitelist, it is blocked.
+"""
+
+import re
+
+
+ALLOWED_SF_SUBCOMMANDS: set[str] = {
+    "org login web",
+    "org list",
+    "org display",
+    "project generate",
+    "project retrieve start",
+    "org list metadata",
+    "package installed list",
+    "sobject list",
+    "sobject describe",
+    "data query",
+    "data search",
+}
+
+LMA_ALLOWED_OBJECTS: set[str] = {
+    "ACCOUNT",
+    "SFLMA__LICENSE__C",
+    "SFLMA__PACKAGE__C",
+    "SFLMA__PACKAGE_VERSION__C",
+    "SUBSCRIBERPACKAGE",
+}
+
+BLOCKED_KEYWORDS: set[str] = {
+    "deploy",
+    "push",
+    "delete",
+    "insert",
+    "update",
+    "upsert",
+    "undelete",
+    "destroy",
+    "execute",
+    "apex run",
+}
+
+
+class SafetyViolationError(Exception):
+    """Raised when a command violates the read-only safety policy."""
+
+
+def validate_sf_command(command: str) -> None:
+    """Validate that an sf CLI command is on the whitelist."""
+    normalized = " ".join(command.strip().split())
+
+    for blocked in BLOCKED_KEYWORDS:
+        if blocked in normalized.lower():
+            raise SafetyViolationError(
+                f"BLOCKED: Command contains '{blocked}' which is prohibited. "
+                f"Command: {command}"
+            )
+
+    if not any(allowed in normalized for allowed in ALLOWED_SF_SUBCOMMANDS):
+        raise SafetyViolationError(
+            f"BLOCKED: Command not on the whitelist. "
+            f"Allowed: {sorted(ALLOWED_SF_SUBCOMMANDS)}. "
+            f"Command: {command}"
+        )
+
+
+def validate_soql_query(
+    query: str,
+    *,
+    target_org: str | None = None,
+    lma_org: str | None = None,
+) -> None:
+    """Validate that a SOQL query is read-only and safe."""
+    normalized = query.strip().upper()
+
+    if not normalized.startswith("SELECT"):
+        raise SafetyViolationError(
+            f"BLOCKED: Only SELECT queries are permitted. Query: {query}"
+        )
+
+    for keyword in ("INSERT", "UPDATE", "DELETE", "UPSERT", "MERGE"):
+        if re.search(rf"\b{keyword}\b", normalized):
+            raise SafetyViolationError(
+                f"BLOCKED: DML keyword '{keyword}' found. Query: {query}"
+            )
+
+    is_lma_context = (
+        target_org is not None
+        and lma_org is not None
+        and target_org == lma_org
+    )
+
+    business_objects = [
+        "ACCOUNT", "CONTACT", "LEAD", "OPPORTUNITY", "CASE",
+        "CONTRACT", "TASK", "EVENT", "CAMPAIGN",
+    ]
+    for obj in business_objects:
+        if re.search(rf"\bFROM\s+{obj}\b", normalized):
+            if is_lma_context and obj in LMA_ALLOWED_OBJECTS:
+                continue
+            raise SafetyViolationError(
+                f"BLOCKED: Querying business object '{obj}' is not permitted. "
+                f"Query: {query}"
+            )

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/utils/sf_cli.py

@@ -0,0 +1,156 @@
+"""Safe wrapper around Salesforce CLI (sf).
+
+Every command goes through the safety validator before execution.
+"""
+
+import json
+import logging
+import subprocess
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .safety import validate_sf_command, validate_soql_query
+
+logger = logging.getLogger(__name__)
+
+
+class SfCliError(Exception):
+    """Raised when an sf CLI command fails."""
+
+    def __init__(self, message: str, command: str = "", exit_code: int = -1, stderr: str = ""):
+        super().__init__(message)
+        self.command = command
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+
+def check_sf_installed() -> dict[str, Any]:
+    """Check if Salesforce CLI is installed and return version info."""
+    sf_path = shutil.which("sf")
+    if not sf_path:
+        return {"installed": False, "version": None, "path": None}
+
+    try:
+        result = subprocess.run(
+            ["sf", "version", "--json"],
+            capture_output=True, text=True, timeout=15,
+        )
+        if result.returncode == 0:
+            try:
+                data = json.loads(result.stdout)
+                version = data.get("cliVersion", result.stdout.strip())
+            except json.JSONDecodeError:
+                version = result.stdout.strip()
+            return {"installed": True, "version": version, "path": sf_path}
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+
+    return {"installed": True, "version": "unknown", "path": sf_path}
+
+
+def run_sf(
+    command: str | list[str],
+    *,
+    cwd: Path | str | None = None,
+    timeout: int = 120,
+    json_output: bool = True,
+) -> dict[str, Any]:
+    """Run an sf CLI command safely.
+
+    The command string should NOT include 'sf' prefix.
+    """
+    if isinstance(command, list):
+        full_command = "sf " + " ".join(command)
+        args = ["sf"] + command
+    else:
+        full_command = f"sf {command}"
+        args = ["sf"] + command.split()
+
+    validate_sf_command(full_command)
+
+    if json_output and "--json" not in args:
+        args.append("--json")
+
+    logger.info("Running: %s (cwd=%s)", " ".join(args), cwd or ".")
+
+    try:
+        result = subprocess.run(
+            args, capture_output=True, text=True,
+            cwd=str(cwd) if cwd else None, timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        raise SfCliError(
+            f"Command timed out after {timeout}s: {full_command}",
+            command=full_command, exit_code=-1, stderr="TimeoutExpired",
+        )
+    except FileNotFoundError:
+        raise SfCliError(
+            "Salesforce CLI (sf) not found on PATH.",
+            command=full_command, exit_code=-1, stderr="FileNotFoundError",
+        )
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or result.stdout.strip()
+        raise SfCliError(
+            f"sf command failed (exit {result.returncode}): {stderr}",
+            command=full_command, exit_code=result.returncode, stderr=stderr,
+        )
+
+    if json_output:
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return {"stdout": result.stdout.strip()}
+
+    return {"stdout": result.stdout.strip()}
+
+
+def list_orgs(cwd: Path | str | None = None) -> list[dict[str, Any]]:
+    """List all authorized Salesforce orgs."""
+    data = run_sf("org list", cwd=cwd)
+    result = data.get("result", {})
+    orgs = []
+    for category in ("nonScratchOrgs", "scratchOrgs"):
+        orgs.extend(result.get(category, []))
+    return orgs
+
+
+def display_org(alias: str, cwd: Path | str | None = None) -> dict[str, Any]:
+    """Get detailed info about a specific org."""
+    return run_sf(f"org display --target-org {alias}", cwd=cwd)
+
+
+def lma_query(
+    query: str,
+    lma_org: str,
+    cwd: Path | str | None = None,
+    timeout: int = 120,
+) -> list[dict[str, Any]]:
+    """Run a read-only SOQL query against the LMA org."""
+    validate_soql_query(query, target_org=lma_org, lma_org=lma_org)
+    data = run_sf(
+        ["data", "query", "--query", query, "--target-org", lma_org],
+        cwd=cwd, timeout=timeout,
+    )
+    result = data.get("result", {})
+    records = result.get("records") or []
+    return records if isinstance(records, list) else []
+
+
+def sosl_search(
+    search_term: str,
+    returning: str,
+    target_org: str,
+    cwd: Path | str | None = None,
+    timeout: int = 60,
+) -> list[dict[str, Any]]:
+    """Run a SOSL search via sf data search."""
+    sosl_query = f"FIND {{{search_term}}} IN NAME FIELDS RETURNING {returning}"
+    data = run_sf(
+        ["data", "search", "--query", sosl_query, "--target-org", target_org],
+        cwd=cwd, timeout=timeout,
+    )
+    result = data.get("result", {})
+    records = result.get("searchRecords") or []
+    return records if isinstance(records, list) else []

cloudsense_customer_compass-0.1.0/src/cloudsense_customer_compass/utils/state.py

@@ -0,0 +1,61 @@
+"""Lean assessment state management.
+
+Manages assessment.json — a minimal state file tracking workflow status
+and connection info only. No data duplication; customer data lives in
+customer/ directory files.
+"""
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+STATE_FILENAME = "assessment.json"
+
+_working_dir: Path | None = None
+
+
+def set_working_dir(path: str | Path | None) -> None:
+    """Set the working directory from a tool argument."""
+    global _working_dir
+    if path:
+        _working_dir = Path(path)
+
+
+def get_working_dir() -> Path:
+    """Return the working directory (explicit override or cwd)."""
+    return _working_dir or Path.cwd()
+
+
+def _state_path() -> Path:
+    return get_working_dir() / STATE_FILENAME
+
+
+def load() -> dict[str, Any]:
+    """Load the state file. Returns empty dict if it doesn't exist."""
+    path = _state_path()
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except (json.JSONDecodeError, OSError):
+            logger.warning("Could not read state file at %s", path)
+    return {}
+
+
+def save(data: dict[str, Any]) -> None:
+    """Write the state file."""
+    path = _state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, default=str))
+
+
+def update(**fields: Any) -> dict[str, Any]:
+    """Merge fields into the existing state and save."""
+    current = load()
+    current.update(fields)
+    current["updated_at"] = datetime.now(timezone.utc).isoformat()
+    save(current)
+    return current