feat(auth): add limited mode (X-UserToken) with scoped tool subset (#2)

Add a runtime-selected limited mode that authenticates via the
X-UserToken service token instead of login/password/2FA. Selection is
implicit: setting PARARAM_USER_TOKEN in the environment switches to
limited mode; login/password are then mutually exclusive and rejected
by Config.validate_credentials.

Limited mode registers a tightly scoped subset of MCP tools matching the
service-token allow-list:

- get_chat (existing aio: get_chat_by_id)
- create_private_chat, create_group_chat, create_thread_chat (new)
- get_chat_messages, get_message_from_url (existing)
- get_reply_thread (new, wraps Post.rerere)
- get_replies_to_post (new, wraps Post.load_reply_posts)
- send_message (existing)
- edit_post (new, wraps Post.edit)
- delete_post (new, wraps Post.delete)

8 new MCP tools, with payload schemas added in models.py. Tool
registration is pruned in server.py after-the-fact via
mcp.local_provider.remove_tool() so existing tool functions don't need
to know about mode.

search_chats is intentionally excluded from limited mode — the
/core/chat/search endpoint demands a `session_id` field whose source
is undocumented for service tokens. Add back once the team documents
the mechanism.

Tool-side notes:

- PararamClient (client.py) branches on config.mode; in limited mode it
  passes user_token= through to AsyncPararamio and never instantiates a
  cookie manager.
- Stale `from pararamio_aio._core import …` imports across client.py
  and tools/*.py are migrated to `pararamio_aio.exceptions` — the
  `_core` shim isn't present in current pararamio-aio HEAD.
- [tool.uv.sources] override pins pararamio-aio to the local
  feat/user-token-auth branch of py-pararamio for development. Revert
  this and bump the version pin to the released aio version before
  merging — marked with a TODO in pyproject.toml.

Verified end-to-end against the real api.pararam.io:

- limited-mode boot succeeds with a real X-UserToken
- get_chat returns chat 360 metadata
- get_reply_thread + get_replies_to_post work for an arbitrary post
- full-mode validation still passes; existing 9 tools still register
  plus 8 net-new tools (20 total in full mode)
- 11 tools register in limited mode (matches the curated allow-list)

Author: ivolnistov

.env.example

@@ -1,18 +1,26 @@
 # Example environment variables for pararam-nexus-mcp
-# Copy this file to .env and fill in the values
-
-# Pararam.io credentials
+# Copy this file to .env and fill in the values.
+#
+# Two authentication modes — pick one:
+#
+# --- Mode A: Full (login + password + optional 2FA) ----------------------
+# All MCP tools are registered. Session is persisted via a cookie file.
 PARARAM_LOGIN=your_login
 PARARAM_PASSWORD=your_password
 
-# Pararam.io 2FA key (required if your account uses 2FA)
-# Get this from your authenticator app settings
+# 2FA key (required if your account has 2FA). From your authenticator app.
 PARARAM_2FA_KEY=your_2fa_key
 
 # Cookie storage path (optional, default: .pararam_cookies.json)
-# Session will be saved here after first successful authentication
 # PARARAM_COOKIE_FILE=.pararam_cookies.json
 
+# --- Mode B: Limited (X-UserToken service token) -------------------------
+# Set PARARAM_USER_TOKEN to enable limited mode. Mutually exclusive with
+# PARARAM_LOGIN/PARARAM_PASSWORD — leave those unset/empty in this mode.
+# Only chat / message / post / replies / edit / delete tools are exposed
+# (no user lookup, no file uploads, no global search). See README "Modes".
+# PARARAM_USER_TOKEN=your_service_token
+
 # Channel settings (optional — enables Claude Code channel notifications)
 # Bot secret key from @infobot new_bot command
 # PARARAM_BOT_SECRET=your_full_bot_secret_key

CLAUDE.md

@@ -48,14 +48,18 @@ FastMCP server providing tools for pararam.io (messaging/collaboration platform)
 
 **Entry point:** `server.py` creates FastMCP instance, registers tools from three modules, runs server on stdio transport.
 
-**Client:** `client.py` — singleton `PararamClient` wrapping `AsyncPararamio` with cookie-based session persistence and TOTP 2FA support.
+**Client:** `client.py` — singleton `PararamClient` wrapping `AsyncPararamio`. In **full** mode it uses cookie-based session persistence + optional TOTP 2FA; in **limited** mode it passes `user_token=` through to `AsyncPararamio` and the cookie manager is never created.
 
-**Config:** `config.py` — Pydantic BaseSettings loading from `.env`. Required: `PARARAM_LOGIN`, `PARARAM_PASSWORD`. Optional: `PARARAM_2FA_KEY`, `PARARAM_COOKIE_FILE`.
+**Config:** `config.py` — Pydantic BaseSettings loading from `.env`. Either set `PARARAM_LOGIN`/`PARARAM_PASSWORD` (+ optional `PARARAM_2FA_KEY`/`PARARAM_COOKIE_FILE`) for full mode, **or** set `PARARAM_USER_TOKEN` for limited mode. The two sets are mutually exclusive; `Config.validate_credentials()` enforces XOR.
+
+**Modes:**
+- `full` (default) — every registered tool is available.
+- `limited` (set when `PARARAM_USER_TOKEN` is present) — the server prunes its tool list to the allow-list defined as `LIMITED_MODE_TOOLS` in `server.py`. User tools (`users.py`) aren't registered at all in limited mode.
 
 **Tools** (in `tools/`):
-- `posts.py` — message search, send, thread building, file upload/download (8 tools)
-- `chats.py` — chat search (1 tool)
-- `users.py` — user search, info, team status (3 tools)
+- `posts.py` — message search, send, thread building, file upload/download, plus limited-mode tools `get_reply_thread`, `get_replies_to_post`, `edit_post`, `delete_post` (12 tools)
+- `chats.py` — chat search/get + create variants (`create_private_chat`, `create_group_chat`, `create_thread_chat`) (5 tools)
+- `users.py` — user search, info, team status (3 tools, full mode only)
 
 Each tool module exports a `register_*_tools(mcp)` function. Tools use `@mcp.tool()` decorator, return `ToolResponse[T]` (generic wrapper with success/message/error/payload).
 

README.md

@@ -133,14 +133,40 @@ uv sync --dev
 
 ## Configuration
 
-Create a `.env` file with your pararam.io credentials:
+The server runs in one of two modes depending on which env vars are set.
+
+### Full mode — login + password (+ optional 2FA)
+
+All tools are registered. Cookies are persisted between runs.
 
 ```env
 PARARAM_LOGIN=your_login
 PARARAM_PASSWORD=your_password
-PARARAM_2FA_KEY=your_2fa_key  # Optional
+PARARAM_2FA_KEY=your_2fa_key  # optional
+```
+
+### Limited mode — `X-UserToken` service token
+
+Set `PARARAM_USER_TOKEN` (mutually exclusive with `PARARAM_LOGIN`/`PARARAM_PASSWORD`).
+Only the chat / message / post / replies / edit / delete tools are registered;
+user lookups, global search, and file ops are excluded.
+
+```env
+PARARAM_USER_TOKEN=your_service_token
 ```
 
+Tools available in limited mode:
+
+- **Chats** — `get_chat`, `create_private_chat`, `create_group_chat`,
+  `create_thread_chat`
+- **Posts** — `get_chat_messages`, `get_message_from_url`,
+  `get_reply_thread`, `get_replies_to_post`, `send_message`,
+  `edit_post`, `delete_post`
+
+> `search_chats` is **not** exposed in limited mode — the underlying
+> `/core/chat/search` endpoint requires a `session_id` field that service
+> tokens don't provide. Will be re-added once the mechanism is documented.
+
 ## MCP Client Configuration
 
 ### Claude Code (CLI)

packages/pararam-nexus-mcp/src/pararam_nexus_mcp/client.py

@@ -4,8 +4,7 @@
 import logging
 from typing import Any
 
-from pararamio_aio import AsyncFileCookieManager, AsyncPararamio
-from pararamio_aio._core import PararamioException
+from pararamio_aio import AsyncFileCookieManager, AsyncPararamio, PararamioException
 
 from pararam_nexus_mcp.auth import get_2fa_key
 from pararam_nexus_mcp.config import config
@@ -30,7 +29,13 @@ def __init__(self) -> None:
         if self._initialized:
             return
         self._client: AsyncPararamio | None = None
-        self._cookie_manager: AsyncFileCookieManager = AsyncFileCookieManager(str(config.pararam_cookie_file))
+        # Cookie manager is only used in full mode; limited (token) mode never
+        # persists session data.
+        self._cookie_manager: AsyncFileCookieManager | None = (
+            None
+            if config.mode == 'limited'
+            else AsyncFileCookieManager(str(config.pararam_cookie_file))
+        )
         self._initialized: bool = True
 
     async def __aenter__(self) -> PararamClient:
@@ -47,22 +52,24 @@ async def connect(self) -> None:
         if self._client is not None:
             return
 
-        logger.info('Connecting to pararam.io')
-
-        # Get 2FA key from config
-        tfa_key = get_2fa_key(config.pararam_2fa_key)
-
-        # Initialize client with cookie manager and enter async context
-        client_context = AsyncPararamio(
-            login=config.pararam_login,
-            password=config.pararam_password,
-            key=tfa_key,
-            cookie_manager=self._cookie_manager,
-        )
-
-        # Enter async context manager to initialize session
-        # AsyncPararamio will automatically load cookies from cookie_manager
-        # and authenticate only if needed
+        logger.info('Connecting to pararam.io (%s mode)', config.mode)
+
+        if config.mode == 'limited':
+            # Token mode: AsyncPararamio sets the X-UserToken header itself and
+            # never needs cookies, login, or 2FA.
+            client_context = AsyncPararamio(user_token=config.pararam_user_token)
+        else:
+            tfa_key = get_2fa_key(config.pararam_2fa_key)
+            client_context = AsyncPararamio(
+                login=config.pararam_login,
+                password=config.pararam_password,
+                key=tfa_key,
+                cookie_manager=self._cookie_manager,
+            )
+
+        # Enter async context manager to initialize session. In full mode
+        # AsyncPararamio loads cookies from cookie_manager and authenticates
+        # only if needed; in limited mode it just opens the httpx session.
         try:
             self._client = await client_context.__aenter__()
             logger.info('Successfully connected to pararam.io')

packages/pararam-nexus-mcp/src/pararam_nexus_mcp/config.py

@@ -1,13 +1,29 @@
 """Configuration management for Pararam Nexus MCP."""
 
 from pathlib import Path
+from typing import Literal
 
 from pydantic import Field, ValidationError
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+Mode = Literal['full', 'limited']
+
 
 class Config(BaseSettings):
-    """Configuration for Pararam Nexus MCP server."""
+    """Configuration for Pararam Nexus MCP server.
+
+    Two authentication modes are supported, selected at startup:
+
+    - **full** (default) — login + password + optional 2FA. All MCP tools
+      are registered.
+    - **limited** — set ``PARARAM_USER_TOKEN`` to an X-UserToken service
+      token. Only the chat/message/post tools listed in the README are
+      registered; file ops and broad search are excluded.
+
+    The two modes are mutually exclusive — providing both
+    ``PARARAM_USER_TOKEN`` and ``PARARAM_LOGIN``/``PARARAM_PASSWORD`` is a
+    configuration error.
+    """
 
     model_config = SettingsConfigDict(
         env_file='.env',
@@ -16,15 +32,21 @@ class Config(BaseSettings):
         extra='ignore',
     )
 
-    # Pararam.io credentials
-    pararam_login: str = Field(..., description='Pararam.io login')
-    pararam_password: str = Field(..., description='Pararam.io password')
-    pararam_2fa_key: str | None = Field(None, description='Pararam.io 2FA key (optional)')
+    # Pararam.io credentials — required in full mode, must be empty in limited mode.
+    pararam_login: str | None = Field(None, description='Pararam.io login (full mode)')
+    pararam_password: str | None = Field(None, description='Pararam.io password (full mode)')
+    pararam_2fa_key: str | None = Field(None, description='Pararam.io 2FA key (full mode, optional)')
 
-    # Cookie storage
+    # Pararam.io service token — selects limited mode when set.
+    pararam_user_token: str | None = Field(
+        None,
+        description='Pararam.io X-UserToken service token (limited mode)',
+    )
+
+    # Cookie storage (full mode only)
     pararam_cookie_file: Path = Field(
         default=Path('.pararam_cookies.json'),
-        description='Path to store authentication cookies',
+        description='Path to store authentication cookies (full mode only)',
     )
 
     # MCP server settings
@@ -38,12 +60,36 @@ class Config(BaseSettings):
         description='MCP server instructions',
     )
 
+    @property
+    def mode(self) -> Mode:
+        """Return 'limited' if a service token is set, else 'full'."""
+        return 'limited' if self.pararam_user_token else 'full'
+
     def validate_credentials(self) -> None:
-        """Validate that required credentials are provided."""
+        """Validate that exactly one auth mode is fully configured.
+
+        Raises:
+            ValueError: If both modes are configured, neither mode is
+                configured, or full mode is missing login/password.
+        """
+        if self.pararam_user_token:
+            if self.pararam_login or self.pararam_password:
+                raise ValueError(
+                    'PARARAM_USER_TOKEN is mutually exclusive with '
+                    'PARARAM_LOGIN/PARARAM_PASSWORD. Unset one or the other.'
+                )
+            return  # limited mode is fully configured
+
         if not self.pararam_login:
-            raise ValueError('PARARAM_LOGIN environment variable is required')
+            raise ValueError(
+                'PARARAM_LOGIN environment variable is required '
+                '(or set PARARAM_USER_TOKEN for limited mode)'
+            )
         if not self.pararam_password:
-            raise ValueError('PARARAM_PASSWORD environment variable is required')
+            raise ValueError(
+                'PARARAM_PASSWORD environment variable is required '
+                '(or set PARARAM_USER_TOKEN for limited mode)'
+            )
 
 
 # Global config instance
@@ -53,7 +99,8 @@ def validate_credentials(self) -> None:
     # Config will fail if .env is missing or fields are invalid, which is expected during development
     # Will be validated at runtime in server.py
     config = Config(
-        pararam_login='',
-        pararam_password='',
+        pararam_login=None,
+        pararam_password=None,
         pararam_2fa_key=None,
+        pararam_user_token=None,
     )

packages/pararam-nexus-mcp/src/pararam_nexus_mcp/models.py

@@ -355,3 +355,53 @@ class GetUserTeamStatusResponse(BaseModel):
     user_id: str = Field(..., description='User ID checked')
     teams_checked: int = Field(..., description='Number of teams checked')
     team_statuses: list[TeamStatus] = Field(..., description='List of team statuses')
+
+
+# Limited-mode (X-UserToken) tool payloads ------------------------------------
+
+
+class GetChatPayload(BaseModel):
+    """Payload for get_chat response."""
+
+    chat: ChatInfo = Field(..., description='Full chat metadata')
+
+
+class CreateChatPayload(BaseModel):
+    """Payload returned by every create_*_chat tool."""
+
+    chat_id: int = Field(..., description='ID of the newly created chat')
+    title: str | None = Field(None, description='Chat title (None for private chats)')
+    type: str = Field(..., description='Chat type: pm, group, or thread')
+
+
+class ReplyThreadPayload(BaseModel):
+    """Payload for get_reply_thread response (server-side rerere traversal)."""
+
+    chat_id: int = Field(..., description='ID of the chat')
+    root_post_no: int = Field(..., description='Post number the thread was rooted at')
+    post_nos: list[int] = Field(..., description='Post numbers in the thread, in server order')
+
+
+class RepliesToPostPayload(BaseModel):
+    """Payload for get_replies_to_post response (direct children only)."""
+
+    chat_id: int = Field(..., description='ID of the chat')
+    post_no: int = Field(..., description='Post number replies were requested for')
+    count: int = Field(..., description='Number of direct replies')
+    replies: list[PostInfo] = Field(..., description='Hydrated reply posts')
+
+
+class EditPostPayload(BaseModel):
+    """Payload for edit_post response."""
+
+    chat_id: int = Field(..., description='ID of the chat')
+    post_no: int = Field(..., description='Post number that was edited')
+    text: str = Field(..., description='New post text after edit')
+
+
+class DeletePostPayload(BaseModel):
+    """Payload for delete_post response."""
+
+    chat_id: int = Field(..., description='ID of the chat')
+    post_no: int = Field(..., description='Post number that was deleted')
+    is_deleted: bool = Field(..., description='Whether the post is now marked deleted')