cocalc-api/mcp: refine authentication

Author: haraldschilly

src/packages/conat/hub/api/system.ts

@@ -9,6 +9,7 @@ import { type UserSearchResult } from "@cocalc/util/db-schema/accounts";
 export const system = {
   getCustomize: noAuth,
   ping: noAuth,
+  test: authFirst,
   terminate: authFirst,
   userTracking: authFirst,
   logClientError: authFirst,
@@ -31,6 +32,8 @@ export interface System {
   getCustomize: (fields?: string[]) => Promise<Customize>;
   // ping server and get back the current time
   ping: () => { now: number };
+  // test API key and return scope information (account_id or project_id) and server time
+  test: () => Promise<{ account_id?: string; project_id?: string; server_time: number }>;
   // terminate a service:
   //   - only admin can do this.
   //   - useful for development

src/packages/conat/project/api/system.ts

@@ -28,6 +28,7 @@ export const system = {
   configuration: true,
 
   ping: true,
+  test: true,
   exec: true,
 
   signal: true,
@@ -69,6 +70,8 @@ export interface System {
 
   ping: () => Promise<{ now: number }>;
 
+  test: () => Promise<{ project_id: string; server_time: number }>;
+
   exec: (opts: ExecuteCodeOptions) => Promise<ExecuteCodeOutput>;
 
   signal: (opts: {

src/packages/next/pages/api/conat/project.ts

@@ -58,6 +58,11 @@ export default async function handle(req, res) {
       args,
       timeout,
     });
+    // For project-scoped API keys, include the project_id in the response
+    // so the client can discover it
+    if (project_id0 && !resp.project_id) {
+      resp.project_id = project_id0;
+    }
     res.json(resp);
   } catch (err) {
     res.json({ error: err.message });

src/packages/project/conat/api/system.ts

@@ -2,6 +2,17 @@ export async function ping() {
   return { now: Date.now() };
 }
 
+export async function test({
+  project_id,
+}: {
+  project_id?: string;
+} = {}) {
+  return {
+    project_id: project_id ?? "",
+    server_time: Date.now(),
+  };
+}
+
 export async function terminate() {}
 
 import { handleExecShellCode } from "@cocalc/project/exec_shell_code";

src/packages/server/api/project-bridge.ts

@@ -51,7 +51,12 @@ async function callProject({
     service: "api",
   });
   try {
-    const data = { name, args };
+    // For system.test(), inject project_id into args[0] if not already present
+    let finalArgs = args;
+    if (name === "system.test" && (!args || args.length === 0)) {
+      finalArgs = [{ project_id }];
+    }
+    const data = { name, args: finalArgs };
     // we use waitForInterest because often the project hasn't
     // quite fully started.
     const resp = await client.request(subject, data, {

src/packages/server/conat/api/system.ts

@@ -18,6 +18,26 @@ export function ping() {
   return { now: Date.now() };
 }
 
+export async function test({
+  account_id,
+  project_id,
+}: { account_id?: string; project_id?: string } = {}) {
+  // Return API key scope information and server time
+  // The authFirst decorator determines the scope from the API key and injects
+  // either account_id (for account-scoped keys) or project_id (for project-scoped keys)
+  // into this parameter object.
+  const response: { account_id?: string; project_id?: string; server_time: number } = {
+    server_time: Date.now(),
+  };
+  if (account_id) {
+    response.account_id = account_id;
+  }
+  if (project_id) {
+    response.project_id = project_id;
+  }
+  return response;
+}
+
 export async function terminate() {}
 
 export async function userTracking({

src/python/cocalc-api/Makefile

@@ -11,7 +11,8 @@ help:
 	@echo "  coverage         - Run tests with coverage reporting (HTML + terminal)"
 	@echo "  coverage-report  - Show coverage report in terminal"
 	@echo "  coverage-html    - Generate HTML coverage report only"
-	@echo "  mcp              - Start the MCP server (requires COCALC_API_KEY, COCALC_PROJECT_ID, and COCALC_HOST)"
+	@echo "  mcp              - Start the MCP server (requires COCALC_API_KEY)"
+	@echo "  mcp-debug        - Debug the running MCP server and show tools/resources"
 	@echo "  serve-docs       - Serve documentation locally"
 	@echo "  build-docs       - Build documentation"
 	@echo "  publish          - Build and publish package"
@@ -51,6 +52,9 @@ coverage-html:
 mcp:
 	uv run cocalc-mcp-server
 
+mcp-debug:
+	uv run cocalc-mcp-debug
+
 serve-docs:
 	uv run mkdocs serve
 

src/python/cocalc-api/pyproject.toml

@@ -21,6 +21,7 @@ Issues = "https://github.com/sagemathinc/cocalc/issues"
 
 [project.scripts]
 cocalc-mcp-server = "cocalc_api.mcp.server:main"
+cocalc-mcp-debug = "cocalc_api.mcp.mcp_debug:main"
 
 [tool.mypy]
 python_version = "3.13"

src/python/cocalc-api/src/cocalc_api/api_types.py

@@ -5,6 +5,12 @@ class PingResponse(TypedDict):
     now: int
 
 
+class TestResponse(TypedDict, total=False):
+    account_id: Optional[str]
+    project_id: Optional[str]
+    server_time: int
+
+
 class ExecuteCodeOutput(TypedDict):
     stdout: str
     stderr: str

src/python/cocalc-api/src/cocalc_api/hub.py

@@ -1,7 +1,7 @@
 import httpx
 from typing import Any, Literal, Optional
 from .util import api_method, handle_error
-from .api_types import PingResponse, UserSearchResult, MessageType
+from .api_types import PingResponse, TestResponse, UserSearchResult, MessageType
 from .org import Organizations
 
 
@@ -83,6 +83,19 @@ def ping(self) -> PingResponse:
         """
         raise NotImplementedError
 
+    @api_method("system.test")
+    def test(self) -> TestResponse:
+        """
+        Test the API key and get its scope information.
+
+        Returns:
+            TestResponse: JSON object containing:
+                - account_id (if account-scoped key)
+                - project_id (if project-scoped key)
+                - server_time (current server time in milliseconds since epoch)
+        """
+        raise NotImplementedError
+
     def get_names(self, account_ids: list[str]) -> list[str]:
         """
         Get the displayed names of CoCalc accounts with given IDs.