tungsten-mcp 0.1.0__tar.gz

tungsten_mcp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+frontend/node_modules/
+storage/
+*.db
+*.sqlite3
+.DS_Store
+.claude/worktrees/

tungsten_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: tungsten-mcp
+Version: 0.1.0
+Summary: Tungsten plugin: an MCP server so AI assistants like Claude can read and change your admin panel's data.
+Project-URL: Homepage, https://tungsten.prisminfoways.com/
+Project-URL: Repository, https://github.com/Prism-Infoways/Tungsten
+Author: Prism Infoways
+License: MIT
+Keywords: ai,claude,fastapi,llm,mcp,model context protocol,tungsten,tungsten-admin
+Requires-Python: >=3.10
+Requires-Dist: tungsten-admin>=0.1.4
+Description-Content-Type: text/markdown
+
+# tungsten-mcp
+
+Let AI assistants like Claude work with your [Tungsten](https://tungsten.prisminfoways.com/) panel, through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).
+
+Ask things like *"Show the 10 newest orders"*, *"How many products are out of stock?"* or *"Mark order 1042 as shipped"*, and the AI does it with your panel's data.
+
+## What you get
+
+- An MCP server inside your panel, at `/admin/mcp`.
+- Tools for every resource: `list_resources`, `describe_resource`, `list_records` (search, filters, sort, pages), `get_record`, and with a token that allows changes, `create_record`, `update_record`, `delete_record`.
+- Login with OAuth: in Claude, add the server URL as a custom connector, press Connect, log in to your panel and press Allow. No token to copy.
+- An **AI access (MCP)** screen to see and revoke connected apps and tokens, with a **How to connect** guide for Claude, Claude Code, Claude Desktop and other apps.
+
+It is safe by default:
+
+- Each token acts as the user who made it. Their roles, policies and tenancy apply, as in the panel.
+- Writes go through the resource's form: the same validation, defaults and hooks, and they show in the activity log.
+- Tokens are read-only unless you switch on **Allow changes**. Only a hash of each token is stored.
+- Password hashes, tokens, secrets and API keys are never sent.
+
+## Install
+
+```bash
+pip install tungsten-mcp
+```
+
+```python
+from tungsten_mcp import McpPlugin
+
+panel = Panel(..., app_url="https://admin.example.com")
+panel.plugin(McpPlugin())
+panel.create_tables(engine)
+```
+
+Then open **AI access (MCP)** in the panel and press **How to connect**. Needs `tungsten-admin` 0.1.4 or newer.
+
+## Connect
+
+**Claude (web, desktop, phone)**: Settings, Connectors, Add custom connector, paste `https://admin.example.com/admin/mcp`, then Connect. Log in to the panel and press Allow.
+
+**Claude Code** with login: `claude mcp add --transport http tungsten https://admin.example.com/admin/mcp`, then `/mcp` in Claude Code.
+
+Apps without MCP login use a token: press **New token** on the AI access (MCP) screen.
+
+**Claude Code** with a token
+
+```bash
+claude mcp add --transport http tungsten https://admin.example.com/admin/mcp --header "Authorization: Bearer YOUR_TOKEN"
+```
+
+**Claude Desktop** (Settings, Developer, Edit Config; needs Node.js)
+
+```json
+{
+  "mcpServers": {
+    "tungsten": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://admin.example.com/admin/mcp", "--header", "Authorization:${AUTH_HEADER}"],
+      "env": {"AUTH_HEADER": "Bearer YOUR_TOKEN"}
+    }
+  }
+}
+```
+
+**Cursor, VS Code and others**: a Streamable HTTP server with the URL and an `Authorization: Bearer YOUR_TOKEN` header.
+
+## Options
+
+```python
+McpPlugin(
+    path="/mcp",                      # where the server answers, under the panel
+    read_only=False,                  # True: no create, update or delete for any token
+    resources=None,                   # only these resources (slugs or classes)
+    exclude=["users"],                # leave these out
+    hidden_fields=["customers.phone", "notes"],   # never send these columns
+    max_limit=100,                    # most records per list_records call
+    name="Shop admin",                # the name the AI app shows
+    oauth=True,                       # apps can connect by logging in (needs a panel with login)
+    token_minutes=60,                 # how long an OAuth access token works
+)
+```
+
+With [multi-tenancy](https://tungsten.prisminfoways.com/docs/multi-tenancy.html), the token's user works in their first tenant. Send an `X-Tenant: <id>` header to pick another.

tungsten_mcp-0.1.0/README.md

@@ -0,0 +1,83 @@
+# tungsten-mcp
+
+Let AI assistants like Claude work with your [Tungsten](https://tungsten.prisminfoways.com/) panel, through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).
+
+Ask things like *"Show the 10 newest orders"*, *"How many products are out of stock?"* or *"Mark order 1042 as shipped"*, and the AI does it with your panel's data.
+
+## What you get
+
+- An MCP server inside your panel, at `/admin/mcp`.
+- Tools for every resource: `list_resources`, `describe_resource`, `list_records` (search, filters, sort, pages), `get_record`, and with a token that allows changes, `create_record`, `update_record`, `delete_record`.
+- Login with OAuth: in Claude, add the server URL as a custom connector, press Connect, log in to your panel and press Allow. No token to copy.
+- An **AI access (MCP)** screen to see and revoke connected apps and tokens, with a **How to connect** guide for Claude, Claude Code, Claude Desktop and other apps.
+
+It is safe by default:
+
+- Each token acts as the user who made it. Their roles, policies and tenancy apply, as in the panel.
+- Writes go through the resource's form: the same validation, defaults and hooks, and they show in the activity log.
+- Tokens are read-only unless you switch on **Allow changes**. Only a hash of each token is stored.
+- Password hashes, tokens, secrets and API keys are never sent.
+
+## Install
+
+```bash
+pip install tungsten-mcp
+```
+
+```python
+from tungsten_mcp import McpPlugin
+
+panel = Panel(..., app_url="https://admin.example.com")
+panel.plugin(McpPlugin())
+panel.create_tables(engine)
+```
+
+Then open **AI access (MCP)** in the panel and press **How to connect**. Needs `tungsten-admin` 0.1.4 or newer.
+
+## Connect
+
+**Claude (web, desktop, phone)**: Settings, Connectors, Add custom connector, paste `https://admin.example.com/admin/mcp`, then Connect. Log in to the panel and press Allow.
+
+**Claude Code** with login: `claude mcp add --transport http tungsten https://admin.example.com/admin/mcp`, then `/mcp` in Claude Code.
+
+Apps without MCP login use a token: press **New token** on the AI access (MCP) screen.
+
+**Claude Code** with a token
+
+```bash
+claude mcp add --transport http tungsten https://admin.example.com/admin/mcp --header "Authorization: Bearer YOUR_TOKEN"
+```
+
+**Claude Desktop** (Settings, Developer, Edit Config; needs Node.js)
+
+```json
+{
+  "mcpServers": {
+    "tungsten": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://admin.example.com/admin/mcp", "--header", "Authorization:${AUTH_HEADER}"],
+      "env": {"AUTH_HEADER": "Bearer YOUR_TOKEN"}
+    }
+  }
+}
+```
+
+**Cursor, VS Code and others**: a Streamable HTTP server with the URL and an `Authorization: Bearer YOUR_TOKEN` header.
+
+## Options
+
+```python
+McpPlugin(
+    path="/mcp",                      # where the server answers, under the panel
+    read_only=False,                  # True: no create, update or delete for any token
+    resources=None,                   # only these resources (slugs or classes)
+    exclude=["users"],                # leave these out
+    hidden_fields=["customers.phone", "notes"],   # never send these columns
+    max_limit=100,                    # most records per list_records call
+    name="Shop admin",                # the name the AI app shows
+    oauth=True,                       # apps can connect by logging in (needs a panel with login)
+    token_minutes=60,                 # how long an OAuth access token works
+)
+```
+
+With [multi-tenancy](https://tungsten.prisminfoways.com/docs/multi-tenancy.html), the token's user works in their first tenant. Send an `X-Tenant: <id>` header to pick another.

tungsten_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tungsten-mcp"
+version = "0.1.0"
+description = "Tungsten plugin: an MCP server so AI assistants like Claude can read and change your admin panel's data."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Prism Infoways" }]
+keywords = ["tungsten", "tungsten-admin", "mcp", "model context protocol", "claude", "ai", "llm", "fastapi"]
+dependencies = ["tungsten-admin>=0.1.4"]
+
+[project.urls]
+Homepage = "https://tungsten.prisminfoways.com/"
+Repository = "https://github.com/Prism-Infoways/Tungsten"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tungsten_mcp"]

tungsten_mcp-0.1.0/src/tungsten_mcp/__init__.py

@@ -0,0 +1,174 @@
+"""Let AI assistants (Claude and other MCP apps) work with your Tungsten panel.
+
+    from tungsten_mcp import McpPlugin
+
+    panel.plugin(McpPlugin())
+    panel.create_tables(engine)
+
+Open "AI access (MCP)" in the panel, make a token, and press "How to connect". The panel's
+resources then show up in the AI app as tools: list, search, read, and (with a token that
+allows changes) create, update and delete records. Every call runs as the token's user, so
+their roles, policies and tenancy apply, and writes go through the resource's form.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from tungsten import Plugin
+
+from .models import McpBase, McpOAuthClient, McpOAuthCode, McpToken, hash_token, new_token
+from .oauth import AuthorizePage, OAuth
+from .resources import McpTokenResource
+from .server import McpServer
+from .tools import SENSITIVE, ToolError, Tools
+
+__version__ = "0.1.0"
+
+DEFAULT_INSTRUCTIONS = (
+    "These tools work with the records of a Tungsten admin panel. Start with list_resources, then "
+    "describe_resource to see a resource's columns and form fields. list_records finds records "
+    "(search, filters, sort, paging); get_record reads one. Each record has _id, _title and a _url "
+    "link to it in the panel."
+)
+
+
+class McpPlugin(Plugin):
+    """``McpPlugin(path="/mcp", read_only=False, resources=None, exclude=(), hidden_fields=(), max_limit=100)``.
+
+    - ``path``: where the MCP server answers, under the panel (``/admin/mcp``).
+    - ``read_only``: no create, update or delete tools for any token.
+    - ``resources``: only these resources (slugs or classes). Default: all of them.
+    - ``exclude``: resources to leave out (slugs or classes).
+    - ``hidden_fields``: columns never sent, as ``"email"`` (every resource) or ``"customers.email"``.
+      Passwords, tokens, secrets and API keys are always hidden.
+    - ``max_limit``: most records one ``list_records`` call returns.
+    - ``name``/``instructions``: what the AI app is told about this server.
+    - ``public_url``: this site's address for the URL in "How to connect". Default: the panel's
+      ``app_url``, then the address in the browser.
+    - ``oauth``: let apps connect by logging in (OAuth 2.1 with PKCE), besides tokens made on
+      the screen. Needs a panel with login. ``allow_registration=False`` stops new apps.
+    - ``token_minutes``: how long an OAuth access token works before the app refreshes it.
+    """
+
+    id = "mcp"
+    metadata = McpBase.metadata
+    templates = Path(__file__).with_name("templates")
+
+    def __init__(self, path: str = "/mcp", *, read_only: bool = False, resources: Iterable[Any] | None = None,
+                 exclude: Iterable[Any] = (), hidden_fields: Iterable[str] = (), max_limit: int = 100,
+                 name: str | None = None, instructions: str | None = None, public_url: str | None = None,
+                 oauth: bool = True, allow_registration: bool = True, token_minutes: int = 60) -> None:
+        self.path = "/" + path.strip("/")
+        self.read_only = read_only
+        self.only = {_slug(r) for r in resources} if resources is not None else None
+        self.exclude = {_slug(r) for r in exclude} | {McpTokenResource.get_slug()}
+        self.hidden_fields = set(hidden_fields)
+        self.max_limit = max_limit
+        self.name = name
+        self.instructions = instructions
+        self.public_url = public_url.rstrip("/") if public_url else None
+        self.oauth_wanted = oauth
+        self.allow_registration = allow_registration
+        self.token_seconds = token_minutes * 60
+        self.panel: Any = None
+        self.server = McpServer(self)
+        self.oauth = OAuth(self)
+
+    def register(self, panel: Any) -> None:
+        self.panel = panel
+        panel.resources([McpTokenResource])
+        panel.routes(self._routes)
+        if self.oauth_enabled:
+            panel.pages([AuthorizePage])
+            panel.routes(self.oauth.routes)
+
+    @property
+    def oauth_enabled(self) -> bool:
+        return bool(self.oauth_wanted and self.panel is not None and self.panel.auth.enabled)
+
+    def mount(self, app: Any, panel: Any) -> None:
+        # MCP apps look for the OAuth metadata at the site root, e.g. /.well-known/oauth-authorization-server/admin
+        if self.oauth_enabled and panel.path:
+            self.oauth.well_known_routes(app, prefix=panel.path)
+            self.oauth.well_known_routes(app)  # older apps drop the path
+
+    def _routes(self, app: Any, panel: Any) -> None:
+        server = self.server
+
+        @app.post(self.path)
+        async def mcp(request: Request):
+            return await server.handle_http(request)
+
+        @app.get(self.path)
+        async def mcp_get(request: Request):
+            # no server-sent events stream: clients fall back to plain POSTs
+            return JSONResponse({"error": "Use POST for MCP messages."}, status_code=405, headers={"Allow": "POST"})
+
+    # ------------------------------------------------------------------ settings
+    def exposes(self, resource: Any) -> bool:
+        slug = resource.get_slug()
+        if slug in self.exclude:
+            return False
+        return self.only is None or slug in self.only
+
+    def hidden_for(self, resource: Any) -> set[str]:
+        slug = resource.get_slug()
+        out = set()
+        for item in self.hidden_fields:
+            owner, _, column = item.rpartition(".")
+            if not owner or owner == slug:
+                out.add(column)
+        return out
+
+    def base_url(self, request: Request) -> str:
+        """``https://host`` of this site (no panel path)."""
+        base = self.public_url or self.panel.app_url
+        if not base:
+            proto = request.headers.get("x-forwarded-proto") or request.url.scheme
+            base = f"{proto}://{request.headers.get('host') or request.url.netloc}"
+        return base.rstrip("/")
+
+    def endpoint_url(self, request: Request) -> str:
+        return self.base_url(request) + self.panel.url(self.path.strip("/"))
+
+    def server_title(self) -> str:
+        return self.name or f"{self.panel.brand_name} admin"
+
+    def instructions_for(self, can_write: bool) -> str:
+        if self.instructions:
+            return self.instructions
+        text = DEFAULT_INSTRUCTIONS
+        if can_write:
+            text += (" create_record, update_record and delete_record change data: confirm with the user "
+                     "before changing or deleting records they did not ask about.")
+        else:
+            text += " This connection can only read."
+        return text
+
+
+def _slug(resource: Any) -> str:
+    return resource if isinstance(resource, str) else resource.get_slug()
+
+
+__all__ = [
+    "SENSITIVE",
+    "AuthorizePage",
+    "McpOAuthClient",
+    "McpOAuthCode",
+    "McpPlugin",
+    "McpServer",
+    "McpToken",
+    "McpTokenResource",
+    "OAuth",
+    "ToolError",
+    "Tools",
+    "__version__",
+    "hash_token",
+    "new_token",
+]

tungsten_mcp-0.1.0/src/tungsten_mcp/models.py

@@ -0,0 +1,80 @@
+"""Tables of the MCP plugin."""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import secrets
+
+from sqlalchemy import JSON, Boolean, DateTime, Integer, String, Text
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+#: every token starts with this, so a leaked one is easy to spot in logs and code
+TOKEN_PREFIX = "tgmcp_"
+
+
+def _now() -> dt.datetime:
+    return dt.datetime.now()
+
+
+def new_token() -> str:
+    return TOKEN_PREFIX + secrets.token_urlsafe(32)
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+class McpBase(DeclarativeBase):
+    pass
+
+
+class McpToken(McpBase):
+    """An access token for one AI client. Only its hash is kept; the token itself is shown once."""
+
+    __tablename__ = "tungsten_mcp_tokens"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+    #: the panel user the AI acts as (their roles and permissions apply); None when the panel has no login
+    user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True)
+    #: first characters of the token, to tell tokens apart in the list
+    hint: Mapped[str] = mapped_column(String(16))
+    can_write: Mapped[bool] = mapped_column(Boolean, default=False)
+    #: set for tokens an app got by OAuth (its ``client_id``); None for tokens made on the screen
+    client_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    #: OAuth access tokens expire; the app swaps its refresh token for a new pair
+    expires_at: Mapped[dt.datetime | None] = mapped_column(DateTime, nullable=True)
+    refresh_hash: Mapped[str | None] = mapped_column(String(64), nullable=True, unique=True)
+    last_used_at: Mapped[dt.datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[dt.datetime] = mapped_column(DateTime, default=_now)
+
+
+class McpOAuthClient(McpBase):
+    """An AI app that registered itself (OAuth dynamic client registration)."""
+
+    __tablename__ = "tungsten_mcp_oauth_clients"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    client_id: Mapped[str] = mapped_column(String(64), unique=True)
+    #: None for public clients (apps on a computer), which prove themselves with PKCE alone
+    secret_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    name: Mapped[str] = mapped_column(String(200))
+    redirect_uris: Mapped[list] = mapped_column(JSON)
+    created_at: Mapped[dt.datetime] = mapped_column(DateTime, default=_now)
+
+
+class McpOAuthCode(McpBase):
+    """A one-time code, given to the app after the user pressed Allow."""
+
+    __tablename__ = "tungsten_mcp_oauth_codes"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    code_hash: Mapped[str] = mapped_column(String(64), unique=True)
+    client_id: Mapped[str] = mapped_column(String(64))
+    user_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    redirect_uri: Mapped[str] = mapped_column(Text)
+    code_challenge: Mapped[str] = mapped_column(String(128))
+    can_write: Mapped[bool] = mapped_column(Boolean, default=False)
+    expires_at: Mapped[dt.datetime] = mapped_column(DateTime)