jsoncrm 1.0.0__py3-none-any.whl

jsoncrm/__init__.py

@@ -0,0 +1,3 @@
+"""jsoncrm — A generic JSON-file CRM pipeline tool."""
+
+__version__ = "1.0.0"

jsoncrm/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Allow running jsoncrm as a module: ``python -m jsoncrm``."""
+
+from jsoncrm.tool import main
+
+if __name__ == "__main__":
+    main()

jsoncrm/backup.py

@@ -0,0 +1,91 @@
+"""Atomic, out-of-Git snapshots of configured CRM state."""
+
+import json
+import os
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZipFile
+
+MANIFEST_NAME = "backup-manifest.json"
+
+
+def _git_root(crm_dir):
+    for candidate in (crm_dir, *crm_dir.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def _default_output(crm_dir, now):
+    name = re.sub(r"[^A-Za-z0-9_.-]+", "-", crm_dir.name).strip("-.") or "crm"
+    timestamp = now.strftime("%Y%m%dT%H%M%S%fZ")
+    return Path.home() / ".jsoncrm" / "backups" / f"{name}-{timestamp}.zip"
+
+
+def create_backup(crm_dir, source_files, output=None, now=None):
+    crm_dir = Path(crm_dir).expanduser().resolve()
+    now = now or datetime.now(timezone.utc)
+    created_at = now.isoformat(timespec="seconds").replace("+00:00", "Z")
+    output = Path(output).expanduser() if output else _default_output(crm_dir, now)
+    output = output.resolve()
+
+    git_root = _git_root(crm_dir)
+    if git_root is not None:
+        try:
+            output.relative_to(git_root)
+        except ValueError:
+            pass
+        else:
+            raise ValueError(f"backup destination must be outside the Git repository: {git_root}")
+
+    entries = []
+    missing = []
+    seen = set()
+    for source in source_files:
+        path = Path(source).expanduser()
+        if not path.is_absolute():
+            path = crm_dir / path
+        path = path.resolve()
+        try:
+            relative = path.relative_to(crm_dir)
+        except ValueError as exc:
+            raise ValueError(f"CRM source is outside {crm_dir}: {path}") from exc
+        archive_name = relative.as_posix()
+        if archive_name in seen:
+            continue
+        seen.add(archive_name)
+        if not path.exists():
+            missing.append(archive_name)
+            continue
+        if not path.is_file():
+            raise ValueError(f"CRM source is not a file: {path}")
+        entries.append((path, archive_name))
+
+    if not entries:
+        raise ValueError(f"no CRM files found to back up in {crm_dir}")
+    if output.exists():
+        raise ValueError(f"backup already exists: {output}")
+
+    archived_files = [archive_name for _, archive_name in entries]
+    manifest = {
+        "created_at": created_at,
+        "files": archived_files,
+        "missing": missing,
+    }
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = output.with_name(f".{output.name}.tmp-{uuid.uuid4().hex}")
+    try:
+        with ZipFile(temporary, "x", compression=ZIP_DEFLATED) as archive:
+            for path, archive_name in entries:
+                archive.write(path, archive_name)
+            archive.writestr(
+                MANIFEST_NAME,
+                json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
+            )
+        os.replace(temporary, output)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+    return {"backup": str(output), "files": archived_files, "missing": missing}

jsoncrm/config.py

@@ -0,0 +1,129 @@
+"""Configuration loader for jsoncrm.
+
+Supports `.crm.json` in the working directory or an explicit ``--config`` path.
+Falls back to built-in marketing-CRM defaults when no config is found.
+"""
+
+import json
+from pathlib import Path
+
+from jsoncrm.schema import JSON_DB_ENCODING
+
+DEFAULT_MARKETING_CONFIG = {
+    "name": "marketing-crm",
+    "pipeline": {
+        "stages": [
+            {"name": "leads", "file": "leads.json"},
+            {"name": "prospects", "file": "prospects.json"},
+            {"name": "customers", "file": "customers.json"},
+        ],
+        "transitions": {
+            "leads": ["prospects"],
+            "prospects": ["customers"],
+        },
+    },
+    "identity": {
+        "primary": "linkedin_url",
+        "fallback": ["id"],
+    },
+    "scores": {
+        "order": ["⭐", "⭐⭐", "⭐⭐⭐", "⭐⭐⭐⭐", "⭐⭐⭐⭐⭐"],
+        "disqualified": "❌",
+    },
+    "blocklist": {
+        "file": "competitors.json",
+        "match_fields": ["company", "name"],
+    },
+}
+
+
+def _deep_merge(base, override):
+    """Recursively merge *override* into *base*."""
+    result = {}
+    for key, value in base.items():
+        if key in override:
+            if isinstance(value, dict) and isinstance(override[key], dict):
+                result[key] = _deep_merge(value, override[key])
+            else:
+                result[key] = override[key]
+        else:
+            result[key] = value
+    # Add keys that exist only in override
+    for key, value in override.items():
+        if key not in base:
+            result[key] = value
+    return result
+
+
+class Config:
+    """Domain-agnostic CRM configuration."""
+
+    def __init__(self, data):
+        self._data = data
+
+    @classmethod
+    def from_file(cls, path=None):
+        """Load config from *path* or fall back to ``.crm.json`` in cwd."""
+        if path is not None:
+            config_path = Path(path)
+        else:
+            config_path = Path(".crm.json")
+
+        if config_path.exists():
+            with open(config_path, encoding=JSON_DB_ENCODING) as f:
+                override = json.load(f)
+            return cls(_deep_merge(DEFAULT_MARKETING_CONFIG, override))
+        return cls(_deep_merge(DEFAULT_MARKETING_CONFIG, {}))
+
+    # --- pipeline ---
+
+    @property
+    def pipeline_stages(self):
+        return self._data["pipeline"]["stages"]
+
+    @property
+    def pipeline_transitions(self):
+        return self._data["pipeline"].get("transitions", {})
+
+    # --- identity ---
+
+    @property
+    def identity_primary(self):
+        return self._data["identity"]["primary"]
+
+    @property
+    def identity_fallback(self):
+        return self._data["identity"].get("fallback", [])
+
+    # --- scores ---
+
+    def _scores_block(self):
+        # A missing, null, or explicitly empty "scores" block all mean the
+        # same thing: no override was really provided, so fall back to the
+        # default rather than silently producing zero valid scores or
+        # crashing on None.
+        return self._data.get("scores") or DEFAULT_MARKETING_CONFIG["scores"]
+
+    @property
+    def score_order(self):
+        order = self._scores_block().get("order") or DEFAULT_MARKETING_CONFIG["scores"]["order"]
+        return {s: i + 1 for i, s in enumerate(order)}
+
+    @property
+    def score_order_descending(self):
+        order = self._scores_block().get("order") or DEFAULT_MARKETING_CONFIG["scores"]["order"]
+        return list(reversed(order))
+
+    @property
+    def disqualified_score(self):
+        return self._scores_block().get("disqualified") or DEFAULT_MARKETING_CONFIG["scores"]["disqualified"]
+
+    # --- blocklist ---
+
+    @property
+    def blocklist_file(self):
+        return self._data["blocklist"]["file"]
+
+    @property
+    def blocklist_match_fields(self):
+        return self._data["blocklist"].get("match_fields", ["company", "name"])

jsoncrm/mcp.py

@@ -0,0 +1,335 @@
+"""Model Context Protocol server for jsoncrm."""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from jsoncrm.schema import JSON_DB_ENCODING
+from jsoncrm.tool import build_parser
+
+EXCLUDED_COMMANDS = frozenset({"serve", "mcp"})
+
+
+def _canonical_command_parsers():
+    parser = build_parser()
+    subparsers = next(
+        action for action in parser._actions
+        if isinstance(action, argparse._SubParsersAction)
+    )
+    commands = {}
+    seen = set()
+    for name, command_parser in subparsers.choices.items():
+        if id(command_parser) in seen:
+            continue
+        seen.add(id(command_parser))
+        commands[name] = command_parser
+    return commands
+
+
+COMMAND_PARSERS = _canonical_command_parsers()
+
+
+def _build_cli_args(command, values):
+    positionals = []
+    options = []
+    for action in COMMAND_PARSERS[command]._actions:
+        if action.dest in ("help", "json"):
+            continue
+        value = values.get(action.dest)
+        if action.option_strings:
+            flag = next(
+                (option for option in action.option_strings if option.startswith("--")),
+                action.option_strings[0],
+            )
+            if action.nargs == 0:
+                if value != action.default:
+                    options.append(flag)
+                continue
+            if value is None:
+                continue
+            options.append(flag)
+            if isinstance(value, dict):
+                options.append(json.dumps(value, ensure_ascii=False))
+            elif isinstance(value, (list, tuple)):
+                options.extend(str(item) for item in value)
+            else:
+                options.append(str(value))
+        else:
+            if value is None:
+                continue
+            if isinstance(value, (list, tuple)):
+                positionals.extend(str(item) for item in value)
+            else:
+                positionals.append(str(value))
+    return [command, *positionals, *options, "--json"]
+
+
+def _run_command(command, config_path=None, **values):
+    argv = [sys.executable, "-m", "jsoncrm"]
+    if config_path:
+        argv.extend(["--config", config_path])
+    argv.extend(_build_cli_args(command, values))
+    result = subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        encoding=JSON_DB_ENCODING,
+        check=False,
+    )
+    stdout = result.stdout.strip()
+    stderr = result.stderr.strip()
+    if result.returncode:
+        message = "\n".join(part for part in (stdout, stderr) if part)
+        raise RuntimeError(message or f"jsoncrm {command} exited with status {result.returncode}")
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError:
+        return {"output": stdout}
+    return data if isinstance(data, dict) else {"result": data}
+
+
+def create_server(config_path=None):
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:
+        raise SystemExit("MCP support requires: pip install 'jsoncrm[mcp]'") from exc
+
+    if config_path:
+        config_path = str(Path(config_path).resolve())
+
+    server = FastMCP(
+        "jsoncrm",
+        instructions="Inspect and modify the configured git-tracked JSON CRM.",
+    )
+
+    @server.tool()
+    def search(query: str, person: bool = False, company: bool = False, competitor: bool = False):
+        """Search the CRM pipeline by name, company, LinkedIn URL, or email."""
+        return _run_command(
+            "search", config_path, query=query, person=person, company=company, competitor=competitor,
+        )
+
+    @server.tool()
+    def find(
+        database_file: str,
+        item_file: str | None = None,
+        item_json: dict | str | None = None,
+        output_file: str | None = None,
+    ):
+        """Find exact field matches in a CRM JSON file."""
+        return _run_command(
+            "find", config_path, database_file=database_file, item_file=item_file,
+            item_json=item_json, output_file=output_file,
+        )
+
+    @server.tool()
+    def add(
+        database_file: str,
+        item_file: str | None = None,
+        item_json: dict | str | None = None,
+        output_file: str | None = None,
+        dry_run: bool = False,
+        apply: bool = False,
+    ):
+        """Add one record to a CRM JSON file."""
+        return _run_command(
+            "add", config_path, database_file=database_file, item_file=item_file,
+            item_json=item_json, output_file=output_file, dry_run=dry_run, apply=apply,
+        )
+
+    @server.tool()
+    def update(
+        database_file: str,
+        item_file: str | None = None,
+        item_json: dict | str | None = None,
+        output_file: str | None = None,
+        dry_run: bool = False,
+        apply: bool = False,
+    ):
+        """Update one record identified by id or linkedin_url."""
+        return _run_command(
+            "update", config_path, database_file=database_file, item_file=item_file,
+            item_json=item_json, output_file=output_file, dry_run=dry_run, apply=apply,
+        )
+
+    @server.tool()
+    def delete(
+        database_file: str,
+        item_file: str | None = None,
+        item_json: dict | str | None = None,
+        output_file: str | None = None,
+        dry_run: bool = False,
+        apply: bool = False,
+    ):
+        """Delete one record identified by id or linkedin_url."""
+        return _run_command(
+            "delete", config_path, database_file=database_file, item_file=item_file,
+            item_json=item_json, output_file=output_file, dry_run=dry_run, apply=apply,
+        )
+
+    @server.tool()
+    def apply_update(pending_file: str = "default"):
+        """Apply updates from a pending update file."""
+        return _run_command("apply_update", config_path, pending_file=pending_file)
+
+    @server.tool()
+    def intake(file: str, output: str | None = None):
+        """Pick the next unscored record from an intake file."""
+        return _run_command("intake", config_path, file=file, output=output)
+
+    @server.tool(name="parse-from-linkedin-mcp")
+    def parse_from_linkedin_mcp(files: list[str]):
+        """Convert LinkedIn MCP output files to CRM flat lists in place."""
+        return _run_command("parse-from-linkedin-mcp", config_path, files=files)
+
+    @server.tool()
+    def shuffle(file: str, seed: int | None = None, dry_run: bool = False):
+        """Shuffle records in a JSON array file."""
+        return _run_command("shuffle", config_path, file=file, seed=seed, dry_run=dry_run)
+
+    @server.tool()
+    def top(
+        num: int = 1,
+        min_score: str | None = None,
+        include_contacted: bool = False,
+        include_disqualified: bool = False,
+        output: str | None = None,
+        file: str | None = None,
+    ):
+        """Return top-scored actionable leads."""
+        return _run_command(
+            "top", config_path, num=num, min_score=min_score,
+            include_contacted=include_contacted, include_disqualified=include_disqualified,
+            output=output, file=file,
+        )
+
+    @server.tool()
+    def merge(file: str, dry_run: bool = False, leads_file: str | None = None):
+        """Merge scored records from a source file into leads."""
+        return _run_command("merge", config_path, file=file, dry_run=dry_run, leads_file=leads_file)
+
+    @server.tool()
+    def deduplicate(
+        file: str,
+        dry_run: bool = False,
+        leads_file: str | None = None,
+        prospects_file: str | None = None,
+        customers_file: str | None = None,
+    ):
+        """Remove records whose LinkedIn URLs already exist in the pipeline."""
+        return _run_command(
+            "deduplicate", config_path, file=file, dry_run=dry_run, leads_file=leads_file,
+            prospects_file=prospects_file, customers_file=customers_file,
+        )
+
+    @server.tool(name="filter-competitors")
+    def filter_competitors(file: str, dry_run: bool = False):
+        """Remove records matching the configured competitor watchlist."""
+        return _run_command("filter-competitors", config_path, file=file, dry_run=dry_run)
+
+    @server.tool()
+    def promote(
+        identity_value: str,
+        identity_field: str | None = None,
+        lead: bool = False,
+        prospect: bool = False,
+        from_file: str | None = None,
+        to_file: str | None = None,
+        dry_run: bool = False,
+        apply: bool = False,
+    ):
+        """Move a lead or prospect to the next configured pipeline stage."""
+        return _run_command(
+            "promote", config_path, identity_value=identity_value, identity_field=identity_field,
+            lead=lead, prospect=prospect, from_file=from_file, to_file=to_file,
+            dry_run=dry_run, apply=apply,
+        )
+
+    @server.tool()
+    def stats(
+        leads_file: str | None = None,
+        prospects_file: str | None = None,
+        customers_file: str | None = None,
+    ):
+        """Show pipeline statistics."""
+        return _run_command(
+            "stats", config_path, leads_file=leads_file,
+            prospects_file=prospects_file, customers_file=customers_file,
+        )
+
+    @server.tool()
+    def validate(
+        leads_file: str | None = None,
+        prospects_file: str | None = None,
+        customers_file: str | None = None,
+    ):
+        """Validate pipeline JSON files for structural integrity."""
+        return _run_command(
+            "validate", config_path, leads_file=leads_file,
+            prospects_file=prospects_file, customers_file=customers_file,
+        )
+
+    @server.tool()
+    def recent(
+        num: int = 10,
+        stage: str | None = None,
+        leads_file: str | None = None,
+        prospects_file: str | None = None,
+        customers_file: str | None = None,
+    ):
+        """Show the most recently added pipeline records."""
+        return _run_command(
+            "recent", config_path, num=num, stage=stage, leads_file=leads_file,
+            prospects_file=prospects_file, customers_file=customers_file,
+        )
+
+    @server.tool()
+    def demote(
+        identity_value: str,
+        identity_field: str | None = None,
+        customer: bool = False,
+        prospect: bool = False,
+        from_file: str | None = None,
+        to_file: str | None = None,
+        dry_run: bool = False,
+        apply: bool = False,
+    ):
+        """Move a prospect or customer back one pipeline stage."""
+        return _run_command(
+            "demote", config_path, identity_value=identity_value, identity_field=identity_field,
+            customer=customer, prospect=prospect, from_file=from_file, to_file=to_file,
+            dry_run=dry_run, apply=apply,
+        )
+
+    @server.tool(name="list")
+    def list_records(
+        stage: str,
+        score: str | None = None,
+        company: str | None = None,
+        query: str | None = None,
+        limit: int | None = None,
+        file: str | None = None,
+    ):
+        """List and filter records in a pipeline stage."""
+        return _run_command(
+            "list", config_path, stage=stage, score=score, company=company,
+            query=query, limit=limit, file=file,
+        )
+
+    @server.tool()
+    def dump_emails(out: str | None = None):
+        """Dump all unique pipeline email addresses, comma separated."""
+        return _run_command("dump_emails", config_path, out=out)
+
+    @server.tool()
+    def backup(output: str | None = None):
+        """Create an atomic ZIP backup of configured CRM files outside Git."""
+        return _run_command("backup", config_path, output=output)
+
+    return server
+
+
+def run_mcp(config_path=None):
+    create_server(config_path=config_path).run(transport="stdio")

jsoncrm/parsers.py

@@ -0,0 +1,98 @@
+"""LinkedIn MCP output parsers for jsoncrm."""
+
+import json
+from datetime import date
+from pathlib import Path
+
+from jsoncrm.schema import JSON_DB_ENCODING
+from jsoncrm.utils import atomic_write_json
+
+
+def cmd_parse_from_linkedin_mcp(args):
+    for filename in args.files:
+        path = Path(filename)
+        if not path.exists():
+            print(f"Error: {path} not found")
+            continue
+
+        data = json.loads(path.read_text(encoding=JSON_DB_ENCODING))
+        
+        if not isinstance(data, dict):
+            print(f"Error: {path.name} must be a recognized MCP output format (dict)")
+            continue
+
+        people_data = []
+
+        # Format 1: get_post_likers
+        if "likers" in data:
+            for l in data["likers"]:
+                people_data.append({
+                    "raw_name": l.get("name", ""),
+                    "url": l.get("url", "")
+                })
+                
+        # Format 2: get_inbox
+        elif "conversations" in data:
+            for c in data["conversations"]:
+                url = c.get("thread_url") or ""
+                if c.get("username"):
+                    url = f"https://www.linkedin.com/in/{c['username']}/"
+                people_data.append({
+                    "raw_name": c.get("name", ""),
+                    "url": url
+                })
+                
+        # Format 3: search_people, get_person_profile, get_company_profile, etc.
+        elif "references" in data:
+            for section, refs in data["references"].items():
+                for r in refs:
+                    if isinstance(r, dict) and r.get("kind") == "person":
+                        url = r.get("url", "")
+                        if url.startswith("/"):
+                            url = f"https://www.linkedin.com{url}"
+                        people_data.append({
+                            "raw_name": r.get("text", ""),
+                            "url": url
+                        })
+
+        if not people_data:
+            print(f"Error: No people records found in {path.name}. Supported formats: likers, conversations, references.")
+            continue
+
+        print(f"Converting {len(people_data)} records from {path.name} to CRM format...")
+        out_data = []
+        today_str = str(date.today())
+        
+        for p in people_data:
+            raw_name = p["raw_name"]
+            parts = raw_name.split("\n")
+            name = parts[0].strip()
+            position = parts[-1].strip() if len(parts) > 1 else ""
+            if position.startswith("·"):
+                position = position[1:].strip()
+            company = None
+            if " at " in position:
+                p_parts = position.split(" at ")
+                position = p_parts[0].strip()
+                company = p_parts[1].strip()
+            elif " @ " in position:
+                p_parts = position.split(" @ ")
+                position = p_parts[0].strip()
+                company = p_parts[1].strip()
+                
+            out_data.append({
+                "name": name,
+                "position": position,
+                "company": company,
+                "linkedin_url": p["url"],
+                "connected": "1st degree" in raw_name,
+                "email": None,
+                "contacted_at": None,
+                "source": "linkedin_mcp",
+                "added": today_str,
+                "score": None,
+                "notes": ""
+            })
+            
+        atomic_write_json(path, out_data)
+        print(f"Successfully converted {len(out_data)} records in {path.name}.")