adminica-mcp 1.0.0__tar.gz

adminica_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: adminica-mcp
+Version: 1.0.0
+Summary: MCP server for Adminica — library search and RAG chat in Cursor, Claude Desktop, VS Code
+Author-email: Adminica Team <info@tx0.ru>
+License-Expression: MIT
+Project-URL: Homepage, https://adminica.ru
+Project-URL: Documentation, https://adminica.ru/api/docs/#mcp
+Project-URL: Repository, https://gitlab.main.tx0.ru/lebedev/adminica-assistant
+Project-URL: Bug Tracker, https://gitlab.main.tx0.ru/lebedev/adminica-assistant/-/issues
+Keywords: mcp,adminica,rag,cursor,claude,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: httpx>=0.25.2
+
+# adminica-mcp
+
+[MCP](https://modelcontextprotocol.io) server for [Adminica](https://adminica.ru) — search the knowledge archive and ask RAG-grounded questions from Cursor, Claude Desktop, VS Code, and other MCP clients.
+
+## Install
+
+```bash
+pip install adminica-mcp
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_library` | Vector search in the Adminica archive |
+| `ask_adminica` | Full RAG answer (`POST /api/v1/query`, requires API key) |
+| `get_library_entry` | Library entry card by UUID |
+| `adminica_health` | Check Adminica `/health` |
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `ADMINICA_API_KEY` | for `ask_adminica` | — |
+| `ADMINICA_API_URL` | no | `https://adminica.ru/api/v1` |
+
+Create an API key at [adminica.ru/profile](https://adminica.ru/profile/) → Security.
+
+## MCP client config
+
+```json
+{
+  "mcpServers": {
+    "adminica": {
+      "command": "adminica-mcp",
+      "env": {
+        "ADMINICA_API_KEY": "ak_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Full guide: [adminica.ru/api/docs/#mcp](https://adminica.ru/api/docs/#mcp)
+
+## License
+
+MIT

adminica_mcp-1.0.0/README.md

@@ -0,0 +1,48 @@
+# adminica-mcp
+
+[MCP](https://modelcontextprotocol.io) server for [Adminica](https://adminica.ru) — search the knowledge archive and ask RAG-grounded questions from Cursor, Claude Desktop, VS Code, and other MCP clients.
+
+## Install
+
+```bash
+pip install adminica-mcp
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_library` | Vector search in the Adminica archive |
+| `ask_adminica` | Full RAG answer (`POST /api/v1/query`, requires API key) |
+| `get_library_entry` | Library entry card by UUID |
+| `adminica_health` | Check Adminica `/health` |
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `ADMINICA_API_KEY` | for `ask_adminica` | — |
+| `ADMINICA_API_URL` | no | `https://adminica.ru/api/v1` |
+
+Create an API key at [adminica.ru/profile](https://adminica.ru/profile/) → Security.
+
+## MCP client config
+
+```json
+{
+  "mcpServers": {
+    "adminica": {
+      "command": "adminica-mcp",
+      "env": {
+        "ADMINICA_API_KEY": "ak_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Full guide: [adminica.ru/api/docs/#mcp](https://adminica.ru/api/docs/#mcp)
+
+## License
+
+MIT

adminica_mcp-1.0.0/adminica_mcp.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: adminica-mcp
+Version: 1.0.0
+Summary: MCP server for Adminica — library search and RAG chat in Cursor, Claude Desktop, VS Code
+Author-email: Adminica Team <info@tx0.ru>
+License-Expression: MIT
+Project-URL: Homepage, https://adminica.ru
+Project-URL: Documentation, https://adminica.ru/api/docs/#mcp
+Project-URL: Repository, https://gitlab.main.tx0.ru/lebedev/adminica-assistant
+Project-URL: Bug Tracker, https://gitlab.main.tx0.ru/lebedev/adminica-assistant/-/issues
+Keywords: mcp,adminica,rag,cursor,claude,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: httpx>=0.25.2
+
+# adminica-mcp
+
+[MCP](https://modelcontextprotocol.io) server for [Adminica](https://adminica.ru) — search the knowledge archive and ask RAG-grounded questions from Cursor, Claude Desktop, VS Code, and other MCP clients.
+
+## Install
+
+```bash
+pip install adminica-mcp
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_library` | Vector search in the Adminica archive |
+| `ask_adminica` | Full RAG answer (`POST /api/v1/query`, requires API key) |
+| `get_library_entry` | Library entry card by UUID |
+| `adminica_health` | Check Adminica `/health` |
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `ADMINICA_API_KEY` | for `ask_adminica` | — |
+| `ADMINICA_API_URL` | no | `https://adminica.ru/api/v1` |
+
+Create an API key at [adminica.ru/profile](https://adminica.ru/profile/) → Security.
+
+## MCP client config
+
+```json
+{
+  "mcpServers": {
+    "adminica": {
+      "command": "adminica-mcp",
+      "env": {
+        "ADMINICA_API_KEY": "ak_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Full guide: [adminica.ru/api/docs/#mcp](https://adminica.ru/api/docs/#mcp)
+
+## License
+
+MIT

adminica_mcp-1.0.0/adminica_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+adminica_mcp.egg-info/PKG-INFO
+adminica_mcp.egg-info/SOURCES.txt
+adminica_mcp.egg-info/dependency_links.txt
+adminica_mcp.egg-info/entry_points.txt
+adminica_mcp.egg-info/requires.txt
+adminica_mcp.egg-info/top_level.txt
+mcp_server/__init__.py
+mcp_server/__main__.py
+mcp_server/client.py
+mcp_server/server.py

adminica_mcp-1.0.0/adminica_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

adminica_mcp-1.0.0/adminica_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+adminica-mcp = mcp_server.server:main

adminica_mcp-1.0.0/adminica_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.6.0
+httpx>=0.25.2

adminica_mcp-1.0.0/adminica_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server

adminica_mcp-1.0.0/mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""MCP-сервер Adminica — поиск по архиву и RAG-чат из Cursor/IDE."""
+
+__version__ = "1.0.0"

adminica_mcp-1.0.0/mcp_server/__main__.py

@@ -0,0 +1,4 @@
+from mcp_server.server import main
+
+if __name__ == "__main__":
+    main()

adminica_mcp-1.0.0/mcp_server/client.py

@@ -0,0 +1,202 @@
+"""HTTP-клиент к REST API Adminica для MCP tools."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+DEFAULT_BASE_URL = "https://adminica.ru/api/v1"
+DEFAULT_TIMEOUT = 120.0
+
+
+def resolve_base_url() -> str:
+    return (os.environ.get("ADMINICA_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def resolve_api_key() -> Optional[str]:
+    key = (os.environ.get("ADMINICA_API_KEY") or "").strip()
+    return key or None
+
+
+def require_api_key() -> str:
+    key = resolve_api_key()
+    if not key:
+        raise ValueError(
+            "ADMINICA_API_KEY is not set. Create a key at https://adminica.ru/profile/ → Security."
+        )
+    return key
+
+
+def _headers(*, with_key: bool = False) -> Dict[str, str]:
+    headers = {"Accept": "application/json", "Content-Type": "application/json"}
+    if with_key:
+        headers["X-API-Key"] = require_api_key()
+    elif resolve_api_key():
+        headers["X-API-Key"] = resolve_api_key()  # type: ignore[assignment]
+    return headers
+
+
+def format_search_results(data: Dict[str, Any]) -> str:
+    entries = data.get("entries") or []
+    total = data.get("total_found", len(entries))
+    query = data.get("query", "")
+    if not entries:
+        return f"No library entries found for «{query}»."
+
+    lines = [f"Found {total} entries for «{query}» (showing {len(entries)}):\n"]
+    for idx, entry in enumerate(entries, start=1):
+        title = entry.get("title") or "Untitled"
+        section = entry.get("section") or "—"
+        entry_id = entry.get("id") or "?"
+        entry_type = entry.get("entry_type") or entry.get("type") or "—"
+        summary = (entry.get("summary") or "").strip()
+        score = entry.get("score") or entry.get("relevance_score")
+        score_part = f" · score {score:.2f}" if isinstance(score, (int, float)) else ""
+        lines.append(f"{idx}. **{title}** ({section}, {entry_type}){score_part}")
+        lines.append(f"   id: `{entry_id}`")
+        if summary:
+            snippet = summary[:280] + ("…" if len(summary) > 280 else "")
+            lines.append(f"   {snippet}")
+        lines.append("")
+    return "\n".join(lines).strip()
+
+
+def format_query_response(data: Dict[str, Any]) -> str:
+    answer = (data.get("answer") or "").strip()
+    confidence = data.get("confidence")
+    entries = data.get("entries") or data.get("sources") or []
+    lines = []
+    if answer:
+        lines.append(answer)
+    meta = []
+    if confidence is not None:
+        meta.append(f"confidence: {confidence}%")
+    if data.get("processing_time_ms") is not None:
+        meta.append(f"{data['processing_time_ms']:.0f} ms")
+    if data.get("intent"):
+        meta.append(f"intent: {data['intent']}")
+    if meta:
+        lines.append("\n---\n_" + " · ".join(meta) + "_")
+
+    if entries:
+        lines.append("\n**Sources:**")
+        for entry in entries[:8]:
+            title = entry.get("title") or entry.get("name") or "Source"
+            section = entry.get("section") or ""
+            entry_id = entry.get("id") or entry.get("entry_id") or ""
+            suffix = f" ({section})" if section else ""
+            id_part = f" `{entry_id}`" if entry_id else ""
+            lines.append(f"- {title}{suffix}{id_part}")
+    return "\n".join(lines).strip()
+
+
+def format_entry_detail(data: Dict[str, Any]) -> str:
+    title = data.get("title") or "Untitled"
+    section = data.get("section") or "—"
+    entry_type = data.get("entry_type") or "—"
+    entry_id = data.get("id") or "?"
+    summary = (data.get("summary") or "").strip()
+    content = (data.get("content") or "").strip()
+    lines = [
+        f"# {title}",
+        f"- **id:** `{entry_id}`",
+        f"- **section:** {section}",
+        f"- **type:** {entry_type}",
+    ]
+    if summary:
+        lines.extend(["", "## Summary", summary])
+    if content:
+        excerpt = content[:4000] + ("…\n\n_(truncated)_" if len(content) > 4000 else "")
+        lines.extend(["", "## Content", excerpt])
+    return "\n".join(lines).strip()
+
+
+class AdminicaClient:
+    """Thin REST client for MCP tools."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.base_url = (base_url or resolve_base_url()).rstrip("/")
+        self.api_key = api_key if api_key is not None else resolve_api_key()
+        self.timeout = timeout
+
+    def _headers(self, *, require_key: bool = False) -> Dict[str, str]:
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        key = self.api_key
+        if require_key and not key:
+            raise ValueError(
+                "ADMINICA_API_KEY is required. Create one at https://adminica.ru/profile/ → Security."
+            )
+        if key:
+            headers["X-API-Key"] = key
+        return headers
+
+    async def health(self) -> Dict[str, Any]:
+        root = self.base_url.replace("/api/v1", "") or "https://adminica.ru"
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.get(f"{root.rstrip('/')}/health")
+            response.raise_for_status()
+            return response.json()
+
+    async def search_library(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        section: Optional[str] = None,
+    ) -> str:
+        params: Dict[str, Any] = {"query": query, "limit": max(1, min(limit, 20))}
+        if section:
+            params["filters.section"] = section
+        url = f"{self.base_url}/knowledge/search?{urlencode(params)}"
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(url, headers=self._headers())
+            response.raise_for_status()
+            return format_search_results(response.json())
+
+    async def ask_adminica(
+        self,
+        query: str,
+        *,
+        session_id: Optional[str] = None,
+        chat_id: Optional[str] = None,
+    ) -> str:
+        payload: Dict[str, Any] = {
+            "query": query,
+            "session_id": session_id or "mcp-session",
+            "chat_id": chat_id or "mcp-cursor",
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}/query",
+                headers=self._headers(require_key=True),
+                json=payload,
+            )
+            if response.status_code >= 400:
+                detail = response.text[:500]
+                try:
+                    err_json = response.json()
+                    detail = err_json.get("detail") or err_json.get("error") or detail
+                except Exception:
+                    pass
+                raise ValueError(
+                    f"API error {response.status_code}: {detail}"
+                )
+            return format_query_response(response.json())
+
+    async def get_library_entry(self, entry_id: str) -> str:
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f"{self.base_url}/knowledge/{entry_id}",
+                headers=self._headers(),
+            )
+            response.raise_for_status()
+            return format_entry_detail(response.json())

adminica_mcp-1.0.0/mcp_server/server.py

@@ -0,0 +1,96 @@
+"""MCP-сервер Adminica (stdio) — tools для Cursor и других MCP-клиентов."""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_server.client import AdminicaClient, resolve_api_key, resolve_base_url
+
+mcp = FastMCP(
+    "adminica",
+    instructions=(
+        "Adminica library assistant: search the knowledge archive (RAG) and ask questions "
+        "grounded in books and articles. Use search_library for raw retrieval; "
+        "ask_adminica for a synthesized answer with sources. Requires ADMINICA_API_KEY for ask_adminica."
+    ),
+)
+
+_client: AdminicaClient | None = None
+
+
+def get_client() -> AdminicaClient:
+    global _client
+    if _client is None:
+        _client = AdminicaClient(base_url=resolve_base_url(), api_key=resolve_api_key())
+    return _client
+
+
+@mcp.tool(
+    name="search_library",
+    description=(
+        "Vector search in the Adminica knowledge library. Returns titles, sections, IDs and summaries. "
+        "No API key required (public endpoint); key is used if ADMINICA_API_KEY is set."
+    ),
+)
+async def search_library(query: str, limit: int = 5, section: str | None = None) -> str:
+    """Search books/articles/manuals in the Adminica archive."""
+    if not query or not query.strip():
+        return "Error: query must not be empty."
+    return await get_client().search_library(query.strip(), limit=limit, section=section)
+
+
+@mcp.tool(
+    name="ask_adminica",
+    description=(
+        "Ask Adminica a question; returns an LLM answer with RAG sources from the library. "
+        "Requires ADMINICA_API_KEY (create at adminica.ru/profile → Security). Uses tokens."
+    ),
+)
+async def ask_adminica(query: str, session_id: str | None = None) -> str:
+    """Full RAG Q&A via POST /api/v1/query."""
+    if not query or not query.strip():
+        return "Error: query must not be empty."
+    try:
+        return await get_client().ask_adminica(query.strip(), session_id=session_id)
+    except ValueError as e:
+        return f"Error: {e}"
+
+
+@mcp.tool(
+    name="get_library_entry",
+    description="Fetch a single library entry by UUID (title, summary, content excerpt).",
+)
+async def get_library_entry(entry_id: str) -> str:
+    """Get one knowledge entry by id."""
+    if not entry_id or not entry_id.strip():
+        return "Error: entry_id must not be empty."
+    try:
+        return await get_client().get_library_entry(entry_id.strip())
+    except Exception as e:
+        return f"Error fetching entry: {e}"
+
+
+@mcp.tool(
+    name="adminica_health",
+    description="Check Adminica API availability (/health).",
+)
+async def adminica_health() -> str:
+    """Ping Adminica deployment health endpoint."""
+    try:
+        data = await get_client().health()
+        status = data.get("status", "unknown")
+        services = data.get("services") or {}
+        parts = [f"status: **{status}**"]
+        for name, state in services.items():
+            parts.append(f"- {name}: {state}")
+        return "\n".join(parts)
+    except Exception as e:
+        return f"Health check failed: {e}"
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

adminica_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adminica-mcp"
+version = "1.0.0"
+description = "MCP server for Adminica — library search and RAG chat in Cursor, Claude Desktop, VS Code"
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "Adminica Team", email = "info@tx0.ru"},
+]
+requires-python = ">=3.11"
+keywords = ["mcp", "adminica", "rag", "cursor", "claude", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.6.0",
+    "httpx>=0.25.2",
+]
+
+[project.urls]
+Homepage = "https://adminica.ru"
+Documentation = "https://adminica.ru/api/docs/#mcp"
+Repository = "https://gitlab.main.tx0.ru/lebedev/adminica-assistant"
+"Bug Tracker" = "https://gitlab.main.tx0.ru/lebedev/adminica-assistant/-/issues"
+
+[project.scripts]
+adminica-mcp = "mcp_server.server:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]

adminica_mcp-1.0.0/setup.cfg

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