sentor-mcp 1.0.0__tar.gz

sentor_mcp-1.0.0/.env.example

@@ -0,0 +1,6 @@
+# Required: your Sentor API key
+# Get yours at https://dashboard.sentor.app/settings?tab=api-access
+SENTOR_API_KEY=your_api_key_here
+
+# Optional: override API base URL (defaults to production)
+# SENTOR_BASE_URL=https://sentor.app/api

sentor_mcp-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+.claude-flow/
+__pycache__/
+*.pyc
+*.pyo
+.env
+dist/
+build/
+*.egg-info/
+.venv/
+venv/

sentor_mcp-1.0.0/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml .
+COPY sentor_mcp/ ./sentor_mcp/
+
+RUN pip install --no-cache-dir -e .
+
+ENV SENTOR_BASE_URL=https://sentor.app/api
+
+EXPOSE 8080
+
+CMD ["python", "-m", "sentor_mcp.server_http"]

sentor_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: sentor-mcp
+Version: 1.0.0
+Summary: Sentor AI MCP Server — entity-based sentiment analysis tools for Claude, Cursor, and any MCP-compatible AI assistant
+Project-URL: Homepage, https://sentor.app
+Project-URL: Documentation, https://sentor.app/docs/integrations/mcp
+Project-URL: Repository, https://github.com/NIKX-Tech/sentor-mcp
+Project-URL: Get API Key, https://dashboard.sentor.app/settings?tab=api-access
+Author-email: "NIKX Technologies B.V." <sentor@nikx.one>
+License: MIT
+Keywords: ai,claude,mcp,nlp,sentiment-analysis,sentor
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# Sentor MCP Server
+
+Connect Sentor's entity-based sentiment analysis to Claude, Cursor, Windsurf, and any MCP-compatible AI assistant.
+
+## What It Does
+
+Once installed, your AI assistant gains four tools:
+
+| Tool | What it does |
+|------|-------------|
+| `analyze_sentiment` | Score sentiment toward specific entities in any text |
+| `cluster_documents` | Group 5+ documents by topic automatically (BERTopic) |
+| `name_topic` | Generate a 3-5 word label for each cluster using LLM |
+| `health_check` | Verify Sentor API is reachable |
+
+**Example prompt after setup:** *"Analyze these 50 customer reviews for sentiment toward our checkout flow and shipping speed, then cluster them by topic."*
+
+## Requirements
+
+- Python 3.10+
+- A Sentor API key → [Get one free at dashboard.sentor.app](https://dashboard.sentor.app/settings?tab=api-access)
+
+## Installation
+
+```bash
+pip install sentor-mcp
+```
+
+## Claude Desktop Setup
+
+Add to your `claude_desktop_config.json`:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "sentor": {
+      "command": "sentor-mcp",
+      "env": {
+        "SENTOR_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the Sentor tools available in the tool selector.
+
+## Cursor / Windsurf Setup
+
+Add to your MCP config file (`.cursor/mcp.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "sentor": {
+      "command": "sentor-mcp",
+      "env": {
+        "SENTOR_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once connected, use natural language:
+
+**Sentiment analysis:**
+> "Use Sentor to analyze the sentiment of these reviews toward Apple and iPhone: [paste reviews]"
+
+**Clustering:**
+> "I have 200 customer support tickets. Use Sentor to cluster them by topic and name each cluster."
+
+**Full pipeline:**
+> "Analyze sentiment in these 100 reviews for 'delivery' and 'packaging' entities, then cluster them and name each cluster."
+
+## Tool Reference
+
+### `analyze_sentiment(docs, language="en")`
+
+```python
+docs = [
+    {
+        "doc_id": "review_1",
+        "doc": "The delivery was fast but the packaging was terrible.",
+        "entities": ["delivery", "packaging"]
+    }
+]
+# Returns: predicted_label, probabilities, per-sentence details
+```
+
+### `cluster_documents(documents, language="en")`
+
+```python
+documents = [
+    {"doc_id": "r1", "text": "Great product quality", "entities": ["product"]},
+    # ... at least 5 documents required
+]
+# Returns: clusters with cluster_id, documents, top_words
+```
+
+### `name_topic(cluster_id, documents, top_words, entities, language="en")`
+
+```python
+# Pass the cluster data from cluster_documents response:
+name_topic(
+    cluster_id=0,
+    documents=cluster["documents"],
+    top_words=cluster["top_words"],
+    entities=["BrandName"]  # exclude your brand from the topic label
+)
+# Returns: topic_name (e.g. "Shipping Delay Complaints")
+```
+
+### `health_check()`
+
+```python
+# Returns: { "status": "healthy", "version": "...", "llm_status": "available" }
+```
+
+## Rate Limits
+
+| Plan | Per Minute | Per Month |
+|------|-----------|-----------|
+| Free | 3 | 300 |
+| Starter | 60 | 3,000 |
+| Growth | 200 | 15,000 |
+| Business | 500 | 60,000 |
+| Enterprise | 10,000 | Unlimited |
+
+## Remote Deployment (HTTP/SSE)
+
+To run as a hosted server:
+
+```bash
+docker build -t sentor-mcp .
+docker run -e SENTOR_API_KEY=your_key -p 8080:8080 sentor-mcp
+```
+
+The server exposes SSE at `http://localhost:8080/sse` and can be connected to AI tools that support remote MCP servers.
+
+## Links
+
+- [Sentor Dashboard](https://dashboard.sentor.app)
+- [API Documentation](https://sentor.app/docs)
+- [MCP Integration Guide](https://sentor.app/docs/integrations/mcp)
+- [Support](mailto:sentor@nikx.one)

sentor_mcp-1.0.0/README.md

@@ -0,0 +1,151 @@
+# Sentor MCP Server
+
+Connect Sentor's entity-based sentiment analysis to Claude, Cursor, Windsurf, and any MCP-compatible AI assistant.
+
+## What It Does
+
+Once installed, your AI assistant gains four tools:
+
+| Tool | What it does |
+|------|-------------|
+| `analyze_sentiment` | Score sentiment toward specific entities in any text |
+| `cluster_documents` | Group 5+ documents by topic automatically (BERTopic) |
+| `name_topic` | Generate a 3-5 word label for each cluster using LLM |
+| `health_check` | Verify Sentor API is reachable |
+
+**Example prompt after setup:** *"Analyze these 50 customer reviews for sentiment toward our checkout flow and shipping speed, then cluster them by topic."*
+
+## Requirements
+
+- Python 3.10+
+- A Sentor API key → [Get one free at dashboard.sentor.app](https://dashboard.sentor.app/settings?tab=api-access)
+
+## Installation
+
+```bash
+pip install sentor-mcp
+```
+
+## Claude Desktop Setup
+
+Add to your `claude_desktop_config.json`:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "sentor": {
+      "command": "sentor-mcp",
+      "env": {
+        "SENTOR_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the Sentor tools available in the tool selector.
+
+## Cursor / Windsurf Setup
+
+Add to your MCP config file (`.cursor/mcp.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "sentor": {
+      "command": "sentor-mcp",
+      "env": {
+        "SENTOR_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once connected, use natural language:
+
+**Sentiment analysis:**
+> "Use Sentor to analyze the sentiment of these reviews toward Apple and iPhone: [paste reviews]"
+
+**Clustering:**
+> "I have 200 customer support tickets. Use Sentor to cluster them by topic and name each cluster."
+
+**Full pipeline:**
+> "Analyze sentiment in these 100 reviews for 'delivery' and 'packaging' entities, then cluster them and name each cluster."
+
+## Tool Reference
+
+### `analyze_sentiment(docs, language="en")`
+
+```python
+docs = [
+    {
+        "doc_id": "review_1",
+        "doc": "The delivery was fast but the packaging was terrible.",
+        "entities": ["delivery", "packaging"]
+    }
+]
+# Returns: predicted_label, probabilities, per-sentence details
+```
+
+### `cluster_documents(documents, language="en")`
+
+```python
+documents = [
+    {"doc_id": "r1", "text": "Great product quality", "entities": ["product"]},
+    # ... at least 5 documents required
+]
+# Returns: clusters with cluster_id, documents, top_words
+```
+
+### `name_topic(cluster_id, documents, top_words, entities, language="en")`
+
+```python
+# Pass the cluster data from cluster_documents response:
+name_topic(
+    cluster_id=0,
+    documents=cluster["documents"],
+    top_words=cluster["top_words"],
+    entities=["BrandName"]  # exclude your brand from the topic label
+)
+# Returns: topic_name (e.g. "Shipping Delay Complaints")
+```
+
+### `health_check()`
+
+```python
+# Returns: { "status": "healthy", "version": "...", "llm_status": "available" }
+```
+
+## Rate Limits
+
+| Plan | Per Minute | Per Month |
+|------|-----------|-----------|
+| Free | 3 | 300 |
+| Starter | 60 | 3,000 |
+| Growth | 200 | 15,000 |
+| Business | 500 | 60,000 |
+| Enterprise | 10,000 | Unlimited |
+
+## Remote Deployment (HTTP/SSE)
+
+To run as a hosted server:
+
+```bash
+docker build -t sentor-mcp .
+docker run -e SENTOR_API_KEY=your_key -p 8080:8080 sentor-mcp
+```
+
+The server exposes SSE at `http://localhost:8080/sse` and can be connected to AI tools that support remote MCP servers.
+
+## Links
+
+- [Sentor Dashboard](https://dashboard.sentor.app)
+- [API Documentation](https://sentor.app/docs)
+- [MCP Integration Guide](https://sentor.app/docs/integrations/mcp)
+- [Support](mailto:sentor@nikx.one)

sentor_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sentor-mcp"
+version = "1.0.0"
+description = "Sentor AI MCP Server — entity-based sentiment analysis tools for Claude, Cursor, and any MCP-compatible AI assistant"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "NIKX Technologies B.V.", email = "sentor@nikx.one" }]
+keywords = ["mcp", "sentiment-analysis", "nlp", "ai", "claude", "sentor"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://sentor.app"
+Documentation = "https://sentor.app/docs/integrations/mcp"
+Repository = "https://github.com/NIKX-Tech/sentor-mcp"
+"Get API Key" = "https://dashboard.sentor.app/settings?tab=api-access"
+
+[project.scripts]
+sentor-mcp = "sentor_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sentor_mcp"]

sentor_mcp-1.0.0/sentor_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Sentor MCP Server — entity-based sentiment analysis for AI assistants."""
+
+__version__ = "1.0.0"

sentor_mcp-1.0.0/sentor_mcp/server.py

@@ -0,0 +1,173 @@
+"""Sentor MCP Server — exposes sentiment analysis, clustering, and topic naming as MCP tools."""
+
+import os
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+SENTOR_BASE_URL = os.getenv("SENTOR_BASE_URL", "https://sentor.app/api")
+SENTOR_API_KEY = os.getenv("SENTOR_API_KEY", "")
+
+mcp = FastMCP(
+    "Sentor AI",
+    instructions=(
+        "You have access to Sentor's entity-based sentiment analysis API. "
+        "Use analyze_sentiment to score sentiment toward specific entities in text. "
+        "Use cluster_documents to group documents by topic (min 5 docs). "
+        "Use name_topic after clustering to label each cluster with a descriptive name. "
+        "Use health_check to verify the service is available. "
+        "All tools require a valid SENTOR_API_KEY set in the environment."
+    ),
+)
+
+
+def _headers() -> dict:
+    if not SENTOR_API_KEY:
+        raise ValueError(
+            "SENTOR_API_KEY environment variable is not set. "
+            "Get your key at https://dashboard.sentor.app/settings?tab=api-access"
+        )
+    return {"x-api-key": SENTOR_API_KEY, "Content-Type": "application/json"}
+
+
+@mcp.tool()
+def analyze_sentiment(
+    docs: list[dict],
+    language: str = "en",
+) -> dict:
+    """Analyze entity-based sentiment in one or more documents.
+
+    Each item in docs must be:
+      { "doc_id": "unique-id", "doc": "text to analyze", "entities": ["entity1", "entity2"] }
+
+    Entities are the specific subjects you want sentiment scored for (e.g. a brand, product,
+    feature, or person). The model returns per-document sentiment (negative/neutral/positive)
+    plus per-sentence breakdowns.
+
+    Args:
+        docs: List of document objects with doc_id, doc, and entities fields.
+        language: Language code — "en" (English) or "nl" (Dutch). Defaults to "en".
+
+    Returns:
+        Dict with "results" list. Each result has doc_id, predicted_label, probabilities,
+        and sentence-level details.
+    """
+    with httpx.Client(timeout=30) as client:
+        response = client.post(
+            f"{SENTOR_BASE_URL}/predicts",
+            params={"language": language},
+            json={"docs": docs},
+            headers=_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+@mcp.tool()
+def cluster_documents(
+    documents: list[dict],
+    language: str = "en",
+) -> dict:
+    """Group documents into thematic clusters using BERTopic + HDBSCAN.
+
+    Requires at least 5 documents. The algorithm automatically discovers the natural
+    number of clusters — you do not need to specify how many. Cluster -1 contains outliers
+    that did not fit any topic.
+
+    Each item in documents must be:
+      { "doc_id": "unique-id", "text": "document text", "entities": ["optional", "entities"] }
+
+    After clustering, pass each cluster's top_words and documents to name_topic to get
+    a human-readable label.
+
+    Args:
+        documents: List of document objects with doc_id, text, and optional entities fields.
+        language: Language code — "en" or "nl". Defaults to "en".
+
+    Returns:
+        Dict with "clusters" list (each with cluster_id, document_count, documents, top_words),
+        total_documents, total_clusters, and outliers_count.
+    """
+    if len(documents) < 5:
+        return {
+            "error": f"Clustering requires at least 5 documents, got {len(documents)}.",
+            "hint": "Add more documents or use analyze_sentiment for smaller sets.",
+        }
+
+    with httpx.Client(timeout=120) as client:
+        response = client.post(
+            f"{SENTOR_BASE_URL}/predicts/cluster",
+            params={"language": language},
+            json={"documents": documents},
+            headers=_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+@mcp.tool()
+def name_topic(
+    cluster_id: int,
+    documents: list[dict],
+    top_words: list[str] | None = None,
+    entities: list[str] | None = None,
+    language: str = "en",
+) -> dict:
+    """Generate a short descriptive name for a document cluster using an LLM.
+
+    Call this after cluster_documents. Pass the cluster's documents and top_words
+    from the clustering response for best results. The model produces a 3-5 word
+    label (e.g. "Shipping Delay Complaints", "Product Quality Praise").
+
+    Args:
+        cluster_id: The cluster ID from the clustering response (e.g. 0, 1, 2).
+        documents: The documents list from that cluster's clustering response entry.
+        top_words: The top_words list from that cluster's clustering response entry (recommended).
+        entities: Entity names to exclude from the topic label (e.g. your brand name).
+        language: Language code — "en" or "nl". Defaults to "en".
+
+    Returns:
+        Dict with cluster_id, topic_name (the generated label), document_count,
+        and generation_method ("LLM" or "Fallback").
+    """
+    with httpx.Client(timeout=30) as client:
+        response = client.post(
+            f"{SENTOR_BASE_URL}/predicts/topic-name",
+            json={
+                "cluster_id": cluster_id,
+                "documents": documents,
+                "top_words": top_words or [],
+                "entities": entities or [],
+                "language": language,
+            },
+            headers=_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+@mcp.tool()
+def health_check() -> dict:
+    """Check Sentor API availability and model status.
+
+    Returns the API status, version, and whether the LLM provider (used for
+    topic naming and report generation) is reachable.
+
+    Returns:
+        Dict with status ("healthy" or "degraded"), version, llm_provider, and llm_status.
+    """
+    with httpx.Client(timeout=10) as client:
+        response = client.get(
+            f"{SENTOR_BASE_URL}/predicts/health",
+            headers=_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def main() -> None:
+    """Entry point for stdio transport (Claude Desktop, Cursor, Windsurf)."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

sentor_mcp-1.0.0/sentor_mcp/server_http.py

@@ -0,0 +1,8 @@
+"""HTTP/SSE transport for Sentor MCP — for remote deployment (Claude.ai web, hosted environments)."""
+
+import os
+from sentor_mcp.server import mcp
+
+if __name__ == "__main__":
+    port = int(os.getenv("PORT", "8080"))
+    mcp.run(transport="sse", host="0.0.0.0", port=port)