swarmv-mcp 1.2.0__tar.gz

swarmv_mcp-1.2.0/.gitignore

@@ -0,0 +1,26 @@
+node_modules/
+dist/
+.env
+.dev.vars
+.DS_Store
+.backup/
+# Secrets and local copies of them
+*.bak
+.env.*
+!.env.example
+# Build output and local state
+.wrangler/
+target/
+crates/edgevec-wasm/pkg/
+.next/
+.vercel/
+__pycache__/
+*.pyc
+# Load test reports
+load-test-*.json
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+# Separate repository (has its own .git)
+edgevec/

swarmv_mcp-1.2.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: swarmv-mcp
+Version: 1.2.0
+Summary: MCP server for SwarmV: persistent vector memory for AI agents, limited to what the user may access.
+Project-URL: Homepage, https://edgevec.pages.dev
+Project-URL: Documentation, https://edgevec.pages.dev/docs
+License-Expression: MIT
+Keywords: agents,ai,mcp,memory,swarmv,vector
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.1.2
+Requires-Dist: swarmv>=1.2.0
+Description-Content-Type: text/markdown
+
+# swarmv-mcp
+
+MCP server for [SwarmV](https://edgevec.pages.dev): gives an AI agent persistent vector memory, limited to what the signed-in user is allowed to see and edit.
+
+Tools:
+
+- `read_from_memory` returns the closest records (id, distance, metadata) from the containers the user can view.
+- `write_to_memory` stores a note in a container the user can edit (put the text in `metadata.text`).
+
+## Setup
+
+```bash
+pip install swarmv-mcp
+```
+
+Add it to your MCP client's configuration (Claude Desktop, Cursor and others):
+
+```json
+{
+  "mcpServers": {
+    "swarmv": {
+      "command": "swarmv-mcp",
+      "env": {
+        "SWARMV_TOKEN_URL": "https://your-backend.example.com/swarmv-token",
+        "SWARMV_TOKEN_URL_AUTH": "<the signed-in user's session credential>"
+      }
+    }
+  }
+}
+```
+
+Or without installing first: `"command": "uvx", "args": ["swarmv-mcp"]`.
+
+## Credentials
+
+Pick one:
+
+| Variables | Use |
+| --- | --- |
+| `SWARMV_TOKEN_URL` (+ optional `SWARMV_TOKEN_URL_AUTH`) | Recommended. Your backend returns `{ "token": "..." }`, a short-lived user token it minted with your API key. |
+| `SWARMV_USER_TOKEN` | A user token you already have (expires). |
+| `SWARMV_API_KEY` + `SWARMV_USER_ID=user:<id>` | Local development only. Never ship your API key to end users. |
+
+Optional: `SWARMV_DIM` (vector dimensions, default 768), `SWARMV_BASE_URL`.
+
+Full documentation: https://edgevec.pages.dev/docs
+
+## License
+
+MIT

swarmv_mcp-1.2.0/README.md

@@ -0,0 +1,50 @@
+# swarmv-mcp
+
+MCP server for [SwarmV](https://edgevec.pages.dev): gives an AI agent persistent vector memory, limited to what the signed-in user is allowed to see and edit.
+
+Tools:
+
+- `read_from_memory` returns the closest records (id, distance, metadata) from the containers the user can view.
+- `write_to_memory` stores a note in a container the user can edit (put the text in `metadata.text`).
+
+## Setup
+
+```bash
+pip install swarmv-mcp
+```
+
+Add it to your MCP client's configuration (Claude Desktop, Cursor and others):
+
+```json
+{
+  "mcpServers": {
+    "swarmv": {
+      "command": "swarmv-mcp",
+      "env": {
+        "SWARMV_TOKEN_URL": "https://your-backend.example.com/swarmv-token",
+        "SWARMV_TOKEN_URL_AUTH": "<the signed-in user's session credential>"
+      }
+    }
+  }
+}
+```
+
+Or without installing first: `"command": "uvx", "args": ["swarmv-mcp"]`.
+
+## Credentials
+
+Pick one:
+
+| Variables | Use |
+| --- | --- |
+| `SWARMV_TOKEN_URL` (+ optional `SWARMV_TOKEN_URL_AUTH`) | Recommended. Your backend returns `{ "token": "..." }`, a short-lived user token it minted with your API key. |
+| `SWARMV_USER_TOKEN` | A user token you already have (expires). |
+| `SWARMV_API_KEY` + `SWARMV_USER_ID=user:<id>` | Local development only. Never ship your API key to end users. |
+
+Optional: `SWARMV_DIM` (vector dimensions, default 768), `SWARMV_BASE_URL`.
+
+Full documentation: https://edgevec.pages.dev/docs
+
+## License
+
+MIT

swarmv_mcp-1.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "swarmv-mcp"
+version = "1.2.0"
+description = "MCP server for SwarmV: persistent vector memory for AI agents, limited to what the user may access."
+readme = "README.md"
+license = "MIT"
+keywords = ["mcp", "ai", "agents", "memory", "vector", "swarmv"]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.1.2,<2",
+    "swarmv>=1.2.0",
+    "httpx>=0.27"
+]
+
+[project.urls]
+Homepage = "https://edgevec.pages.dev"
+Documentation = "https://edgevec.pages.dev/docs"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/swarmv_mcp", "README.md", "pyproject.toml"]
+exclude = ["**/__pycache__"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/swarmv_mcp"]
+
+[project.scripts]
+swarmv-mcp = "swarmv_mcp.server:main"

swarmv_mcp-1.2.0/src/swarmv_mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP Server implementation for SwarmV in Python."""

swarmv_mcp-1.2.0/src/swarmv_mcp/server.py

@@ -0,0 +1,161 @@
+"""SwarmV MCP server (Python).
+
+The agent always acts as ONE user, fixed by the credentials below and never chosen by the model.
+
+  SWARMV_TOKEN_URL   (recommended) Your backend endpoint returning {"token": "<user token>"} for the
+                     signed-in user. Called with POST; SWARMV_TOKEN_URL_AUTH, if set, is sent as a Bearer
+                     credential. Tokens are refreshed automatically when they expire.
+  SWARMV_USER_TOKEN  A fixed user token from generate_user_token(). Expires within an hour; for testing.
+  SWARMV_API_KEY +   Local development only: the server mints its own tokens for SWARMV_USER_ID.
+  SWARMV_USER_ID     This keeps a backend key on the machine, so don't use it on shared or production hosts.
+"""
+
+import asyncio
+import json
+import os
+import re
+import sys
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+from swarmv import AsyncSwarmV
+
+server = Server("swarmv-mcp-python")
+
+BASE_URL = os.environ.get("SWARMV_BASE_URL", "https://edgevec-edge.lorencogonzaga.workers.dev")
+DIM = int(os.environ.get("SWARMV_DIM", "768"))
+
+
+def _fail(msg: str) -> None:
+    print(msg, file=sys.stderr)
+    sys.exit(1)
+
+
+def _build_client():
+    token_url = os.environ.get("SWARMV_TOKEN_URL")
+    user_token = os.environ.get("SWARMV_USER_TOKEN")
+    api_key = os.environ.get("SWARMV_API_KEY")
+    user_id = os.environ.get("SWARMV_USER_ID")
+
+    if token_url:
+        async def provider() -> str:
+            headers = {}
+            if os.environ.get("SWARMV_TOKEN_URL_AUTH"):
+                headers["Authorization"] = f"Bearer {os.environ['SWARMV_TOKEN_URL_AUTH']}"
+            async with httpx.AsyncClient(timeout=10) as http:
+                res = await http.post(token_url, headers=headers)
+            res.raise_for_status()
+            token = res.json().get("token")
+            if not token:
+                raise RuntimeError("Token endpoint response has no 'token' field")
+            return token
+
+        return AsyncSwarmV(token_provider=provider, base_url=BASE_URL), "token-url"
+
+    if user_token:
+        return AsyncSwarmV(token=user_token, base_url=BASE_URL), "user-token"
+
+    if api_key:
+        if not user_id or not user_id.startswith("user:"):
+            _fail(
+                "SWARMV_API_KEY alone is not allowed: the agent would act with backend-wide access.\n"
+                "Set SWARMV_TOKEN_URL (recommended), or SWARMV_USER_TOKEN, or add SWARMV_USER_ID=user:<id> for local development."
+            )
+        admin = AsyncSwarmV(api_key=api_key, base_url=BASE_URL)
+
+        async def provider() -> str:
+            return await admin.generate_user_token(user_id, 900, scopes=["vector:read", "vector:write"])
+
+        print(f"SwarmV MCP: minting tokens locally for {user_id}. Use SWARMV_TOKEN_URL outside local development.", file=sys.stderr)
+        return AsyncSwarmV(token_provider=provider, base_url=BASE_URL), "local-key"
+
+    _fail("No SwarmV credentials. Set SWARMV_TOKEN_URL (recommended), SWARMV_USER_TOKEN, or SWARMV_API_KEY with SWARMV_USER_ID.")
+
+
+memory, MODE = _build_client()
+
+
+def _pad(v):
+    out = [float(x) for x in v[:DIM]]
+    out.extend([0.0] * (DIM - len(out)))
+    return out
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="read_from_memory",
+            description="Search SwarmV memory. Returns the closest records with their id, distance (lower is closer) and stored metadata, such as the note text. Includes notes written moments ago. Results are limited to the containers the connected user can view.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query_vector": {"type": "array", "items": {"type": "number"}, "description": f"Dense embedding; padded/truncated to {DIM} dimensions."},
+                    "top_k": {"type": "number", "description": "Number of results (1-100, default 10)."},
+                },
+                "required": ["query_vector"],
+            },
+        ),
+        Tool(
+            name="write_to_memory",
+            description="Write a note to SwarmV memory in a container the connected user can edit. Put the note itself in metadata.text so it comes back from read_from_memory.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Numeric string id (unsigned 32-bit integer)."},
+                    "vector": {"type": "array", "items": {"type": "number"}, "description": f"Dense embedding; padded/truncated to {DIM} dimensions."},
+                    "container_id": {"type": "string", "description": "Target container, e.g. 'container:apollo'. The user must be an editor of it."},
+                    "metadata": {"type": "object", "description": "Flat metadata (string, number or boolean values; up to 8 KB), e.g. {text: 'the note'}. Values come back as strings."},
+                },
+                "required": ["id", "vector", "container_id"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
+    try:
+        if name == "read_from_memory":
+            top_k = int(arguments.get("top_k", 10))
+            if not 1 <= top_k <= 100:
+                raise ValueError("top_k must be between 1 and 100")
+            # No auth_user_id: the user is fixed by the credential, so a prompt can't change who we search as.
+            # Agents often read what they (or another agent) just wrote: always include unmerged writes.
+            results = await memory.search(query=_pad(arguments["query_vector"]), top_k=top_k, fresh=True)
+            payload = [{"id": r.id, "distance": r.distance, "metadata": r.metadata} for r in results]
+            return [TextContent(type="text", text=json.dumps(payload, indent=2))]
+
+        if name == "write_to_memory":
+            id_ = str(arguments["id"])
+            if not re.fullmatch(r"\d+", id_):
+                raise ValueError("id must be a numeric string (unsigned 32-bit integer)")
+            container_id = arguments.get("container_id", "")
+            if not str(container_id).startswith("container:"):
+                raise ValueError("container_id must look like 'container:<name>'")
+            metadata = dict(arguments.get("metadata") or {})
+            metadata["container_id"] = container_id
+            # Write immediately (not buffered) so permission errors are reported back to the model.
+            await memory.insert_many([{"id": id_, "vector": _pad(arguments["vector"]), "metadata": metadata}])
+            return [TextContent(type="text", text=f"Stored {id_} in {container_id}.")]
+
+        raise ValueError(f"Unknown tool: {name}")
+
+    except Exception as e:
+        return [TextContent(type="text", text=f"Error executing {name}: {e}")]
+
+
+async def run_server():
+    async with stdio_server() as (read_stream, write_stream):
+        print(f"SwarmV MCP Server (Python) running on stdio (credentials: {MODE})", file=sys.stderr)
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main():
+    asyncio.run(run_server())
+
+
+if __name__ == "__main__":
+    main()