Tianji MCP Server: Website Analytics, Uptime, Status

Overview

Tianji MCP Server is a lightweight Model Context Protocol (MCP) adapter that lets AI assistants and other MCP-aware tools interact with a Tianji instance. It bridges the MCP protocol to the Tianji platform API so assistants can query survey data, fetch detailed survey metadata, and enumerate workspace surveys in real time.

While its primary focus is survey access, the MCP server is commonly used as part of broader observability and analytics workflows: embedding survey-driven feedback into assistant responses, surface analytics and uptime summaries stored in Tianji, or trigger alerts based on survey-derived signals. The server runs as a standalone process (stdio) and exposes a small set of MCP tools that map to Tianji API endpoints.

Features

• Exposes Tianji workspace surveys to MCP clients (AI assistants, agents).
• Query survey results (aggregations, raw responses).
• Fetch detailed survey metadata and question definitions.
• List all surveys accessible in a configured workspace.
• Simple stdio-based MCP server for easy local or containerized deployment.
• Environment-driven configuration for CI/CD and container workflows.

Installation / Configuration

Prerequisites:

• Node.js / npx installed (for the npx example)
• Tianji API credentials (base URL, API key, workspace ID)

Example: run via npx (recommended for dev / quick start)

# Run MCP server locally using npx
TIANJI_BASE_URL="https://tianji.example.com" \
TIANJI_API_KEY="your_api_key" \
TIANJI_WORKSPACE_ID="your_workspace_id" \
npx -y tianji-mcp-server

Example: run inside a container using the official Node image (runs npx inside a container)

docker run --rm \
  -e TIANJI_BASE_URL="https://tianji.example.com" \
  -e TIANJI_API_KEY="your_api_key" \
  -e TIANJI_WORKSPACE_ID="your_workspace_id" \
  node:18 \
  npx -y tianji-mcp-server

MCP client configuration snippet (example JSON to register the server as an MCP stdio server):

{
  "mcpServers": {
    "tianji": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tianji-mcp-server"],
      "env": {
        "TIANJI_BASE_URL": "https://tianji.example.com",
        "TIANJI_API_KEY": "<your-api-key>",
        "TIANJI_WORKSPACE_ID": "<your-workspace-id>"
      }
    }
  }
}

Environment variables

Available Tools / Resources

The MCP server exposes a small set of tools (MCP calls) that map to Tianji functionality. Typical tool names and payloads:

• listSurveys

  • Purpose: return a paginated list of surveys in the configured workspace.
  • Request: { “page”: 1, “limit”: 50 }
  • Response: { “surveys”: [ { “id”, “title”, “status”, “createdAt” } ], “total” }

• getSurvey

  • Purpose: fetch detailed metadata (questions, settings) for a specific survey.
  • Request: { “surveyId”: “abc123” }
  • Response: { “id”, “title”, “questions”: [ … ], “settings”: { … } }

• querySurveyResults

  • Purpose: retrieve aggregated or raw responses for a survey; supports filters and time ranges.
  • Request: { “surveyId”: “abc123”, “from”: “2025-01-01”, “to”: “2025-01-31”, “aggregate”: true }
  • Response: { “aggregations”: { … }, “rows”: [ … ] }

These tools are intended for consumption by MCP-aware agents or custom integrations. The exact request/response shapes can be discovered by examining the MCP tool manifests returned when the server initializes.

Use Cases

1. Summarize customer feedback inside an assistant

   • An AI assistant can call querySurveyResults for recent feedback surveys and produce a short summary: top themes, sentiment, and recommended actions.

2. Combine survey signals with uptime/analytics dashboards

   • Use Tianji survey responses as qualitative context alongside quantitative uptime/analytics (e.g., map a spike in error reports to survey complaints). The MCP server provides the survey side of that integration for assistants that coordinate alerts.

3. Automate alerting workflows

   • An automated agent can periodically call listSurveys and querySurveyResults to detect sudden shifts in responses and trigger notifications (Slack, email,