alix-graphql-mcp-knowledge-base-tool 0.1.0__tar.gz

alix_graphql_mcp_knowledge_base_tool-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: alix-graphql-mcp-knowledge-base-tool
+Version: 0.1.0
+Summary: Knowledge Base MCP tool for Alix GraphQL. Fetches institution marshaling plans.
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.9.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"

alix_graphql_mcp_knowledge_base_tool-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alix-graphql-mcp-knowledge-base-tool"
+version = "0.1.0"
+description = "Knowledge Base MCP tool for Alix GraphQL. Fetches institution marshaling plans."
+requires-python = ">=3.11"
+dependencies = [
+  "mcp>=1.9.0",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine"]
+
+[project.scripts]
+alix-graphql-mcp-knowledge-base-tool = "alix_graphql_mcp_knowledge_base_tool.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

alix_graphql_mcp_knowledge_base_tool-0.1.0/setup.cfg

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

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool/__init__.py

@@ -0,0 +1,12 @@
+__version__ = "0.1.0"
+
+from alix_graphql_mcp_knowledge_base_tool.mcp_server import (
+    run_get_institution_marshaling_plan,
+    run_get_institution_marshaling_plans,
+)
+
+__all__ = [
+    "__version__",
+    "run_get_institution_marshaling_plan",
+    "run_get_institution_marshaling_plans",
+]

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool/__main__.py

@@ -0,0 +1,6 @@
+"""python -m alix_graphql_mcp_knowledge_base_tool -> stdio MCP."""
+
+from alix_graphql_mcp_knowledge_base_tool.mcp_server import main
+
+if __name__ == "__main__":
+    main()

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool/mcp_server.py

@@ -0,0 +1,373 @@
+"""Knowledge Base MCP server for institution marshaling plans.
+
+Env vars:
+    ALIX_API_URL          required. Base URL (e.g. http://localhost:8080) or full
+                          /graphql URL.
+    ALIX_API_KEY          required. Master token sent as the Authorization header.
+    ALIX_GRAPHQL_TIMEOUT  optional. Request timeout in seconds (default 30).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Literal
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+SERVER_NAME: str = "alix-graphql-mcp-knowledge-base-tool"
+
+AssetCategory = Literal[
+    "BankAccount",
+    "Investment",
+    "LifeInsurance",
+    "PersonalProperty",
+    "RealEstate",
+    "Retirement",
+    "UnclaimedProperty",
+    "Vehicle",
+    "Business",
+    "Cash",
+    "MoneyDueToEstate",
+]
+
+AssetSubcategory = Literal[
+    "Checking",
+    "Savings",
+    "CD",
+    "MoneyMarket",
+    "SafetyDepositBox",
+    "Trust",
+    "IRA",
+    "RothIRA",
+    "K401",
+    "Roth401K",
+    "B457",
+    "B403",
+    "Pension",
+    "Annuity",
+    "ESOP",
+    "Brokerage",
+    "Stocks",
+    "HSA",
+    "PrimaryResidence",
+    "VacationHome",
+    "ResidentialIncomeProperty",
+    "CommercialProperty",
+    "UndevelopedParcel",
+    "Car",
+    "Truck",
+    "RV",
+    "Boat",
+    "Aircraft",
+    "Trailer",
+    "Motorcycle",
+    "SoleProprietorship",
+    "Partnership",
+    "LLC",
+    "Corporation",
+    "SCorporation",
+    "Income",
+    "Refund",
+    "Other",
+]   
+
+AssetDesignation = Literal[
+    "InTrust",
+    "PodTod",
+    "Tod",
+    "JointOwnership",
+    "JointOwnershipWithSurvivorship",
+    "JointTenantsWithRightOfSurvivorship",
+    "TenancyInCommon",
+    "CommunityProperty",
+    "InTheEstate",
+    "OwnerTransferByOperatingAgreement",
+    "Unknown",
+]
+
+_MARSHALING_PLAN_SELECTION = """
+id
+createdAt
+updatedAt
+deletedAt
+institutionId
+assetCategory
+assetDesignation
+assetSubcategory
+contactPhone
+faxNumber
+businessHours
+submissionMethods
+submissionInstructions
+onlinePortalUrl
+typicalProcessingTime
+recommendedFollowUpInterval
+additionalNotes
+metadata
+mailingAddress {
+  id
+  address
+  city
+  county
+  state
+  zip
+  country
+}
+steps(orderBy: [{ order: asc }]) {
+  id
+  order
+  title
+  description
+  config
+}
+forms {
+  id
+  createdAt
+  updatedAt
+  name
+  description
+  isFillable
+  fieldMap
+  fileId
+}
+requiredDocuments {
+  id
+  createdAt
+  updatedAt
+  documentType
+  notes
+}
+"""
+
+_GET_MARSHALING_PLANS_QUERY = f"""
+query GetInstitutionMarshalingPlans($institutionId: String!) {{
+  marshalingPlans(
+    where: {{
+      institutionId: {{ equals: $institutionId }}
+      deletedAt: {{ equals: null }}
+    }}
+    orderBy: [{{ updatedAt: desc }}]
+  ) {{
+    {_MARSHALING_PLAN_SELECTION}
+  }}
+}}
+"""
+
+_GET_MARSHALING_PLAN_QUERY = f"""
+query GetInstitutionMarshalingPlan($where: MarshalingPlanWhereInput!) {{
+  marshalingPlans(
+    where: $where
+    orderBy: [{{ updatedAt: desc }}]
+    take: 2
+  ) {{
+    {_MARSHALING_PLAN_SELECTION}
+  }}
+}}
+"""
+
+
+def  _resolve_endpoint(raw: str) -> str:
+    url = raw.rstrip("/")
+    if url.endswith("/graphql"):
+        return url
+    return f"{url}/graphql"
+
+
+def _read_timeout() -> float:
+    raw = os.environ.get("ALIX_GRAPHQL_TIMEOUT")
+    if not raw:
+        return 30.0
+    try:
+        return float(raw)
+    except ValueError:
+        return 30.0
+
+
+def _graphql_request(
+    *,
+    query: str,
+    variables: dict[str, Any],
+    operation_name: str,
+) -> dict[str, Any]:
+    api_url_raw = os.environ.get("ALIX_API_URL")
+    api_key = os.environ.get("ALIX_API_KEY")
+    if not api_url_raw:
+        return {"errors": [{"message": "ALIX_API_URL is not set."}]}
+    if not api_key:
+        return {"errors": [{"message": "ALIX_API_KEY is not set."}]}
+
+    endpoint = _resolve_endpoint(api_url_raw)
+    timeout = _read_timeout()
+
+    payload: dict[str, Any] = {
+        "query": query,
+        "variables": variables,
+        "operationName": operation_name,
+    }
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": api_key,
+    }
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.post(endpoint, json=payload, headers=headers)
+    except httpx.HTTPError as exc:
+        return {"errors": [{"message": f"Transport error: {exc.__class__.__name__}: {exc}"}]}
+
+    text = response.text
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = None
+
+    if response.is_error:
+        if isinstance(body, dict) and ("errors" in body or "data" in body):
+            return {
+                "data": body.get("data"),
+                "errors": body.get("errors")
+                or [{"message": f"HTTP {response.status_code}: {text or response.reason_phrase}"}],
+                "http_status": response.status_code,
+            }
+        return {
+            "data": None,
+            "errors": [{"message": f"HTTP {response.status_code}: {text or response.reason_phrase}"}],
+            "http_status": response.status_code,
+        }
+
+    if not isinstance(body, dict):
+        return {
+            "data": None,
+            "errors": [{"message": f"Non-JSON response from GraphQL endpoint: {text[:500]}"}],
+            "http_status": response.status_code,
+        }
+
+    return {
+        "data": body.get("data"),
+        "errors": body.get("errors"),
+        "extensions": body.get("extensions"),
+        "http_status": response.status_code,
+    }
+
+
+def _clean_optional_enum(value: str | None) -> str | None:
+    if value is None:
+        return None
+    cleaned = value.strip()
+    if not cleaned:
+        return None
+    return cleaned
+
+
+def run_get_institution_marshaling_plans(institutionId: str) -> str:
+    if not institutionId or not isinstance(institutionId, str):
+        return json.dumps({"errors": [{"message": "institutionId is required."}]})
+
+    result = _graphql_request(
+        query=_GET_MARSHALING_PLANS_QUERY,
+        variables={"institutionId": institutionId},
+        operation_name="GetInstitutionMarshalingPlans",
+    )
+    return json.dumps(result, default=str)
+
+
+def run_get_institution_marshaling_plan(
+    institutionId: str,
+    assetCategory: AssetCategory,
+    assetDesignation: AssetDesignation,
+    assetSubcategory: AssetSubcategory | None = None,
+) -> str:
+    if not institutionId or not isinstance(institutionId, str):
+        return json.dumps({"errors": [{"message": "institutionId is required."}]})
+
+    where: dict[str, Any] = {
+        "institutionId": {"equals": institutionId},
+        "deletedAt": {"equals": None},
+        "assetCategory": {"equals": assetCategory},
+        "assetDesignation": {"equals": assetDesignation},
+    }
+    cleaned_subcategory = _clean_optional_enum(assetSubcategory)
+    if cleaned_subcategory is not None:
+        where["assetSubcategory"] = {"equals": cleaned_subcategory}
+
+    result = _graphql_request(
+        query=_GET_MARSHALING_PLAN_QUERY,
+        variables={"where": where},
+        operation_name="GetInstitutionMarshalingPlan",
+    )
+
+    if result.get("errors"):
+        return json.dumps(result, default=str)
+
+    data = result.get("data") if isinstance(result.get("data"), dict) else {}
+    plans = data.get("marshalingPlans") if isinstance(data, dict) else None
+
+    if not isinstance(plans, list):
+        return json.dumps(
+            {
+                **result,
+                "errors": [{"message": "Unexpected GraphQL response: `marshalingPlans` is missing."}],
+            },
+            default=str,
+        )
+
+    if not plans:
+        return json.dumps(
+            {
+                **result,
+                "data": {"marshalingPlan": None},
+            },
+            default=str,
+        )
+
+    if len(plans) > 1:
+        return json.dumps(
+            {
+                **result,
+                "data": {"marshalingPlan": None},
+                "errors": [
+                    {
+                        "message": (
+                            "Multiple marshaling plans match this filter. "
+                            "Provide additional filters: assetCategory, assetDesignation, assetSubcategory."
+                        )
+                    }
+                ],
+            },
+            default=str,
+        )
+
+    return json.dumps(
+        {
+            **result,
+            "data": {"marshalingPlan": plans[0]},
+        },
+        default=str,
+    )
+
+
+def main() -> None:
+    mcp = FastMCP(SERVER_NAME)
+
+    mcp.tool(
+        name="getInstitutionMarshalingPlans",
+        title="Get institution marshaling plans",
+        description=(
+            "Fetch all active MarshalingPlan records for an institutionId from the Alix GraphQL API. "
+            "Returns raw JSON containing `{data, errors, extensions, http_status}`."
+        ),
+    )(run_get_institution_marshaling_plans)
+
+    mcp.tool(
+        name="getInstitutionMarshalingPlan",
+        title="Get one institution marshaling plan",
+        description=(
+            "Fetch a single active MarshalingPlan for an institutionId with optional filters "
+            "(assetCategory, assetDesignation, assetSubcategory). Returns raw JSON containing "
+            "`{data, errors, extensions, http_status}` and normalizes the payload to `data.marshalingPlan`."
+        ),
+    )(run_get_institution_marshaling_plan)
+
+    mcp.run()

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: alix-graphql-mcp-knowledge-base-tool
+Version: 0.1.0
+Summary: Knowledge Base MCP tool for Alix GraphQL. Fetches institution marshaling plans.
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.9.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+src/alix_graphql_mcp_knowledge_base_tool/__init__.py
+src/alix_graphql_mcp_knowledge_base_tool/__main__.py
+src/alix_graphql_mcp_knowledge_base_tool/mcp_server.py
+src/alix_graphql_mcp_knowledge_base_tool.egg-info/PKG-INFO
+src/alix_graphql_mcp_knowledge_base_tool.egg-info/SOURCES.txt
+src/alix_graphql_mcp_knowledge_base_tool.egg-info/dependency_links.txt
+src/alix_graphql_mcp_knowledge_base_tool.egg-info/entry_points.txt
+src/alix_graphql_mcp_knowledge_base_tool.egg-info/requires.txt
+src/alix_graphql_mcp_knowledge_base_tool.egg-info/top_level.txt

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+alix-graphql-mcp-knowledge-base-tool = alix_graphql_mcp_knowledge_base_tool.mcp_server:main

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool.egg-info/requires.txt

@@ -0,0 +1,6 @@
+mcp>=1.9.0
+httpx>=0.27
+
+[dev]
+build
+twine

alix_graphql_mcp_knowledge_base_tool-0.1.0/src/alix_graphql_mcp_knowledge_base_tool.egg-info/top_level.txt

@@ -0,0 +1 @@
+alix_graphql_mcp_knowledge_base_tool