arcanna-mcp-server 0.1.0__tar.gz

arcanna_mcp_server-0.1.0/.github/workflows/build_image_and_package.yml

@@ -0,0 +1,83 @@
+name: Build and Publish Docker Image and Pypi package
+
+on:
+  push:
+    branches:
+      - master
+      - test-build
+  workflow_dispatch:
+
+jobs:
+  # First job to request approval
+#  request-approval:
+#    runs-on: ubuntu-latest
+#    steps:
+#      - name: Request approval
+#        uses: trstringer/manual-approval@v1
+#        with:
+#          secret: ${{ secrets.GITHUB_TOKEN }}
+#          approvers: DenisStefanAndrei,alinmanolache,AlexCornigeanu,marian-craciunescu,marius-avram,mateibm,AndreiTudose95,smmihai,RazvanKokovicsSiscale,hutanmihai,aburnaz
+#          minimum-approvals: 1
+#          issue-title: "Approval needed for Docker image push"
+#          issue-body: "Please approve this workflow to push a new Docker image to DockerHub"
+#          exclude-workflow-initiator-as-approver: false
+#          timeout-minutes: 120
+
+  deploy:
+    runs-on: ubuntu-latest
+    environment: pypi-publish
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install uv
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+
+    - name: Install dependencies from pyproject.toml
+      run: |
+        uv pip install  --system . 
+
+    - name: Build package
+      run: uv build
+
+    - name: Verify package
+      run: |
+        ls -la dist/
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Second job to build and push Docker image
+#  build-and-push:
+#    needs: request-approval  # This ensures the approval job completes first
+#    runs-on: ubuntu-latest
+#    steps:
+#      - name: Checkout code
+#        uses: actions/checkout@v3
+#
+#      - name: Set up Docker Buildx
+#        uses: docker/setup-buildx-action@v2
+#
+#      - name: Login to DockerHub
+#        uses: docker/login-action@v2
+#        with:
+#          username: devsiscale
+#          password: ${{ secrets.DOCKERHUB_DEVSISCALE_PAT }}
+#
+#      - name: Build and push
+#        uses: docker/build-push-action@v4
+#        with:
+#          context: .
+#          push: true
+#          tags: arcanna/arcanna-mcp-server:latest

arcanna_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.idea
+.env
+.venv
+__pycache__/

arcanna_mcp_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

arcanna_mcp_server-0.1.0/Dockerfile

@@ -0,0 +1,36 @@
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS uv
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev --no-editable
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-editable
+
+FROM python:3.12-slim-bookworm
+
+WORKDIR /app
+ 
+COPY --from=uv /root/.local /root/.local
+COPY --from=uv --chown=app:app /app/.venv /app/.venv
+
+# Place executables in the environment at the front of the path
+ENV PATH="/app/.venv/bin:$PATH"
+
+# when running the container, add --db-path and a bind mount to the host's db file
+ENTRYPOINT ["arcanna-mcp-server"]

arcanna_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: arcanna-mcp-server
+Version: 0.1.0
+Summary: The Arcanna MCP server allows user to interact with Arcanna's AI use cases through the Model Context Protocol (MCP).
+Project-URL: homepage, https://github.com/siscale/arcanna-mcp-server
+Author-email: DevSiscale <dev@siscale.com>
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.6
+Requires-Dist: mcp[cli]>=1.2.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: starlette>=0.46.0
+Requires-Dist: uv>=0.6.9
+Requires-Dist: uvx>=2.5.1
+Description-Content-Type: text/markdown
+
+# Arcanna MCP Server
+
+The Arcanna MCP server allows user to interact with Arcanna's AI use cases through the Model Context Protocol (MCP).
+
+## Usage with Claude Desktop or other MCP Clients
+
+### Option 1 - uvx
+#### Prerequisites
+- uv - https://docs.astral.sh/uv/getting-started/installation/#installation-methods
+
+#### Configuration
+Add the following entry to the `mcpServers` section in your MCP client config file (`claude_desktop_config.json` for Claude
+Desktop).
+
+```json
+{
+  "mcpServers": {
+    "arcanna": {
+      "command": "uvx",
+      "args": [
+        "arcanna-mcp"
+      ],
+      "env": {
+        "ARCANNA_INPUT_API_KEY": "YOUR_ARCANNA_INPUT_API_KEY",
+        "ARCANNA_MANAGEMENT_API_KEY": "YOUR_ARCANNA_MANAGEMENT_API_KEY",
+        "ARCANNA_HOST": "YOUR_ARCANNA_HOST",
+        "ARCANNA_USER": "YOUR_USERNAME"
+      }
+    }
+  }
+}
+```
+
+### Option 2 - Building local image from this repository
+#### Prerequisites
+- Docker - https://docs.docker.com/engine/install/
+
+#### Configuration
+1. Change directory to the directory where the Dockerfile is.
+2. Run ```docker build -t mcp/arcanna . --progress=plain --no-cache```
+3. Add the configuration bellow to your claude desktop config.
+```json
+{
+  "mcpServers": {
+    "arcanna-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "ARCANNA_INPUT_API_KEY",
+        "-e",
+        "ARCANNA_MANAGEMENT_API_KEY",
+        "-e",
+        "ARCANNA_HOST",
+        "-e",
+        "ARCANNA_USER",
+        "mcp/arcanna"
+      ],
+      "env": {
+        "ARCANNA_INPUT_API_KEY": "<YOUR_ARCANNA_API_KEY_HERE>",
+        "ARCANNA_MANAGEMENT_API_KEY": "<ARCANNA_MANAGEMENT_API_KEY>",
+        "ARCANNA_HOST": "<YOUR_ARCANNA_HOST_HERE>",
+        "ARCANNA_USER": "<YOUR_USERNAME_HERE>"
+      }
+    }
+  }
+}
+```
+
+
+## Features
+
+- **Job Management**: Create, retrieve, start, stop, and train jobs
+- **Event Processing**: Send events for AI-powered decision making
+- **Feedback System**: Provide feedback on decisions to improve model accuracy
+- **Health Monitoring**: Check server and API key status
+
+## Tools
+
+### Job Management
+- **get_jobs**
+  - Retrieve all jobs associated with your API key
+  - Returns a list of job details including status, labels, and processing metrics
+
+- **get_job_by_id**
+  - Retrieve specific job details by ID
+
+- **get_job_by_name**
+  - Retrieve specific job details by name
+
+- **get_job_labels**
+  - Retrieve decision labels for a specific job
+
+- **get_labels_of_job_by_name**
+  - Retrieve decision labels for a job by name
+
+- **start_job**
+  - Begin event ingestion for a job
+
+- **stop_job**
+  - Stop event ingestion for a job
+
+- **train_job**
+  - Train the job's AI model using the provided feedback
+
+### Event Management
+- **send_event**
+  - Submit an event to Arcanna for AI decision-making
+
+- **send_event_with_id**
+  - Submit an event with a custom identifier
+
+- **get_event_by_id**
+  - Retrieve event details and decision results
+
+### Feedback System
+- **send_feedback_for_event**
+  - Provide feedback on AI decisions for model improvement
+
+### System Health
+- **health_check**
+  - Verify server status and API key validity
+  - Returns API key authorization status
+

arcanna_mcp_server-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Arcanna MCP Server
+
+The Arcanna MCP server allows user to interact with Arcanna's AI use cases through the Model Context Protocol (MCP).
+
+## Usage with Claude Desktop or other MCP Clients
+
+### Option 1 - uvx
+#### Prerequisites
+- uv - https://docs.astral.sh/uv/getting-started/installation/#installation-methods
+
+#### Configuration
+Add the following entry to the `mcpServers` section in your MCP client config file (`claude_desktop_config.json` for Claude
+Desktop).
+
+```json
+{
+  "mcpServers": {
+    "arcanna": {
+      "command": "uvx",
+      "args": [
+        "arcanna-mcp"
+      ],
+      "env": {
+        "ARCANNA_INPUT_API_KEY": "YOUR_ARCANNA_INPUT_API_KEY",
+        "ARCANNA_MANAGEMENT_API_KEY": "YOUR_ARCANNA_MANAGEMENT_API_KEY",
+        "ARCANNA_HOST": "YOUR_ARCANNA_HOST",
+        "ARCANNA_USER": "YOUR_USERNAME"
+      }
+    }
+  }
+}
+```
+
+### Option 2 - Building local image from this repository
+#### Prerequisites
+- Docker - https://docs.docker.com/engine/install/
+
+#### Configuration
+1. Change directory to the directory where the Dockerfile is.
+2. Run ```docker build -t mcp/arcanna . --progress=plain --no-cache```
+3. Add the configuration bellow to your claude desktop config.
+```json
+{
+  "mcpServers": {
+    "arcanna-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "ARCANNA_INPUT_API_KEY",
+        "-e",
+        "ARCANNA_MANAGEMENT_API_KEY",
+        "-e",
+        "ARCANNA_HOST",
+        "-e",
+        "ARCANNA_USER",
+        "mcp/arcanna"
+      ],
+      "env": {
+        "ARCANNA_INPUT_API_KEY": "<YOUR_ARCANNA_API_KEY_HERE>",
+        "ARCANNA_MANAGEMENT_API_KEY": "<ARCANNA_MANAGEMENT_API_KEY>",
+        "ARCANNA_HOST": "<YOUR_ARCANNA_HOST_HERE>",
+        "ARCANNA_USER": "<YOUR_USERNAME_HERE>"
+      }
+    }
+  }
+}
+```
+
+
+## Features
+
+- **Job Management**: Create, retrieve, start, stop, and train jobs
+- **Event Processing**: Send events for AI-powered decision making
+- **Feedback System**: Provide feedback on decisions to improve model accuracy
+- **Health Monitoring**: Check server and API key status
+
+## Tools
+
+### Job Management
+- **get_jobs**
+  - Retrieve all jobs associated with your API key
+  - Returns a list of job details including status, labels, and processing metrics
+
+- **get_job_by_id**
+  - Retrieve specific job details by ID
+
+- **get_job_by_name**
+  - Retrieve specific job details by name
+
+- **get_job_labels**
+  - Retrieve decision labels for a specific job
+
+- **get_labels_of_job_by_name**
+  - Retrieve decision labels for a job by name
+
+- **start_job**
+  - Begin event ingestion for a job
+
+- **stop_job**
+  - Stop event ingestion for a job
+
+- **train_job**
+  - Train the job's AI model using the provided feedback
+
+### Event Management
+- **send_event**
+  - Submit an event to Arcanna for AI decision-making
+
+- **send_event_with_id**
+  - Submit an event with a custom identifier
+
+- **get_event_by_id**
+  - Retrieve event details and decision results
+
+### Feedback System
+- **send_feedback_for_event**
+  - Provide feedback on AI decisions for model improvement
+
+### System Health
+- **health_check**
+  - Verify server status and API key validity
+  - Returns API key authorization status
+

arcanna_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "arcanna-mcp-server"
+authors = [
+  { name="DevSiscale", email="dev@siscale.com" },
+]
+version = "0.1.0"
+description = "The Arcanna MCP server allows user to interact with Arcanna's AI use cases through the Model Context Protocol (MCP)."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.2.1",
+    "requests>=2.32.3",
+    "fastapi>=0.115.6",
+    "starlette>=0.46.0",
+    "uv>=0.6.9",
+    "uvx>=2.5.1"
+]
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = ["pyright>=1.1.389"]
+
+[project.scripts]
+arcanna-mcp-server = "arcanna_mcp_server:main"
+
+[project.urls]
+homepage = "https://github.com/siscale/arcanna-mcp-server"

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/__init__.py

@@ -0,0 +1,7 @@
+from arcanna_mcp_server.environment import validate_environment_variables
+from . import server
+
+
+def main():
+    validate_environment_variables()
+    server.main()

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/constants.py

@@ -0,0 +1,36 @@
+from arcanna_mcp_server.environment import ARCANNA_HOST
+
+# event ingestion
+SEND_EVENT_URL = ARCANNA_HOST + "/api/v1/events"
+SEND_EVENT_WITH_ID_URL = ARCANNA_HOST + "/api/v1/events/{}"
+
+# event retrieval
+RETRIEVE_EVENT_BY_ID_URL = ARCANNA_HOST + "/api/v1/events/{}/{}"  # /job_id/event_id
+
+# event feedback
+EVENT_FEEDBACK_URL = ARCANNA_HOST + "/api/v1/events/{}/{}/feedback"
+
+GET_JOBS_URL = ARCANNA_HOST + "/api/v1/jobs"
+GET_JOB_BY_ID_URL = ARCANNA_HOST + "/api/v1/jobs/{}"
+GET_JOB_LABELS_URL = ARCANNA_HOST + "/api/v1/jobs/{}/labels"
+START_JOB_URL = ARCANNA_HOST + "/api/v1/jobs/{}/start"
+STOP_JOB_URL = ARCANNA_HOST + "/api/v1/jobs/{}/stop"
+TRAIN_JOB_URL = ARCANNA_HOST + "/api/v1/jobs/{}/train"
+GET_JOB_BY_NAME_URL = ARCANNA_HOST + "/api/v1/jobs/get_by_name"
+GET_LABELS_OF_JOB_BY_NAME_URL = ARCANNA_HOST + "/api/v1/jobs/get_by_name/labels"
+
+# healthcheck
+HEALTH_CHECK_URL = ARCANNA_HOST + "/api/v1/health/"
+
+# custom code block
+CUSTOM_CODE_BLOCK_TEST_URL = ARCANNA_HOST + "/api/v2/custom_code_execution/test"
+CUSTOM_CODE_BLOCK_SAVE_URL = ARCANNA_HOST + "/api/v2/custom_code_execution/save"
+
+# resources CRUD operations
+RESOURCES_CRUD_URL = ARCANNA_HOST + "/api/v2/resources"
+
+# integration parameters schema
+INTEGRATION_PARAMETERS_SCHEMA_URL = ARCANNA_HOST + "/api/v2/resources/integration/parameters/schema"
+
+# events operations
+QUERY_EVENTS_URL = ARCANNA_HOST + "/api/v2/events/query"

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/environment.py

@@ -0,0 +1,20 @@
+import os
+
+MANAGEMENT_API_KEY = os.getenv("ARCANNA_MANAGEMENT_API_KEY")
+API_KEY = os.getenv("ARCANNA_INPUT_API_KEY")
+ARCANNA_HOST = os.getenv("ARCANNA_HOST", "")
+ARCANNA_USER = "MCP" + "-" + (os.getenv("ARCANNA_USER") or "user")
+TRANSPORT_MODE = os.getenv("TRANSPORT_MODE", "stdio")
+
+
+def validate_environment_variables():
+    if MANAGEMENT_API_KEY is None:
+        raise Exception("Arcanna management api key not found")
+    if API_KEY is None:
+        raise Exception("Arcanna input API KEY not found.")
+
+    if ARCANNA_HOST is None:
+        raise Exception("Arcanna HOST not found.")
+
+    if TRANSPORT_MODE not in ["stdio", "sse"]:
+        raise Exception(f"TRANSPORT_MODE {TRANSPORT_MODE} not supported.")

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/models/base_resource.py

@@ -0,0 +1,108 @@
+
+from pydantic import BaseModel, Field, computed_field
+from typing import Annotated, Any, Dict, List, Literal, Optional, Union
+
+from arcanna_mcp_server.models.resource_type import ResourceType
+
+
+class ApiKeyProperties(BaseModel):
+    name: str
+
+    @computed_field
+    @property
+    def title(self) -> str:
+        return self.name
+
+
+class IntegrationProperties(BaseModel):
+    title: str
+    integration_type: str
+    parameters: Dict[str, Any]
+
+
+class Label(BaseModel):
+    name: str
+    hex_color: str
+
+
+class AutoRetrainOptions(BaseModel):
+    class AutoRetrainBlockers(BaseModel):
+        consensus_flipping: bool = Field(default=False, description="Buckets/events with flipping consensus")
+        low_confidence_score: bool = Field(default=False, description="Buckets/events with low confidence score")
+        undecided_consensus: bool = Field(default=False, description="Bucket/events with undecided consensus")
+        consensus_low_score: bool = Field(default=False, description="Buckets/events with low consensus score")
+        outliers: bool = Field(default=False, description="Outliers")
+        consensus_changes: bool = Field(default=False, description="Consensus changes since last training session")
+
+    enabled: bool
+    cron: str
+    blockers: Optional[AutoRetrainBlockers] = Field(default=None)
+
+
+class MonitoringSettings(BaseModel):
+    class MonitorInfo(BaseModel):
+        name: Literal[
+            "results_with_error_logs_in_last_x_minutes",
+            "error_job_state_in_last_x_minutes",
+            "no_data_processed_in_last_x_minutes"
+        ]
+        active: bool
+        interval_check: int
+
+    throttling: int
+    monitors: List[MonitorInfo]
+
+
+class JobProperties(BaseModel):
+    class PipelineIntegration(BaseModel):
+        resource: str
+        integration_type: str
+        enabled: bool
+        auto_id: Optional[str] = Field(default=None)
+        parameters: Dict[str, Any]
+
+    class Feature(BaseModel):
+        name: str
+        type: str
+
+    class AdvancedSettings(BaseModel):
+        custom_labels: Optional[List[Label]] = Field(default=None)
+        auto_retrain: Optional[AutoRetrainOptions] = Field(default=None, description="Auto retrain settings")
+        monitoring_settings: Optional[MonitoringSettings] = Field(default=None, description="Monitoring settings")
+
+    title: str
+    description: Optional[str] = None
+    category: str
+    features: List[str]
+    feedback_columns: Optional[List[str]] = None
+    advanced_settings: Optional[AdvancedSettings] = None
+    pipeline_integrations: List[PipelineIntegration]
+
+
+ResourcePropertiesType = Union[ApiKeyProperties, IntegrationProperties, JobProperties]
+
+
+class ResourceCommon(BaseModel):
+    type: Any
+    depends_on: Optional[List[str]] = Field(default=[])
+
+
+class ApiKeyResource(ResourceCommon):
+    type: Literal[ResourceType.API_KEY] = ResourceType.API_KEY.value
+    properties: ApiKeyProperties
+
+
+class IntegrationResource(ResourceCommon):
+    type: Literal[ResourceType.INTEGRATION] = ResourceType.INTEGRATION.value
+    properties: IntegrationProperties
+
+
+class JobResource(ResourceCommon):
+    type: Literal[ResourceType.JOB] = ResourceType.JOB.value
+    properties: JobProperties
+
+
+ResourceUnionType = Union[ApiKeyResource, IntegrationResource, JobResource]
+
+
+BaseResource = Annotated[ResourceUnionType, Field(discriminator='type')]

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/models/generic_events.py

@@ -0,0 +1,30 @@
+from typing import Optional, List, Any, Union, Dict, Literal
+from pydantic import BaseModel, Field
+
+
+class Filter(BaseModel):
+    field: str
+    operator: Literal["is", "is not", "is one of", "is not one of", "starts with", "not starts with", "contains", "not contains", "exists", "not exists", "lt", "lte", "gte", "gte"]
+    value: Any
+
+
+class QueryEventsRequest(BaseModel):
+    job_ids: Optional[Union[List[int], int]] = None
+    job_titles: Optional[Union[List[str], str]] = None
+    event_ids: Optional[Union[List[str], str]] = None
+    decision_points_only: Optional[bool] = False
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    size: Optional[int] = Field(default=5)
+    sort_by_column: Optional[str] = Field(default="timestamp_inference")
+    sort_order: Literal['desc', 'asc'] = Field(default="desc")
+    filters: List[Filter] = Field(default_factory=list)
+
+
+class EventModel(BaseModel):
+    event_id: str
+    job_id: int
+    job_title: str
+    decision_points: Dict[str, Any]
+    arcanna: Dict[str, Any]
+    raw_event: Optional[Dict[str, Any]] = None

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/models/resource_type.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class ResourceType(str, Enum):
+    API_KEY = 'api_key'
+    JOB = 'job'
+    INTEGRATION = 'integration'

arcanna_mcp_server-0.1.0/src/arcanna_mcp_server/server.py

@@ -0,0 +1,17 @@
+from mcp.server import FastMCP
+
+from arcanna_mcp_server.environment import TRANSPORT_MODE
+from arcanna_mcp_server.tools import attach_tools
+
+mcp = FastMCP("arcanna_mcp-server")
+
+attach_tools(mcp)
+
+
+def main():
+    # Initialize and run the server
+    mcp.run(transport=TRANSPORT_MODE)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,21 @@
+import arcanna_mcp_server.tools.resources
+from mcp.server import FastMCP
+import arcanna_mcp_server.tools.jobs
+import arcanna_mcp_server.tools.events
+import arcanna_mcp_server.tools.health_check
+import arcanna_mcp_server.tools.custom_code_block
+import arcanna_mcp_server.tools.generic_events
+
+
+def attach_tools(mcp_server: FastMCP):
+    modules = [
+        arcanna_mcp_server.tools.jobs,
+        arcanna_mcp_server.tools.events,
+        arcanna_mcp_server.tools.health_check,
+        arcanna_mcp_server.tools.custom_code_block,
+        arcanna_mcp_server.tools.resources,
+        arcanna_mcp_server.tools.generic_events
+    ]
+    for module in modules:
+        for tool_fn in module.export_tools():
+            mcp_server.add_tool(tool_fn)