igenius-mcp 0.1.0__tar.gz

igenius_mcp-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+Thumbs.db
+.venv/
+venv/

igenius_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 iGenius Memory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

igenius_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: igenius-mcp
+Version: 0.1.0
+Summary: MCP server for iGenius Memory — gives AI agents persistent memory tools via the hosted API
+Project-URL: Homepage, https://igenius-memory.com
+Project-URL: Documentation, https://igenius-memory.info
+Project-URL: Repository, https://github.com/vehoelite/igenius-mcp
+Project-URL: Store, https://igenius-memory.store
+Author-email: iGenius <hello@igenius-memory.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,copilot,igenius,mcp,memory
+Classifier: Development Status :: 4 - Beta
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# iGenius MCP — Thin Memory Server for VS Code
+
+A lightweight MCP (Model Context Protocol) server that gives AI agents
+persistent memory via the [iGenius Memory](https://igenius-memory.com) service.
+
+No database, no LLM, no local backend required — just an API key.
+
+## Quick Start
+
+```bash
+pip install igenius-mcp
+```
+
+Set your API key and run:
+
+```bash
+export IGENIUS_API_KEY=ig_your_key_here
+igenius-mcp
+```
+
+> **Get a free key** at [igenius-memory.online](https://igenius-memory.online#apikey)
+
+## VS Code Setup
+
+Add to `~/.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "igenius-memory": {
+      "command": "igenius-mcp",
+      "env": { "IGENIUS_API_KEY": "ig_your_key_here" },
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Restart VS Code — all 14 memory tools are now available to Copilot and any
+MCP-compatible agent.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_briefing` | Session briefing from all memory layers (call FIRST) |
+| `memory_ingest` | Ingest user/agent messages for AI extraction |
+| `memory_consolidate` | Merge accumulated extracts into master briefing |
+| `memory_process` | Detect trigger words and auto-classify text |
+| `memory_store` | Direct store to a specific memory layer |
+| `memory_search` | Natural language search across memories |
+| `memory_recall` | Retrieve all persistent session memories |
+| `memory_summarize` | LLM-powered summary of a memory layer |
+| `memory_delete` | Delete a memory by ID |
+| `memory_update` | Update fields on an existing memory |
+| `memory_review` | List short-term memories for triage |
+| `memory_promote` | Promote short-term → long-term |
+| `memory_triggers_list` | List trigger words and their layers |
+| `memory_triggers_add` | Add a new trigger word |
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `IGENIUS_API_KEY` | Yes | — |
+| `IGENIUS_API_URL` | No | `https://igenius-memory.online/v1` |
+
+## Agent Instructions
+
+For best results, add the iGenius agent instructions to your workspace:
+
+- **VS Code**: Place `igenius.instructions.md` in `~/.vscode/prompts/`
+- **Claude Code**: Add to `CLAUDE.md`
+- **Workspace**: Add to `.github/copilot-instructions.md`
+
+Get the template at [igenius-memory.info](https://igenius-memory.info)
+
+## How It Works
+
+```
+Agent ←→ MCP (stdio) ←→ igenius-mcp ←→ REST API ←→ iGenius Backend
+```
+
+This package is a **thin proxy** — it translates MCP tool calls into REST API
+requests. All processing (AI extraction, LLM summarization, encryption) happens
+server-side. Your data never touches the local machine.
+
+## Plans
+
+| Plan | Price | Includes |
+|------|-------|----------|
+| Starter | Free | 50 memories, all 14 tools |
+| Pro | $19/mo | Unlimited memories, priority, encryption |
+| Enterprise | Contact | Custom deployment, SLA |
+
+Details at [igenius-memory.store](https://igenius-memory.store)
+
+## Links
+
+- [Landing Page](https://igenius-memory.com)
+- [Documentation](https://igenius-memory.info)
+- [API Portal](https://igenius-memory.online)
+- [Store & Plans](https://igenius-memory.store)
+
+## License
+
+MIT

igenius_mcp-0.1.0/README.md

@@ -0,0 +1,107 @@
+# iGenius MCP — Thin Memory Server for VS Code
+
+A lightweight MCP (Model Context Protocol) server that gives AI agents
+persistent memory via the [iGenius Memory](https://igenius-memory.com) service.
+
+No database, no LLM, no local backend required — just an API key.
+
+## Quick Start
+
+```bash
+pip install igenius-mcp
+```
+
+Set your API key and run:
+
+```bash
+export IGENIUS_API_KEY=ig_your_key_here
+igenius-mcp
+```
+
+> **Get a free key** at [igenius-memory.online](https://igenius-memory.online#apikey)
+
+## VS Code Setup
+
+Add to `~/.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "igenius-memory": {
+      "command": "igenius-mcp",
+      "env": { "IGENIUS_API_KEY": "ig_your_key_here" },
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Restart VS Code — all 14 memory tools are now available to Copilot and any
+MCP-compatible agent.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_briefing` | Session briefing from all memory layers (call FIRST) |
+| `memory_ingest` | Ingest user/agent messages for AI extraction |
+| `memory_consolidate` | Merge accumulated extracts into master briefing |
+| `memory_process` | Detect trigger words and auto-classify text |
+| `memory_store` | Direct store to a specific memory layer |
+| `memory_search` | Natural language search across memories |
+| `memory_recall` | Retrieve all persistent session memories |
+| `memory_summarize` | LLM-powered summary of a memory layer |
+| `memory_delete` | Delete a memory by ID |
+| `memory_update` | Update fields on an existing memory |
+| `memory_review` | List short-term memories for triage |
+| `memory_promote` | Promote short-term → long-term |
+| `memory_triggers_list` | List trigger words and their layers |
+| `memory_triggers_add` | Add a new trigger word |
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `IGENIUS_API_KEY` | Yes | — |
+| `IGENIUS_API_URL` | No | `https://igenius-memory.online/v1` |
+
+## Agent Instructions
+
+For best results, add the iGenius agent instructions to your workspace:
+
+- **VS Code**: Place `igenius.instructions.md` in `~/.vscode/prompts/`
+- **Claude Code**: Add to `CLAUDE.md`
+- **Workspace**: Add to `.github/copilot-instructions.md`
+
+Get the template at [igenius-memory.info](https://igenius-memory.info)
+
+## How It Works
+
+```
+Agent ←→ MCP (stdio) ←→ igenius-mcp ←→ REST API ←→ iGenius Backend
+```
+
+This package is a **thin proxy** — it translates MCP tool calls into REST API
+requests. All processing (AI extraction, LLM summarization, encryption) happens
+server-side. Your data never touches the local machine.
+
+## Plans
+
+| Plan | Price | Includes |
+|------|-------|----------|
+| Starter | Free | 50 memories, all 14 tools |
+| Pro | $19/mo | Unlimited memories, priority, encryption |
+| Enterprise | Contact | Custom deployment, SLA |
+
+Details at [igenius-memory.store](https://igenius-memory.store)
+
+## Links
+
+- [Landing Page](https://igenius-memory.com)
+- [Documentation](https://igenius-memory.info)
+- [API Portal](https://igenius-memory.online)
+- [Store & Plans](https://igenius-memory.store)
+
+## License
+
+MIT

igenius_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "igenius-mcp"
+version = "0.1.0"
+description = "MCP server for iGenius Memory — gives AI agents persistent memory tools via the hosted API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "iGenius", email = "hello@igenius-memory.com" }]
+keywords = ["mcp", "ai", "memory", "agent", "copilot", "claude", "igenius"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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 :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://igenius-memory.com"
+Documentation = "https://igenius-memory.info"
+Repository = "https://github.com/vehoelite/igenius-mcp"
+Store = "https://igenius-memory.store"
+
+[project.scripts]
+igenius-mcp = "igenius_mcp.server:main"

igenius_mcp-0.1.0/src/igenius_mcp/__init__.py

@@ -0,0 +1,10 @@
+# iGenius MCP — Thin API Client for MCP Tools
+
+"""
+igenius-mcp: A lightweight MCP server that exposes iGenius Memory tools
+by proxying all requests through the hosted REST API.
+
+No database, no LLM, no server logic — just a clean MCP ↔ REST bridge.
+"""
+
+__version__ = "0.1.0"

igenius_mcp-0.1.0/src/igenius_mcp/server.py

@@ -0,0 +1,397 @@
+"""
+iGenius MCP Server — Thin REST-API proxy.
+
+Exposes all 14 iGenius Memory tools as MCP tools by forwarding requests to the
+hosted API at igenius-memory.online. Requires only an API key — no database,
+no LLM, no local backend.
+
+Usage:
+    pip install igenius-mcp
+    IGENIUS_API_KEY=ig_xxx igenius-mcp
+
+Or configure in VS Code mcp.json:
+    {
+      "servers": {
+        "igenius-memory": {
+          "command": "igenius-mcp",
+          "env": { "IGENIUS_API_KEY": "ig_xxx" },
+          "type": "stdio"
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+# ─── Configuration ──────────────────────────────────────────────────────────────
+
+API_BASE = os.environ.get("IGENIUS_API_URL", "https://igenius-memory.online/v1")
+API_KEY = os.environ.get("IGENIUS_API_KEY", "")
+
+if not API_KEY:
+    print(
+        "ERROR: IGENIUS_API_KEY environment variable is required.\n"
+        "Get a free key at https://igenius-memory.online#apikey",
+        file=sys.stderr,
+    )
+
+# ─── HTTP Client ────────────────────────────────────────────────────────────────
+
+_client: httpx.AsyncClient | None = None
+
+
+def _get_client() -> httpx.AsyncClient:
+    global _client
+    if _client is None or _client.is_closed:
+        _client = httpx.AsyncClient(
+            base_url=API_BASE,
+            headers={
+                "X-API-Key": API_KEY,
+                "Content-Type": "application/json",
+                "User-Agent": "iGenius-MCP/0.1.0",
+            },
+            timeout=120.0,
+        )
+    return _client
+
+
+async def _api(method: str, path: str, body: dict | None = None) -> dict:
+    """Make an API request and return JSON response."""
+    client = _get_client()
+    if method == "GET":
+        resp = await client.get(path)
+    else:
+        resp = await client.post(path, json=body or {})
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─── MCP Server ─────────────────────────────────────────────────────────────────
+
+server = Server("igenius-memory")
+
+# ─── Tool Definitions ───────────────────────────────────────────────────────────
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="memory_briefing",
+        description=(
+            "Generate a smart, LLM-synthesised session briefing from ALL memory layers. "
+            "Call this FIRST in every new conversation — it replaces the need to "
+            "call memory_recall + memory_summarize separately. "
+            "Results are cached and only regenerated when underlying memories change."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "force": {
+                    "type": "boolean",
+                    "description": "Force regeneration even if memories haven't changed (default: false).",
+                },
+            },
+        },
+    ),
+    Tool(
+        name="memory_ingest",
+        description=(
+            "Ingest a single interaction message for AI-powered extraction. "
+            "This is the CORE tool — call it for EVERY user prompt, agent response, "
+            "tool result, or system message. The AI reads the message, extracts "
+            "facts, decisions, credentials, file paths, preferences, and context, "
+            "then stores a smart summary as persistent memory."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "The raw interaction message to process.",
+                },
+                "role": {
+                    "type": "string",
+                    "enum": ["user", "agent", "tool", "system"],
+                    "description": "Who sent this message (default: user).",
+                },
+            },
+            "required": ["message"],
+        },
+    ),
+    Tool(
+        name="memory_consolidate",
+        description=(
+            "Consolidate all accumulated interaction summaries into a master briefing. "
+            "Call this before context resets or when context is getting full."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "force": {
+                    "type": "boolean",
+                    "description": "Force regeneration even if nothing new (default: false).",
+                },
+            },
+        },
+    ),
+    Tool(
+        name="memory_process",
+        description=(
+            "Process raw text through the trigger pipeline. "
+            "Detects trigger words, classifies via LLM, and auto-stores to the "
+            "appropriate memory layer."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "text": {
+                    "type": "string",
+                    "description": "The raw text to process.",
+                },
+            },
+            "required": ["text"],
+        },
+    ),
+    Tool(
+        name="memory_store",
+        description=(
+            "Directly store a memory into a specific layer, bypassing LLM classification."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "layer": {
+                    "type": "string",
+                    "enum": ["persistent", "long_term", "short_term"],
+                },
+                "title": {"type": "string", "description": "Short title (max 512 chars)."},
+                "content": {"type": "string", "description": "Full memory content."},
+                "category": {"type": "string"},
+                "importance": {"type": "integer", "minimum": 0, "maximum": 100},
+            },
+            "required": ["layer", "title", "content"],
+        },
+    ),
+    Tool(
+        name="memory_search",
+        description=(
+            "Search memories by natural language query across short_term and long_term layers."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query."},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 100},
+            },
+            "required": ["query"],
+        },
+    ),
+    Tool(
+        name="memory_recall",
+        description=(
+            "Retrieve all active persistent memories (interaction extracts from current session)."
+        ),
+        inputSchema={"type": "object", "properties": {}},
+    ),
+    Tool(
+        name="memory_summarize",
+        description=(
+            "Summarize memories in a layer using the LLM."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "layer": {
+                    "type": "string",
+                    "enum": ["persistent", "long_term", "short_term"],
+                },
+                "limit": {"type": "integer", "minimum": 1, "maximum": 200},
+            },
+        },
+    ),
+    Tool(
+        name="memory_delete",
+        description="Delete a memory by its ID.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "memory_id": {"type": "integer", "description": "The memory ID to delete."},
+            },
+            "required": ["memory_id"],
+        },
+    ),
+    Tool(
+        name="memory_update",
+        description="Update fields on an existing memory.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "memory_id": {"type": "integer"},
+                "title": {"type": "string"},
+                "content": {"type": "string"},
+                "category": {"type": "string"},
+                "importance": {"type": "integer", "minimum": 0, "maximum": 100},
+                "layer": {"type": "string", "enum": ["persistent", "long_term", "short_term"]},
+            },
+            "required": ["memory_id"],
+        },
+    ),
+    Tool(
+        name="memory_review",
+        description=(
+            "List short-term memories for user triage. Promote keepers or discard."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "limit": {"type": "integer", "minimum": 1, "maximum": 200},
+            },
+        },
+    ),
+    Tool(
+        name="memory_promote",
+        description="Promote a short-term memory to long-term storage.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "memory_id": {"type": "integer"},
+            },
+            "required": ["memory_id"],
+        },
+    ),
+    Tool(
+        name="memory_triggers_list",
+        description="List all configured trigger words and their target layers.",
+        inputSchema={"type": "object", "properties": {}},
+    ),
+    Tool(
+        name="memory_triggers_add",
+        description="Add a new trigger word that maps to a memory layer.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "word": {"type": "string"},
+                "target_layer": {"type": "string", "enum": ["persistent", "long_term", "short_term"]},
+                "description": {"type": "string"},
+            },
+            "required": ["word", "target_layer"],
+        },
+    ),
+]
+
+
+# ─── Tool Dispatch ──────────────────────────────────────────────────────────────
+
+ROUTE_MAP: dict[str, tuple[str, str]] = {
+    # name → (HTTP method, path template)
+    "memory_briefing":       ("GET",  "/briefing"),
+    "memory_ingest":         ("POST", "/ingest"),
+    "memory_consolidate":    ("POST", "/consolidate"),
+    "memory_process":        ("POST", "/process"),
+    "memory_store":          ("POST", "/memories"),
+    "memory_search":         ("GET",  "/memories/search"),
+    "memory_recall":         ("GET",  "/memories/layer/persistent"),
+    "memory_summarize":      ("POST", "/memories/summarize"),
+    "memory_delete":         ("DELETE", "/memories/{memory_id}"),
+    "memory_update":         ("PATCH",  "/memories/{memory_id}"),
+    "memory_review":         ("GET",  "/memories/review"),
+    "memory_promote":        ("POST", "/memories/{memory_id}/promote"),
+    "memory_triggers_list":  ("GET",  "/triggers"),
+    "memory_triggers_add":   ("POST", "/triggers"),
+}
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return TOOLS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    try:
+        result = await _dispatch(name, arguments)
+        return [TextContent(type="text", text=json.dumps(result, indent=2, default=str))]
+    except httpx.HTTPStatusError as e:
+        detail = e.response.text
+        try:
+            detail = e.response.json().get("detail", detail)
+        except Exception:
+            pass
+        return [TextContent(type="text", text=json.dumps({"error": str(detail), "status": e.response.status_code}))]
+    except Exception as e:
+        return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
+
+
+async def _dispatch(name: str, args: dict[str, Any]) -> Any:
+    """Route tool calls to REST API endpoints."""
+    route = ROUTE_MAP.get(name)
+    if not route:
+        return {"error": f"Unknown tool: {name}"}
+
+    method, path_template = route
+    client = _get_client()
+
+    # Substitute path params like {memory_id}
+    path = path_template
+    path_args = {}
+    for key in list(args.keys()):
+        placeholder = f"{{{key}}}"
+        if placeholder in path_template:
+            path = path.replace(placeholder, str(args[key]))
+            path_args[key] = args.pop(key)
+
+    # Build request
+    if method == "GET":
+        # Convert remaining args to query params
+        params = {}
+        if name == "memory_briefing" and args.get("force"):
+            params["force"] = "true"
+        elif name == "memory_search":
+            params["q"] = args.get("query", "")
+            if args.get("limit"):
+                params["limit"] = str(args["limit"])
+        elif name == "memory_review":
+            if args.get("limit"):
+                params["limit"] = str(args["limit"])
+        resp = await client.get(path, params=params)
+    elif method == "DELETE":
+        resp = await client.delete(path)
+    elif method == "PATCH":
+        resp = await client.patch(path, json=args)
+    else:
+        resp = await client.post(path, json=args)
+
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ─── Entry point ────────────────────────────────────────────────────────────────
+
+async def _run():
+    if not API_KEY:
+        print(
+            "FATAL: Set IGENIUS_API_KEY environment variable.\n"
+            "Get a free key at https://igenius-memory.online#apikey",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main():
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()