sharepoint-knowledge 0.1.0__tar.gz

sharepoint_knowledge-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: sharepoint-knowledge
+Version: 0.1.0
+Summary: SharePoint connector for the grounded-Q&A engine — site pages + document libraries, Entra device-code sign-in, local models, cited answers
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/nkunal1992/agents
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: confluence-knowledge[files]>=0.4.1
+Requires-Dist: msal>=1.31
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.8
+Provides-Extra: models
+Requires-Dist: confluence-knowledge[models]>=0.4.1; extra == "models"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: python-docx>=1.1; extra == "dev"
+Requires-Dist: python-pptx>=1.0; extra == "dev"
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Requires-Dist: pypdf>=5.0; extra == "dev"
+
+# sharepoint-knowledge
+
+SharePoint connector on the shared grounded-Q&A engine — Site Pages +
+document libraries (docx/pdf/pptx/xlsx/csv/txt/md/html), Entra device-code
+sign-in, local models, cited answers. Same engine as
+[`confluence-knowledge`](../confluence-knowledge) and
+[`local-knowledge`](../local-knowledge).
+
+- `sharepoint_knowledge/auth_sp.py` — MSAL device-code flow, token cache in
+  the OS keyring (protected-file fallback), silent refresh
+- `sharepoint_knowledge/client_sp.py` — GET-only Graph client; downloads go
+  through `@microsoft.graph.downloadUrl` WITHOUT the Bearer header
+- `sharepoint_knowledge/crawl_sp.py` — durable BFS site → pages + libraries
+- `sharepoint_knowledge/server_sp.py` — the `sharepoint-knowledge/*` tools
+- `sharepoint_knowledge/cli_sp.py` — setup/doctor/prepare-models/register/
+  update/serve/clean
+
+See `docs/sharepoint-knowledge.md` for the full guide.

sharepoint_knowledge-0.1.0/README.md

@@ -0,0 +1,18 @@
+# sharepoint-knowledge
+
+SharePoint connector on the shared grounded-Q&A engine — Site Pages +
+document libraries (docx/pdf/pptx/xlsx/csv/txt/md/html), Entra device-code
+sign-in, local models, cited answers. Same engine as
+[`confluence-knowledge`](../confluence-knowledge) and
+[`local-knowledge`](../local-knowledge).
+
+- `sharepoint_knowledge/auth_sp.py` — MSAL device-code flow, token cache in
+  the OS keyring (protected-file fallback), silent refresh
+- `sharepoint_knowledge/client_sp.py` — GET-only Graph client; downloads go
+  through `@microsoft.graph.downloadUrl` WITHOUT the Bearer header
+- `sharepoint_knowledge/crawl_sp.py` — durable BFS site → pages + libraries
+- `sharepoint_knowledge/server_sp.py` — the `sharepoint-knowledge/*` tools
+- `sharepoint_knowledge/cli_sp.py` — setup/doctor/prepare-models/register/
+  update/serve/clean
+
+See `docs/sharepoint-knowledge.md` for the full guide.

sharepoint_knowledge-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sharepoint-knowledge"
+version = "0.1.0"
+description = "SharePoint connector for the grounded-Q&A engine — site pages + document libraries, Entra device-code sign-in, local models, cited answers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+dependencies = [
+    "confluence-knowledge[files]>=0.4.1",
+    "msal>=1.31",
+    "httpx>=0.27",
+    "mcp>=1.8",
+]
+
+[project.optional-dependencies]
+models = [
+    "confluence-knowledge[models]>=0.4.1",
+]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5",
+    "python-docx>=1.1",
+    "python-pptx>=1.0",
+    "openpyxl>=3.1",
+    "pypdf>=5.0",
+]
+
+[project.scripts]
+sharepoint-knowledge = "sharepoint_knowledge.cli_sp:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/nkunal1992/agents"

sharepoint_knowledge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sharepoint_knowledge-0.1.0/src/sharepoint_knowledge/__init__.py

@@ -0,0 +1,3 @@
+"""sharepoint-knowledge — SharePoint connector on the shared engine."""
+
+__version__ = "0.1.0"

sharepoint_knowledge-0.1.0/src/sharepoint_knowledge/auth_sp.py

@@ -0,0 +1,118 @@
+"""Entra auth for sharepoint-knowledge — device-code flow + silent refresh.
+
+The MSAL token cache is stored as a credential blob through the shared
+keyring/file machinery (same posture as the Confluence PAT). The access
+token itself never enters chat, logs, or command-line arguments.
+
+SP_KNOWLEDGE_TOKEN env var short-circuits everything (tests/CI).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from confluence_knowledge.auth import get_credential, store_credential
+from confluence_knowledge.settings import SetupError
+
+SCOPES = ["https://graph.microsoft.com/Sites.Read.All", "offline_access"]
+ENV_TOKEN = "SP_KNOWLEDGE_TOKEN"
+AUTH_FILE = ".sp_auth.json"
+INDEX_DIR = ".sp_knowledge_index"
+SERVICE = "sharepoint-knowledge"
+
+
+def _cache_ref(profile) -> str:
+    return f"cache:{profile.credential_ref}"
+
+
+def _load_msal():
+    try:
+        import msal
+    except ImportError as e:
+        raise SetupError(
+            "msal isn't installed — reinstall with `pip install "
+            "sharepoint-knowledge[models]`") from e
+    return msal
+
+
+def _load_cache(workdir: Path, profile):
+    msal = _load_msal()
+    blob = get_credential(workdir, _cache_ref(profile), env=ENV_TOKEN,
+                          service=SERVICE, auth_file=AUTH_FILE,
+                          home_dir=".sharepoint-knowledge")
+    if blob:
+        try:
+            cache = msal.SerializableTokenCache()
+            cache.deserialize(json.loads(blob))
+            return cache
+        except Exception:  # noqa: BLE001 — corrupt cache → re-sign-in
+            return None
+    return None
+
+
+def _save_cache(workdir: Path, home_dir: Path, profile, cache) -> str:
+    return store_credential(workdir, home_dir, _cache_ref(profile),
+                            json.dumps(cache.serialize()),
+                            service=SERVICE, auth_file=AUTH_FILE,
+                            index_dir=INDEX_DIR)
+
+
+def _app(profile, cache=None):
+    msal = _load_msal()
+    kwargs = {"token_cache": cache} if cache else {}
+    return msal.PublicClientApplication(
+        profile.client_id,
+        authority=f"{_get_auth_base()}/{profile.tenant_id}",
+        **kwargs)
+
+
+def _get_auth_base() -> str:
+    """Authority base override for e2e (fake token endpoint)."""
+    return os.environ.get("SP_KNOWLEDGE_AUTH_BASE",
+                          "https://login.microsoftonline.com")
+
+
+def acquire_token(profile, workdir: Path, home_dir: Path) -> str:
+    """Silent first (cached refresh token); device flow only on expiry —
+    so normal use needs no re-sign-in after setup."""
+    if os.environ.get(ENV_TOKEN):
+        return os.environ[ENV_TOKEN]
+    cache = _load_cache(workdir, profile)
+    app = _app(profile, cache)
+    accounts = app.get_accounts()
+    if accounts:
+        r = app.acquire_token_silent(SCOPES, account=accounts[0])
+        if r and "access_token" in r:
+            if cache and cache.has_state_changed:
+                _save_cache(workdir, home_dir, profile, cache)
+            return r["access_token"]
+    raise SetupError(
+        "SharePoint sign-in expired — run `sharepoint-knowledge setup` to "
+        "re-authenticate (device code, one browser step)")
+
+
+def device_sign_in(profile, workdir: Path, home_dir: Path) -> dict:
+    """Interactive device-code sign-in — used by `setup`. Prints the
+    message Microsoft returns (URL + code); blocks until approved or it
+    times out. Returns the stored-cache location description."""
+    msal = _load_msal()
+    cache = msal.SerializableTokenCache()
+    app = _app(profile, cache)
+    flow = app.initiate_device_flow(scopes=SCOPES)
+    if "user_code" not in flow:
+        raise SetupError(
+            "couldn't start device sign-in: "
+            f"{flow.get('error_description', flow)}")
+    print("\n" + flow["message"] + "\n")  # "go to microsoft.com/devicelogin…"
+    r = app.acquire_token_by_device_flow(flow)
+    if "access_token" not in r:
+        raise SetupError(
+            "sign-in failed: "
+            f"{r.get('error_description', r.get('error', r))}")
+    where = _save_cache(workdir, home_dir, profile, cache)
+    account = r.get("id_token_claims", {})
+    return {"where": where,
+            "user": (account.get("preferred_username")
+                     or account.get("email") or "signed in")}

sharepoint_knowledge-0.1.0/src/sharepoint_knowledge/cli_sp.py

@@ -0,0 +1,191 @@
+"""sharepoint-knowledge CLI — setup (Entra device sign-in), doctor,
+prepare-models, register, update, serve, clean.
+
+Same shape as the other knowledge CLIs. `setup` prints the exact Entra
+app-registration steps for IT, collects tenant/client/site, then runs the
+one-time device-code sign-in.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from confluence_knowledge.registration import register as _register
+from confluence_knowledge.retrieval import prepare_models
+from confluence_knowledge.settings import SetupError, ensure_gitignore
+
+from .settings_sp import (
+    APP_NAME,
+    AUTH_ENV,
+    AUTH_FILE_NAME,
+    INDEX_DIR_NAME,
+    PROFILE_NAME,
+    SPProfile,
+    home,
+    workdir,
+)
+
+TOKEN_STEPS = """\
+Entra app registration — once per tenant, done by IT (or you, if allowed):
+  1. Entra portal (entra.microsoft.com) → Applications → App registrations
+     → New registration
+  2. Name: e.g. "sharepoint-knowledge-agent" — Accounts in this org only
+  3. Authentication → Enable "Allow public client flows" → YES (required
+     for device-code sign-in — no client secret is used or needed)
+  4. API permissions → Add → Microsoft Graph → Delegated → Sites.Read.All
+     (+ offline_access is implied by device flow)
+  5. Grant admin consent for the tenant (the delegated scope normally
+     requires it) — one click on the Permissions page
+  6. Copy: Directory (tenant) ID and Application (client) ID — needed below
+
+This app requests only delegated read access — it can read exactly what
+the signed-in user can already read, nothing more.
+"""
+
+
+def _setup() -> int:
+    print("SharePoint Knowledge — first-run setup\n")
+    print(TOKEN_STEPS)
+
+    tenant = input("Tenant ID (GUID): ").strip()
+    client = input("Client ID (application ID, GUID): ").strip()
+    site = input("SharePoint site URL (e.g. https://contoso.sharepoint.com"
+                 "/sites/team): ").strip().rstrip("/")
+    if not (tenant and client and site):
+        print("tenant ID, client ID, and site URL are all required",
+              file=sys.stderr)
+        return 1
+
+    profile = SPProfile(tenant_id=tenant, client_id=client,
+                        site_url=site, credential_ref="sp-token")
+    profile.save()
+    print(f"\nprofile saved to {home() / PROFILE_NAME}\n")
+
+    print("Sign-in (device code — one browser step). The code you get "
+          "never leaves the OS credential store.", flush=True)
+    if os.environ.get(AUTH_ENV):
+        print("SP_KNOWLEDGE_TOKEN is set — using it; skipping sign-in")
+    else:
+        from .auth_sp import device_sign_in
+        try:
+            r = device_sign_in(profile, workdir(), home())
+            print(f"signed in as {r['user']} — token cache stored at "
+                  f"{r['where']}")
+        except SetupError as e:
+            print(f"sign-in failed: {e}", file=sys.stderr)
+            return 1
+
+    # make sure the workdir's gitignore hides the index + auth file
+    workdir().mkdir(parents=True, exist_ok=True)
+    ensure_gitignore(workdir(), [AUTH_FILE_NAME,
+                                 f"{INDEX_DIR_NAME}/"])
+
+    if input("\nDownload the two local models now (~175 MB, one-time)? "
+             "[Y/n] ").strip().lower() not in ("n", "no"):
+        for line in prepare_models(home()):
+            print(line)
+
+    print("\nsetup complete — run `sharepoint-knowledge doctor` to verify")
+    return 0
+
+
+def _doctor() -> int:
+    from confluence_knowledge.update import check
+
+    from .server_sp import status
+    s = status()
+    print(json.dumps(s, indent=2))
+    upd = check("sharepoint-knowledge")
+    if upd["installed"]:
+        line = f"version: {upd['installed']}"
+        if upd["latest"]:
+            line += f" (latest: {upd['latest']})"
+        elif upd["latest"] is None:
+            line += " (latest: unchecked — offline or internal mirror)"
+        print(line)
+    if upd["update_available"]:
+        print("update available: run `sharepoint-knowledge update` "
+              "(or pip install -U sharepoint-knowledge[models])")
+    return 0
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="sharepoint-knowledge",
+                                description="Local SharePoint indexer + "
+                                            "grounded-Q&A MCP service")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("setup", help="configure Entra sign-in + site")
+    sub.add_parser("doctor", help="report configuration + model readiness")
+    sub.add_parser("prepare-models", help="download the pinned local models")
+    sub.add_parser("update", help="upgrade this package via pip -U")
+    reg = sub.add_parser("register",
+                         help="write the IDE MCP config automatically")
+    reg.add_argument("--ide", choices=["auto", "all", "jetbrains", "vscode"],
+                     default="auto")
+    reg.add_argument("--workspace", default=None,
+                     help="repo dir for the workspace .vscode/mcp.json")
+    reg.add_argument("--remove", action="store_true",
+                     help="remove our server entry instead of adding it")
+    sub.add_parser("serve", help="run the stdio MCP server")
+    sub.add_parser("clean", help="delete all indexed data")
+
+    args = p.parse_args()
+    if args.cmd == "setup":
+        sys.exit(_setup())
+    if args.cmd == "doctor":
+        sys.exit(_doctor())
+    if args.cmd == "prepare-models":
+        for line in prepare_models(home()):
+            print(line)
+        return
+    if args.cmd == "update":
+        import subprocess
+        cmd = [sys.executable, "-m", "pip", "install", "-U",
+               "sharepoint-knowledge[models]"]
+        if os.name == "nt":
+            print("on Windows, upgrade via the venv python directly:\n  "
+                  + " ".join(f'"{c}"' if " " in c else c for c in cmd))
+            return
+        r = subprocess.run(cmd, check=False)
+        if r.returncode == 0:
+            print("\nupdated — models are pinned and unchanged; "
+                  "run `sharepoint-knowledge doctor` to confirm")
+        sys.exit(r.returncode)
+    if args.cmd == "register":
+        results = _register(
+            ide=args.ide,
+            workspace=Path(args.workspace) if args.workspace else None,
+            remove=args.remove,
+            server_id=APP_NAME,
+            module="sharepoint_knowledge.server_sp",
+            env_var="SP_KNOWLEDGE_WORKDIR")
+        for path, action in results:
+            print(f"{action}: {path}")
+        if args.remove:
+            print("removed — reload the IDE to drop the server")
+        else:
+            print("registered — reload the IDE so the tools appear")
+        return
+    if args.cmd == "serve":
+        from .server_sp import main as serve
+        serve()
+        return
+    if args.cmd == "clean":
+        import shutil
+
+        from .settings_sp import index_root
+        d = index_root()
+        if d.exists():
+            shutil.rmtree(d)
+            print(f"deleted {d}")
+        else:
+            print("nothing to clean")
+        return
+
+
+if __name__ == "__main__":
+    main()

sharepoint_knowledge-0.1.0/src/sharepoint_knowledge/client_sp.py

@@ -0,0 +1,69 @@
+"""GET-only Microsoft Graph client for sharepoint-knowledge.
+
+Reuses the allowlist + GET-only machinery of the Confluence client: every
+request passes through the same `_validate_path` — the only Graph routes
+allowed are the read ones the crawler needs. File downloads use the
+pre-authenticated `@microsoft.graph.downloadUrl` fetched WITHOUT the Bearer
+header — the token never leaves graph.microsoft.com.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlparse
+
+import httpx
+from confluence_knowledge.client import (
+    AccessError,
+    ConfluenceClient,
+    EndpointRule,
+    SecurityException,
+)
+
+GRAPH_RULES = [
+    EndpointRule(re.compile(r"sites/[^/]+:.*"), "site by hostname:path"),
+    EndpointRule(re.compile(r"sites/[^/]+$"), "site info"),
+    EndpointRule(re.compile(r"sites/[^/]+/lists/?$"), "site lists"),
+    EndpointRule(re.compile(r"sites/[^/]+/lists/[^/]+/items/?$"), "list items"),
+    EndpointRule(re.compile(r"sites/[^/]+/lists/[^/]+/items/[^/]+/?$"), "list item"),
+    EndpointRule(re.compile(r"sites/[^/]+/pages/?$"), "site pages"),
+    EndpointRule(re.compile(r"sites/[^/]+/pages/[^/]+/?$"), "site page"),
+    EndpointRule(re.compile(r"sites/[^/]+/drives/?$"), "document libraries"),
+    EndpointRule(re.compile(r"sites/[^/]+/drive/?$"), "default drive"),
+    EndpointRule(re.compile(r"sites/[^/]+/drive/root:.+"), "item by path"),
+    EndpointRule(re.compile(r"drives/[^/]+/root/children/?$"), "library root"),
+    EndpointRule(re.compile(r"drives/[^/]+/items/[^/]+/children/?$"), "folder children"),
+    EndpointRule(re.compile(r"drives/[^/]+/items/[^/]+/?$"), "item metadata"),
+    EndpointRule(re.compile(r"me/?$"), "identity"),
+]
+
+
+def make_client(base_url: str, token: str) -> ConfluenceClient:
+    """Graph client — Bearer stays on the API host only."""
+    return ConfluenceClient(base_url, {"Authorization": f"Bearer {token}"},
+                            GRAPH_RULES)
+
+
+def download_file(url: str, max_bytes: int = 25 * 1024 * 1024) -> bytes:
+    """Fetch a pre-authenticated downloadUrl — NO Authorization header.
+
+    The URL embeds a short-lived download token; sending our Bearer would
+    leak it to a different host (and is unnecessary — these links are
+    self-authenticating). https only (localhost allowed for tests).
+    """
+    u = urlparse(url)
+    if u.scheme != "https" and u.hostname not in ("localhost", "127.0.0.1"):
+        raise SecurityException(
+            "download URL isn't https — refusing to fetch")
+    with httpx.Client(timeout=60.0, follow_redirects=True) as http, \
+            http.stream("GET", url) as r:
+        # bounded stream — don't buffer an unbounded response
+        if r.status_code >= 400:
+            raise AccessError(f"download failed: HTTP {r.status_code}")
+        out = bytearray()
+        for chunk in r.iter_bytes(1 << 20):
+            out += chunk
+            if len(out) > max_bytes:
+                raise AccessError(
+                    f"file exceeds {max_bytes} bytes — refusing to buffer")
+        return bytes(out)