cocalc-api/mcp: dynamic tool and resource registration based on api key type

Author: haraldschilly

src/python/cocalc-api/src/cocalc_api/mcp/DEVELOPMENT.md

@@ -1,17 +1,14 @@
 # CoCalc API MCP Server
 
-A Model Context Protocol (MCP) server that allows LLMs to interact with CoCalc projects.
+A Model Context Protocol (MCP) server that provides LLMs (Claude, etc.) with direct access to CoCalc accounts and projects.
 
 ## Quick Start
 
-### 1. Configuration
-
-Set environment variables:
+### 1. Set Environment Variables
 
 ```bash
-export COCALC_API_KEY="sk-your-api-key"
-export COCALC_PROJECT_ID="your-project-uuid"
-export COCALC_HOST="https://cocalc.com"  # optional, defaults to https://cocalc.com
+export COCALC_API_KEY="sk-your-api-key"  # Account or project-scoped
+export COCALC_HOST="http://localhost:5000"  # Optional, defaults to https://cocalc.com
 ```
 
 ### 2. Run the Server
@@ -20,46 +17,31 @@ export COCALC_HOST="https://cocalc.com"  # optional, defaults to https://cocalc.
 uv run cocalc-mcp-server
 ```
 
-### 3. Setup with Claude Code CLI
+The server will detect your API key type and automatically register the appropriate tools/resources.
+
+## Setup with Claude Code
+
+### Quick Registration
 
 ```bash
-# Set your credentials
-export COCALC_API_KEY="sk-your-api-key-here"
-export COCALC_PROJECT_ID="[UUID]"
-export COCALC_API_PATH="/path/to/cocalc/src/python/cocalc-api"
-# OPTIONAL: set the host, defaults to cocalc.com. for development use localhost:5000
-export COCALC_HOST="http://localhost:5000"
-
-# Add the MCP server to Claude Code
 claude mcp add \
   --transport stdio \
   cocalc \
-  --env COCALC_API_KEY="$COCALC_API_KEY" \
-  --env COCALC_PROJECT_ID="$COCALC_PROJECT_ID" \
-  --env COCALC_HOST="$COCALC_HOST" \
-  -- uv --directory "$COCALC_API_PATH" run cocalc-mcp-server
+  --env COCALC_API_KEY="sk-your-api-key" \
+  -- uv --directory /path/to/cocalc-api run cocalc-mcp-server
 ```
 
-Alternatively, using JSON configuration:
+### Via JSON Config
 
 ```bash
 claude mcp add-json cocalc '{
   "command": "uv",
-  "args": ["--directory", "/path/to/cocalc/src/python/cocalc-api", "run", "cocalc-mcp-server"],
-  "env": {
-    "COCALC_API_KEY": "sk-your-api-key-here",
-    "COCALC_PROJECT_ID": "[UUID]",
-    "COCALC_HOST": "http://localhost:5000"
-  }
+  "args": ["--directory", "/path/to/cocalc-api", "run", "cocalc-mcp-server"],
+  "env": {"COCALC_API_KEY": "sk-your-api-key"}
 }'
 ```
 
-**Important:**
-
-- Replace `/path/to/cocalc/src/python/cocalc-api` with the absolute path to your cocalc-api directory.
-- Replace `http://localhost:5000` with your CoCalc instance URL (defaults to `https://cocalc.com` if not set).
-
-### 4. Setup with Claude Desktop
+## Setup with Claude Desktop
 
 Add to `~/.config/Claude/claude_desktop_config.json`:
 
@@ -68,111 +50,62 @@ Add to `~/.config/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "cocalc": {
       "command": "uv",
-      "args": [
-        "--directory",
-        "/path/to/cocalc/src/python/cocalc-api",
-        "run",
-        "cocalc-mcp-server"
-      ],
-      "env": {
-        "COCALC_API_KEY": "sk-your-api-key-here",
-        "COCALC_PROJECT_ID": "[UUID]",
-        "COCALC_HOST": "http://localhost:5000"
-      }
+      "args": ["--directory", "/path/to/cocalc-api", "run", "cocalc-mcp-server"],
+      "env": {"COCALC_API_KEY": "sk-your-api-key"}
     }
   }
 }
 ```
 
-**Important:**
-
-- Replace `/path/to/cocalc/src/python/cocalc-api` with the absolute path to your cocalc-api directory.
-- Replace `http://localhost:5000` with your CoCalc instance URL (defaults to `https://cocalc.com` if not set).
-
-### 5. Allow MCP Tools in Claude Code Settings
+## Allow Tools in Claude Code Settings
 
-To automatically allow all CoCalc MCP tools without prompts, add this to `.claude/settings.json`:
+Add to `.claude/settings.json`:
 
 ```json
 {
   "allowedTools": ["mcp__cocalc__*"]
 }
 ```
 
-This wildcard pattern (`mcp__cocalc__*`) automatically allows:
+## Available Tools & Resources
 
-- `mcp__cocalc__exec` - Execute shell commands
-- `mcp__cocalc__project_files` - Browse project files
-- Any future tools added to the MCP server
+The server automatically provides different tools based on your API key type:
 
-## Features
+### Account-Scoped API Keys
 
-### Tools
+**Tools:**
+- `projects_search(query="")` - Search and list your projects with collaborator info
 
-- **`exec`** - Execute shell commands in the project
+**Resources:**
+- `cocalc://account-profile` - View your account info, settings, and preferences
 
-  ```
-  Tool: exec
-  Params: command (required), args, bash, timeout, cwd
-  Returns: {stdout, stderr, exit_code}
-  ```
+### Project-Scoped API Keys
 
-- **`jupyter_execute`** - Execute code using Jupyter kernels
-  ```
-  Tool: jupyter_execute
-  Params: input (required), kernel (default: "python3"), history
-  Returns: Formatted execution output (text, plots, errors, etc.)
-  ```
+**Tools:**
+- `exec(command)` - Execute shell commands in the project
+- `jupyter_execute(input, kernel="python3")` - Run code using Jupyter kernels
 
-### Resources
+**Resources:**
+- `cocalc://project-files` - Browse the project directory structure
 
-- **`project-files`** - Browse project files with filtering and pagination
-  ```
-  URI: cocalc://project-files/{path}?glob=*.py&limit=100&recurse=true
-  Returns: File listing with metadata
-  ```
+## API Keys
 
-## Documentation
+Create API keys at:
+- **Account-scoped**: CoCalc Settings → API keys → Create API key
+- **Project-scoped**: Project Settings → API keys → Create API key
 
-See [DEVELOPMENT.md](./DEVELOPMENT.md) for:
-
-- Architecture and design principles
-- Detailed API specifications
-- Configuration options
-- Testing strategy
-- Future roadmap
-
-## Directory Structure
-
-```
-src/cocalc_api/mcp/
-├── README.md                 # This file
-├── DEVELOPMENT.md            # Architecture & design documentation
-├── server.py                 # Main MCP server
-├── mcp_server.py            # MCP instance and project client coordination
-├── __main__.py              # Module entry point
-├── tools/
-│   ├── exec.py              # Shell command execution tool
-│   └── __init__.py
-└── resources/
-    ├── file_listing.py      # File listing resource
-    └── __init__.py
-```
-
-## Requirements
+## Security
 
-- Python 3.10+
-- mcp>=1.0
-- httpx
-- pydantic (via mcp)
+- Never commit API keys to version control
+- Use restricted file permissions (600) on config files with API keys
+- Each server instance is isolated to its scope (account or project)
+- Commands execute with the permissions of your API key
 
-## Security
+## Development
 
-- API keys should never be committed to version control
-- Use restricted file permissions (600) on config files containing API keys
-- Each server instance is scoped to a single project
-- Commands execute with the permissions of the CoCalc project user
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for architecture, design patterns, and adding new tools.
 
-## Next Steps
+## References
 
-See [DEVELOPMENT.md](./DEVELOPMENT.md#next-steps) for implementation roadmap and upcoming features.
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [CoCalc API Documentation](https://github.com/sagemathinc/cocalc)

src/python/cocalc-api/src/cocalc_api/mcp/README.md

@@ -2,35 +2,39 @@
 CoCalc MCP (Model Context Protocol) Server - Central Coordination Module
 
 This MCP server gives you direct access to a CoCalc project or account environment.
+The available tools and resources depend on your API key type (account-scoped or project-scoped).
 
-AVAILABLE TOOLS (actions you can perform):
+AVAILABLE TOOLS - PROJECT-SCOPED KEYS:
 - exec: Run shell commands, scripts, and programs in the project
   Use for: running code, data processing, build/test commands, git operations, etc.
 - jupyter_execute: Execute code using Jupyter kernels (Python, R, Julia, etc.)
   Use for: interactive code execution, data analysis, visualization, scientific computing
 
-AVAILABLE RESOURCES (information you can read):
+AVAILABLE TOOLS - ACCOUNT-SCOPED KEYS:
+- projects_search: Search for and list projects you have access to
+  Use for: discovering projects, seeing collaborators, checking project states
+
+AVAILABLE RESOURCES - PROJECT-SCOPED KEYS:
 - project-files: Browse the project file structure
   Use for: exploring what files exist, understanding project layout, locating files to work with
 
-HOW IT WORKS:
-- You can use these tools and resources to understand, modify, and manage files in the project
-- The project runs in an Ubuntu Linux container with common development tools pre-installed
-- Commands execute with the permissions of the CoCalc project user
-- All operations are scoped to this single project
+AVAILABLE RESOURCES - ACCOUNT-SCOPED KEYS:
+- account-profile: View your account profile and settings
+  Use for: checking personal info, account settings, preferences
 
-WHEN TO USE WHICH:
-1. First, use project-files to explore and understand the project structure
-2. Then, use exec to run commands, edit files, run tests, etc.
-3. Use project-files again if you need to navigate to new directories
-4. Use exec for anything the project-files resource can't show (recursive listings, complex queries, etc.)
+HOW IT WORKS:
+- Account-scoped keys: Access your account information, manage projects, view profile
+- Project-scoped keys: Execute code, run commands, and manage files in a specific project
+- All operations are secure and scoped to what your API key authorizes
 
 AUTHENTICATION & CONFIGURATION:
 Required environment variables (already set when this server is running):
 - COCALC_API_KEY: Your CoCalc API authentication token (account-scoped or project-scoped)
 - COCALC_HOST: (optional) Your CoCalc instance URL (defaults to https://cocalc.com)
+- COCALC_PROJECT_ID: (optional) Project ID for project-scoped keys
 
-The server will validate your API key on startup and report whether it's account-scoped or project-scoped.
+The server will validate your API key on startup and automatically register the appropriate
+tools and resources based on whether it's account-scoped or project-scoped.
 """
 
 import os
@@ -279,13 +283,33 @@ def get_project_client(project_id: Optional[str] = None) -> Project:
     return client
 
 
-# Register tools and resources
-# This happens at module import time, auto-registering with the mcp instance
-from . import tools as tools_module  # noqa: E402
-from . import resources as resources_module  # noqa: E402
+def _register_tools_and_resources() -> None:
+    """Register tools and resources based on API key scope."""
+    global _api_key_scope
+
+    _initialize_config()
+
+    # Determine which tools/resources to register based on API key scope
+    if _api_key_scope and "account_id" in _api_key_scope:
+        # Account-scoped key: register account-scoped tools/resources
+        print("Registering account-scoped tools and resources...", file=sys.stderr)
+        from .tools.projects_search import register_projects_search_tool
+        from .resources.account_profile import register_account_profile_resource
+
+        register_projects_search_tool(mcp)
+        register_account_profile_resource(mcp)
+
+    elif _api_key_scope and "project_id" in _api_key_scope:
+        # Project-scoped key: register project-scoped tools/resources
+        print("Registering project-scoped tools and resources...", file=sys.stderr)
+        from .tools.exec import register_exec_tool
+        from .tools.jupyter import register_jupyter_tool
+        from .resources.file_listing import register_file_listing_resource
+
+        register_exec_tool(mcp)
+        register_jupyter_tool(mcp)
+        register_file_listing_resource(mcp)
 
-tools_module.register_tools(mcp)
-resources_module.register_resources(mcp)
 
-# Initialize configuration and validate API key at startup
-_initialize_config()
+# Initialize configuration and validate API key at startup, then register tools/resources
+_register_tools_and_resources()

src/python/cocalc-api/src/cocalc_api/mcp/mcp_server.py

@@ -1,18 +1,17 @@
 """
 CoCalc MCP Resources - Available Information
 
-Resources are read-only information you can access about the CoCalc project.
+Resources are read-only information you can access about the CoCalc project or account.
 
-Available Resources:
-- project-files: Browse and list files in the project directory structure
+Resources are dynamically registered based on API key scope:
 
-See mcp_server.py for overview of all available tools and resources, and guidance
-on when to use each one.
-"""
+PROJECT-SCOPED KEYS:
+- project-files: Browse and list files in the project directory structure
 
+ACCOUNT-SCOPED KEYS:
+- account-profile: View account profile information
 
-def register_resources(mcp) -> None:
-    """Register all resources with the given FastMCP instance."""
-    from .file_listing import register_file_listing_resource
+See mcp_server.py for overview of all available tools and resources.
 
-    register_file_listing_resource(mcp)
+Note: Individual resource registration functions are imported directly by mcp_server.py.
+"""