mcp-eregistrations-bpa 0.8.5__py3-none-any.whl

mcp_eregistrations_bpa/server.py

@@ -0,0 +1,152 @@
+"""MCP server for eRegistrations BPA platform."""
+
+from fastmcp import FastMCP
+
+from mcp_eregistrations_bpa.auth import (
+    TokenManager,
+    perform_browser_login,
+    perform_cas_browser_login,
+)
+from mcp_eregistrations_bpa.config import AuthProvider, load_config
+from mcp_eregistrations_bpa.tools import (
+    register_action_tools,
+    register_analysis_tools,
+    register_audit_tools,
+    register_behaviour_tools,
+    register_bot_tools,
+    register_classification_tools,
+    register_cost_tools,
+    register_debug_tools,
+    register_determinant_tools,
+    register_document_requirement_tools,
+    register_export_tools,
+    register_field_tools,
+    register_form_tools,
+    register_message_tools,
+    register_notification_tools,
+    register_registration_institution_tools,
+    register_registration_tools,
+    register_role_status_tools,
+    register_role_tools,
+    register_role_unit_tools,
+    register_rollback_tools,
+    register_service_tools,
+    register_workflow_tools,
+)
+
+mcp = FastMCP("eregistrations-bpa")
+
+# Register BPA tools
+register_service_tools(mcp)
+register_registration_tools(mcp)
+register_registration_institution_tools(mcp)
+register_field_tools(mcp)
+register_form_tools(mcp)
+register_determinant_tools(mcp)
+register_action_tools(mcp)
+register_behaviour_tools(mcp)
+register_bot_tools(mcp)
+register_classification_tools(mcp)
+register_notification_tools(mcp)
+register_message_tools(mcp)
+register_role_tools(mcp)
+register_role_status_tools(mcp)
+register_role_unit_tools(mcp)
+register_document_requirement_tools(mcp)
+register_cost_tools(mcp)
+register_analysis_tools(mcp)
+register_audit_tools(mcp)
+register_rollback_tools(mcp)
+register_export_tools(mcp)
+register_workflow_tools(mcp)
+register_debug_tools(mcp)
+
+# Global token manager instance (in-memory storage)
+_token_manager = TokenManager()
+
+
+@mcp.tool()
+async def auth_login() -> dict[str, object]:
+    """Authenticate with BPA via browser-based Keycloak login.
+
+    This tool initiates the OIDC authentication flow:
+    1. Discovers Keycloak endpoints from BPA instance
+    2. Opens browser to Keycloak login page
+    3. Waits for callback with authorization code
+    4. Exchanges code for tokens
+    5. Returns success with user info
+
+    Returns:
+        dict: Authentication result with user email and session duration.
+    """
+    config = load_config()
+
+    if config.auth_provider == AuthProvider.CAS:
+        return await perform_cas_browser_login()
+    else:
+        return await perform_browser_login()
+
+
+async def get_connection_status() -> dict[str, object]:
+    """Get current BPA connection status (internal implementation).
+
+    Returns connection state, authenticated user, permissions, and session info.
+    This is a read-only operation that does not trigger token refresh.
+
+    Returns:
+        dict: Connection status with instance URL, instance_id, user, permissions,
+        and expiry.
+    """
+    config = load_config()
+
+    # Check if not authenticated
+    if not _token_manager.is_authenticated():
+        return {
+            "connected": False,
+            "instance_id": config.instance_id,
+            "instance_url": config.bpa_instance_url,
+            "message": "Not authenticated. Run auth_login to connect.",
+        }
+
+    # Check if token has already expired
+    if _token_manager.is_token_expired():
+        return {
+            "connected": False,
+            "instance_id": config.instance_id,
+            "instance_url": config.bpa_instance_url,
+            "message": "Session expired. Run auth_login to reconnect.",
+        }
+
+    # Return full authenticated status
+    return {
+        "connected": True,
+        "instance_id": config.instance_id,
+        "instance_url": config.bpa_instance_url,
+        "user": _token_manager.user_email,
+        "permissions": _token_manager.permissions,
+        "session_expires_in": f"{_token_manager.expires_in_minutes} minutes",
+    }
+
+
+@mcp.tool()
+async def connection_status() -> dict[str, object]:
+    """View current BPA connection status.
+
+    Returns connection state, authenticated user, permissions, and session info.
+    This is a read-only operation that does not trigger token refresh.
+
+    Returns:
+        dict: Connection status with instance URL, user, permissions, and expiry.
+    """
+    return await get_connection_status()
+
+
+def get_token_manager() -> TokenManager:
+    """Get the global token manager instance.
+
+    This is used by other modules to access the authenticated session.
+
+    Returns:
+        The global TokenManager instance.
+    """
+    return _token_manager

mcp_eregistrations_bpa/tools/__init__.py

@@ -0,0 +1,372 @@
+"""MCP tools for BPA operations.
+
+This module provides tools for interacting with the BPA API through MCP.
+"""
+
+from mcp_eregistrations_bpa.tools.actions import (
+    componentaction_get,
+    componentaction_get_by_component,
+    register_action_tools,
+)
+from mcp_eregistrations_bpa.tools.analysis import (
+    analyze_service,
+    register_analysis_tools,
+)
+from mcp_eregistrations_bpa.tools.audit import (
+    audit_get,
+    audit_list,
+    register_audit_tools,
+)
+from mcp_eregistrations_bpa.tools.behaviours import (
+    componentbehaviour_get,
+    componentbehaviour_get_by_component,
+    componentbehaviour_list,
+    effect_create,
+    effect_delete,
+    register_behaviour_tools,
+)
+from mcp_eregistrations_bpa.tools.bots import (
+    bot_create,
+    bot_delete,
+    bot_get,
+    bot_list,
+    bot_update,
+    register_bot_tools,
+)
+from mcp_eregistrations_bpa.tools.classifications import (
+    classification_create,
+    classification_export_csv,
+    classification_get,
+    classification_list,
+    classification_update,
+    register_classification_tools,
+)
+from mcp_eregistrations_bpa.tools.costs import (
+    cost_create_fixed,
+    cost_create_formula,
+    cost_delete,
+    cost_update,
+    register_cost_tools,
+)
+from mcp_eregistrations_bpa.tools.debugger import (
+    debug_fix,
+    debug_fix_batch,
+    debug_group_issues,
+    debug_investigate,
+    debug_plan,
+    debug_scan,
+    debug_verify,
+    register_debug_tools,
+)
+from mcp_eregistrations_bpa.tools.determinants import (
+    booleandeterminant_create,
+    classificationdeterminant_create,
+    datedeterminant_create,
+    determinant_delete,
+    determinant_get,
+    determinant_list,
+    determinant_search,
+    griddeterminant_create,
+    numericdeterminant_create,
+    register_determinant_tools,
+    selectdeterminant_create,
+    textdeterminant_create,
+    textdeterminant_update,
+)
+from mcp_eregistrations_bpa.tools.document_requirements import (
+    documentrequirement_create,
+    documentrequirement_delete,
+    documentrequirement_list,
+    documentrequirement_update,
+    register_document_requirement_tools,
+    requirement_list,
+)
+from mcp_eregistrations_bpa.tools.export import (
+    register_export_tools,
+    service_copy,
+    service_export_raw,
+    service_to_yaml,
+)
+from mcp_eregistrations_bpa.tools.fields import (
+    field_get,
+    field_list,
+    register_field_tools,
+)
+from mcp_eregistrations_bpa.tools.formio_helpers import (
+    build_checkbox,
+    build_columns,
+    build_number,
+    build_panel,
+    build_select,
+    build_textarea,
+    build_textfield,
+)
+from mcp_eregistrations_bpa.tools.forms import (
+    form_component_add,
+    form_component_get,
+    form_component_move,
+    form_component_remove,
+    form_component_update,
+    form_get,
+    form_update,
+    register_form_tools,
+)
+from mcp_eregistrations_bpa.tools.messages import (
+    message_create,
+    message_delete,
+    message_get,
+    message_list,
+    message_update,
+    register_message_tools,
+)
+from mcp_eregistrations_bpa.tools.notifications import (
+    notification_create,
+    notification_list,
+    register_notification_tools,
+)
+from mcp_eregistrations_bpa.tools.registration_institutions import (
+    institution_create,
+    institution_discover,
+    register_registration_institution_tools,
+    registrationinstitution_create,
+    registrationinstitution_delete,
+    registrationinstitution_get,
+    registrationinstitution_list,
+    registrationinstitution_list_by_institution,
+)
+from mcp_eregistrations_bpa.tools.registrations import (
+    register_registration_tools,
+    registration_activate,
+    registration_create,
+    registration_delete,
+    registration_get,
+    registration_list,
+    serviceregistration_link,
+)
+from mcp_eregistrations_bpa.tools.role_status import (
+    register_role_status_tools,
+    rolestatus_create,
+    rolestatus_delete,
+    rolestatus_get,
+    rolestatus_update,
+)
+from mcp_eregistrations_bpa.tools.role_units import (
+    register_role_unit_tools,
+    roleunit_create,
+    roleunit_delete,
+    roleunit_get,
+    roleunit_list,
+)
+from mcp_eregistrations_bpa.tools.roles import (
+    register_role_tools,
+    role_create,
+    role_delete,
+    role_get,
+    role_list,
+    role_update,
+    roleinstitution_create,
+    roleregistration_create,
+)
+from mcp_eregistrations_bpa.tools.rollback import (
+    register_rollback_tools,
+    rollback,
+    rollback_cleanup,
+    rollback_history,
+)
+from mcp_eregistrations_bpa.tools.services import (
+    register_service_tools,
+    service_activate,
+    service_create,
+    service_get,
+    service_list,
+    service_publish,
+    service_update,
+)
+from mcp_eregistrations_bpa.tools.workflows import (
+    register_workflow_tools,
+    workflow_cancel,
+    workflow_chain,
+    workflow_confirm,
+    workflow_continue,
+    workflow_describe,
+    workflow_execute,
+    workflow_list,
+    workflow_retry,
+    workflow_rollback,
+    workflow_search,
+    workflow_start_interactive,
+    workflow_status,
+)
+
+__all__ = [
+    # Service tools
+    "service_list",
+    "service_get",
+    "service_create",
+    "service_update",
+    "service_publish",
+    "service_activate",
+    "register_service_tools",
+    # Registration tools
+    "registration_list",
+    "registration_get",
+    "registration_create",
+    "registration_delete",
+    "registration_activate",
+    "serviceregistration_link",
+    "register_registration_tools",
+    # Registration institution tools
+    "registrationinstitution_list",
+    "registrationinstitution_get",
+    "registrationinstitution_create",
+    "registrationinstitution_delete",
+    "registrationinstitution_list_by_institution",
+    "institution_discover",
+    "institution_create",
+    "register_registration_institution_tools",
+    # Field tools
+    "field_list",
+    "field_get",
+    "register_field_tools",
+    # Form tools
+    "form_get",
+    "form_component_get",
+    "form_component_add",
+    "form_component_update",
+    "form_component_remove",
+    "form_component_move",
+    "form_update",
+    "register_form_tools",
+    # Form.io component builders
+    "build_textfield",
+    "build_number",
+    "build_select",
+    "build_checkbox",
+    "build_textarea",
+    "build_panel",
+    "build_columns",
+    # Determinant tools
+    "determinant_list",
+    "determinant_get",
+    "determinant_search",
+    "determinant_delete",
+    "textdeterminant_create",
+    "textdeterminant_update",
+    "selectdeterminant_create",
+    "numericdeterminant_create",
+    "booleandeterminant_create",
+    "datedeterminant_create",
+    "classificationdeterminant_create",
+    "griddeterminant_create",
+    "register_determinant_tools",
+    # Behaviour/Effect tools
+    "componentbehaviour_list",
+    "componentbehaviour_get",
+    "componentbehaviour_get_by_component",
+    "effect_create",
+    "effect_delete",
+    "register_behaviour_tools",
+    # Component action tools
+    "componentaction_get",
+    "componentaction_get_by_component",
+    "register_action_tools",
+    # Bot tools
+    "bot_list",
+    "bot_get",
+    "bot_create",
+    "bot_update",
+    "bot_delete",
+    "register_bot_tools",
+    # Classification tools
+    "classification_list",
+    "classification_get",
+    "classification_create",
+    "classification_update",
+    "classification_export_csv",
+    "register_classification_tools",
+    # Notification tools
+    "notification_list",
+    "notification_create",
+    "register_notification_tools",
+    # Role tools
+    "role_list",
+    "role_get",
+    "role_create",
+    "role_update",
+    "role_delete",
+    "roleinstitution_create",
+    "roleregistration_create",
+    "register_role_tools",
+    # Role status tools
+    "rolestatus_get",
+    "rolestatus_create",
+    "rolestatus_update",
+    "rolestatus_delete",
+    "register_role_status_tools",
+    # Role unit tools
+    "roleunit_list",
+    "roleunit_get",
+    "roleunit_create",
+    "roleunit_delete",
+    "register_role_unit_tools",
+    # Message tools
+    "message_list",
+    "message_get",
+    "message_create",
+    "message_update",
+    "message_delete",
+    "register_message_tools",
+    # Analysis tools
+    "analyze_service",
+    "register_analysis_tools",
+    # Document requirement tools
+    "requirement_list",
+    "documentrequirement_list",
+    "documentrequirement_create",
+    "documentrequirement_update",
+    "documentrequirement_delete",
+    "register_document_requirement_tools",
+    # Cost tools
+    "cost_create_fixed",
+    "cost_create_formula",
+    "cost_update",
+    "cost_delete",
+    "register_cost_tools",
+    # Audit tools
+    "audit_list",
+    "audit_get",
+    "register_audit_tools",
+    # Rollback tools
+    "rollback",
+    "rollback_history",
+    "rollback_cleanup",
+    "register_rollback_tools",
+    # Export tools
+    "service_export_raw",
+    "service_to_yaml",
+    "service_copy",
+    "register_export_tools",
+    # Workflow orchestration tools
+    "workflow_list",
+    "workflow_describe",
+    "workflow_search",
+    "workflow_execute",
+    "workflow_status",
+    "workflow_cancel",
+    "workflow_retry",
+    "workflow_rollback",
+    "workflow_chain",
+    "workflow_start_interactive",
+    "workflow_continue",
+    "workflow_confirm",
+    "register_workflow_tools",
+    # Debug tools
+    "debug_scan",
+    "debug_investigate",
+    "debug_fix",
+    "debug_fix_batch",
+    "debug_group_issues",
+    "debug_plan",
+    "debug_verify",
+    "register_debug_tools",
+]

mcp_eregistrations_bpa/tools/actions.py

@@ -0,0 +1,155 @@
+"""Component action tools for BPA API.
+
+This module provides MCP tools for retrieving component actions
+from the BPA API. Component actions define workflow automation
+configured for form components.
+
+Tools:
+    componentaction_get: Get component actions by ID
+    componentaction_get_by_component: Get actions for a form component
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp.exceptions import ToolError
+
+from mcp_eregistrations_bpa.bpa_client import BPAClient
+from mcp_eregistrations_bpa.bpa_client.errors import (
+    BPAClientError,
+    BPANotFoundError,
+    translate_error,
+)
+
+__all__ = [
+    "componentaction_get",
+    "componentaction_get_by_component",
+    "register_action_tools",
+]
+
+
+async def componentaction_get(id: str) -> dict[str, Any]:
+    """Get component actions by ID.
+
+    Args:
+        id: The unique identifier of the component actions record.
+
+    Returns:
+        dict with id, service_id, component_key, actions.
+    """
+    try:
+        async with BPAClient() as client:
+            try:
+                data = await client.get(
+                    "/componentactions/{id}",
+                    path_params={"id": id},
+                    resource_type="componentactions",
+                    resource_id=id,
+                )
+            except BPANotFoundError:
+                raise ToolError(
+                    f"ComponentActions '{id}' not found. Verify the ID is correct."
+                )
+    except ToolError:
+        raise
+    except BPAClientError as e:
+        raise translate_error(e, resource_type="componentactions", resource_id=id)
+
+    return _transform_component_actions(data)
+
+
+async def componentaction_get_by_component(
+    service_id: str | int, component_key: str
+) -> dict[str, Any]:
+    """Get component actions for a specific form component.
+
+    Args:
+        service_id: The service containing the component.
+        component_key: The form component key/identifier.
+
+    Returns:
+        dict with id, service_id, component_key, actions.
+    """
+    try:
+        async with BPAClient() as client:
+            try:
+                data = await client.get(
+                    "/service/{service_id}/componentactions/{component_key}",
+                    path_params={
+                        "service_id": service_id,
+                        "component_key": component_key,
+                    },
+                    resource_type="componentactions",
+                )
+            except BPANotFoundError:
+                raise ToolError(
+                    f"No actions found for component '{component_key}' "
+                    f"in service '{service_id}'."
+                )
+    except ToolError:
+        raise
+    except BPAClientError as e:
+        raise translate_error(e, resource_type="componentactions")
+
+    return _transform_component_actions(data)
+
+
+def _transform_bot(bot: dict[str, Any]) -> dict[str, Any]:
+    """Transform a bot object from camelCase to snake_case.
+
+    Args:
+        bot: Raw bot object from API.
+
+    Returns:
+        dict: Transformed bot with snake_case keys.
+    """
+    return {
+        "bot_type": bot.get("botType"),
+        "name": bot.get("name"),
+        "description": bot.get("description"),
+        "enabled": bot.get("enabled", True),
+    }
+
+
+def _transform_component_actions(data: dict[str, Any]) -> dict[str, Any]:
+    """Transform API response to snake_case format.
+
+    Args:
+        data: Raw API response with camelCase keys.
+
+    Returns:
+        dict: Transformed response with snake_case keys.
+    """
+    actions = []
+    for action in data.get("actions", []):
+        bots = [_transform_bot(bot) for bot in action.get("bots", [])]
+        actions.append(
+            {
+                "id": action.get("id"),
+                "json_determinants": action.get("jsonDeterminants"),
+                "bots": bots,
+                "sort_order": action.get("sortOrderNumber"),
+                "parallel": action.get("parallel", False),
+                "mandatory": action.get("mandatory", False),
+                "multiple_bot": action.get("multipleBot", False),
+                "multiple_field_key": action.get("multipleFieldKey"),
+            }
+        )
+
+    return {
+        "id": data.get("id"),
+        "service_id": data.get("serviceId"),
+        "component_key": data.get("componentKey"),
+        "actions": actions,
+    }
+
+
+def register_action_tools(mcp: Any) -> None:
+    """Register action tools with the MCP server.
+
+    Args:
+        mcp: The FastMCP server instance.
+    """
+    mcp.tool()(componentaction_get)
+    mcp.tool()(componentaction_get_by_component)