Connect Operto Teams to Claude

mkdir operto-teams-mcp
cd operto-teams-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

{
  "name": "operto-teams-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  }
}

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const API_KEY = process.env.OPERTO_TEAMS_API_KEY;
const API_VALUE = process.env.OPERTO_TEAMS_API_VALUE;
const BASE_URL = "https://teams-api.operto.com";

if (!API_KEY || !API_VALUE) {
  console.error("Missing OPERTO_TEAMS_API_KEY or OPERTO_TEAMS_API_VALUE");
  process.exit(1);
}

// --- Auth: exchange the key pair for a bearer token, re-login near expiry ---
let cachedToken = null;
let tokenFetchedAt = 0;

async function getToken() {
  // Access tokens last 1 hour; re-login after 50 minutes to be safe.
  if (cachedToken && Date.now() - tokenFetchedAt < 50 * 60 * 1000) {
    return cachedToken;
  }
  const response = await fetch(`${BASE_URL}/api/v1/oauth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ API_Key: API_KEY, API_Value: API_VALUE }),
  });
  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Operto Teams login failed ${response.status}: ${body}`);
  }
  const data = await response.json();
  cachedToken = data?.Access_Token?.token;
  if (!cachedToken) {
    throw new Error(
      `Login succeeded but no Access_Token.token in response: ${JSON.stringify(data)}`
    );
  }
  tokenFetchedAt = Date.now();
  return cachedToken;
}

async function opertoGet(path, params = {}) {
  const token = await getToken();
  const url = new URL(`${BASE_URL}${path}`);
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined && value !== null && value !== "") {
      url.searchParams.append(key, String(value));
    }
  }
  const response = await fetch(url.toString(), {
    method: "GET",
    headers: {
      Authorization: `VRS ${token}`,
      Accept: "application/json",
      "User-Agent": "rapideye-operto-teams-mcp/1.0",
    },
  });
  if (response.status === 429) {
    throw new Error(
      "Operto Teams rate limit hit (50 requests per 2 minutes). Wait before retrying."
    );
  }
  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Operto Teams API ${response.status}: ${body}`);
  }
  return response.json();
}

const asText = (data) => ({
  content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
});

const server = new McpServer({
  name: "operto-teams",
  version: "1.0.0",
});

// Tool 1: Properties
server.tool(
  "list-properties",
  "List properties in Operto Teams. Returns property IDs, names, and settings. Use this first to map PropertyIDs for other queries.",
  {},
  async () => asText(await opertoGet("/api/v1/properties"))
);

// Tool 2: Tasks (the workhorse)
server.tool(
  "list-tasks",
  "List tasks (cleans, inspections, maintenance) with optional filters. Each task includes TaskID, PropertyID, TaskName, TaskDate, Completed/Approved flags, assigned Staff, and a TaskImages array. Rate limit is 50 requests per 2 minutes, so prefer date-bounded queries over paging through everything.",
  {
    PropertyID: z.string().optional().describe("Filter to one property"),
    Completed: z.string().optional().describe("1 for completed tasks, 0 for not completed"),
    TaskStartDate: z.string().optional().describe("Earliest task date, YYYY-MM-DD"),
    TaskEndDate: z.string().optional().describe("Latest task date, YYYY-MM-DD"),
    CompletedStartDate: z.string().optional().describe("Earliest completion date, YYYY-MM-DD"),
    CompletedEndDate: z.string().optional().describe("Latest completion date, YYYY-MM-DD"),
    per_page: z.string().optional().describe("Results per page"),
    page: z.string().optional().describe("Page number"),
  },
  async (params) => asText(await opertoGet("/api/v1/tasks", params))
);

// Tool 3: Single task
server.tool(
  "get-task",
  "Fetch one task by TaskID, including its TaskImages array and assigned staff.",
  { TaskID: z.string().describe("Task ID from list-tasks") },
  async ({ TaskID }) => asText(await opertoGet(`/api/v1/tasks/${TaskID}`))
);

// Tool 4: Task form elements (the checklist)
server.tool(
  "get-task-form-elements",
  "Fetch the checklist (Task Form) elements for a task. Useful for reviewing what the checklist asked and what staff recorded. Note: the public API does not expose checklist video; video captured in Operto Teams stays in the platform.",
  { TaskID: z.string().describe("Task ID from list-tasks") },
  async ({ TaskID }) =>
    asText(await opertoGet(`/api/v1/tasks/${TaskID}/formElements`))
);

// Tool 5: Staff task assignments and hours
server.tool(
  "list-staff-tasks",
  "List staff task assignments with optional filters. Cross-reference with list-tasks for workload and completion analysis.",
  {
    StaffID: z.string().optional().describe("Filter to one staff member"),
    PropertyID: z.string().optional().describe("Filter to one property"),
    Completed: z.string().optional().describe("1 for completed, 0 for not completed"),
    TaskStartDate: z.string().optional().describe("Earliest task date, YYYY-MM-DD"),
    TaskEndDate: z.string().optional().describe("Latest task date, YYYY-MM-DD"),
    per_page: z.string().optional().describe("Results per page"),
    page: z.string().optional().describe("Page number"),
  },
  async (params) => asText(await opertoGet("/api/v1/stafftasks", params))
);

// Tool 6: Issues
server.tool(
  "list-issues",
  "List reported issues (damage, maintenance, missing items) logged by staff.",
  {},
  async () => asText(await opertoGet("/api/v1/issues"))
);

const transport = new StdioServerTransport();
await server.connect(transport);

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "operto-teams": {
      "command": "node",
      "args": ["/absolute/path/to/operto-teams-mcp/index.js"],
      "env": {
        "OPERTO_TEAMS_API_KEY": "your_api_key_here",
        "OPERTO_TEAMS_API_VALUE": "your_api_value_here"
      }
    }
  }
}