OPlatformStudentMCP by dev-zeromoblt - MCP Server

OPlatform Student MCP Server

MCP (Model Context Protocol) server for querying the Student API with Redis FT.SEARCH capabilities, including geo-radius queries.

Features

Get Student by ID: Retrieve complete student details using their unique Zrn identifier
Advanced Search: Redis FT.SEARCH powered queries with support for:
- Full-text search on names and addresses
- Tag-based filtering (status, grade, subscription, gender, campus)
- Geo-radius queries (find students within X km/mi of a location)
- Complex boolean queries with AND/OR operators
- Pagination support

Architecture

┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
│   Claude    │◄────►│  Student MCP     │◄────►│  Student API    │
│   Desktop   │ stdio│  Server          │ HTTP │  (Redis Search) │
└─────────────┘      └──────────────────┘      └─────────────────┘
                            │
                            ▼
                     ┌─────────────┐
                     │ Smithy Gen  │
                     │ TypeScript  │
                     │ Models      │
                     └─────────────┘

Prerequisites

Node.js >= 18
TypeScript
Access to Student API endpoint
Valid JWT authentication token

Local Development Setup

1. Build Smithy Models and Install Dependencies

The project uses Smithy-generated TypeScript models packaged as a local tarball dependency.

Option A: Use the automated build script (Recommended)

cd /Users/zeroman/workplace/nowzone/OPlatformStudentMCP
./build-with-models.sh

This script will:

Build the Smithy models from OPlatformModels
Pack them as a tarball
Copy the tarball to src/generated/
Install all dependencies (including the packaged model)
Build the TypeScript project

Option B: Manual steps

cd /Users/zeroman/workplace/nowzone/OPlatformStudentMCP

# Build and package Smithy models
npm run model

# Build the project
npm run build

3. Set Environment Variables

Create a .env file or export variables:

export STUDENT_API_ENDPOINT="https://api.zeromoblt.com"
export STUDENT_API_AUTH_TOKEN="your-jwt-token-here"

4. Test Locally with Claude Desktop

Create or update ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "student-search": {
      "command": "node",
      "args": ["/Users/zeroman/workplace/nowzone/OPlatformStudentMCP/dist/index.js"],
      "env": {
        "STUDENT_API_ENDPOINT": "https://api.zeromoblt.com",
        "STUDENT_API_AUTH_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server.

Quick Token Update (macOS):

Update your token quickly when it expires:

# 1. Copy JWT token from browser to clipboard
# 2. Run the update script
npm run update-token
# or: yarn update-token

# 3. Restart Claude Desktop

This automatically updates your Claude Desktop config with the token from clipboard. See for details.

Usage Examples

Get Student by ID

"Get student with ID ZST12345"

The MCP server will call:

{
  "tool": "get_student",
  "arguments": {
    "id": "ZST12345"
  }
}

Search Examples

Find all active students:

"Search for all active students"

→ Query: @status:{ACTIVE}

Find students by name:

"Find students named Basavaraju"

→ Query: @name:Basavaraju

Find students in a specific grade:

"Find all students in class 10 or class 11"

→ Query: @grade:{CLASS_10|CLASS_11}

Geo-radius search:

"Find students named Kumar within 5km of Empire State Building (40.748817, -73.985428)"

→ Query: @name:Kumar with lat=40.748817, lng=-73.985428, radius=5, unit=km

Complex queries:

"Find active class 12 students at campus ZCA00123"

→ Query: @status:{ACTIVE} @grade:{CLASS_12} @campusId:{ZCA00123}

Redis Search Query Syntax

TEXT Fields (full-text search)

@name:Basavaraju - Contains "Basavaraju"
@givenName:Raj* - Starts with "Raj"
@familyName:"Kumar Singh" - Exact phrase

TAG Fields (exact match)

@status:{ACTIVE} - Single value
@status:{ACTIVE|PENDING_DUES} - OR condition
@grade:{CLASS_11|CLASS_12} - Multiple values

Available Fields

TEXT: name, givenName, familyName, middleName, geoAddress

TAG: status, grade, subscription, gender, campusId, primaryParentId, secondaryParentId

GEO: location (use with longitude, latitude, radius parameters)

NUMERIC: birthdate, startDate, updatedAt

Operators

* - Wildcard
| - OR (within tags)
- - NOT
() - Grouping

See src/schemas/redis-schema.txt for complete reference.

Docker Build

Important: Before building the Docker image, you must build and pack the Smithy models:

cd /Users/zeroman/workplace/nowzone/OPlatformStudentMCP

# Build and pack models
npm run model

# Build Docker image
docker build -t student-mcp:latest .

The Dockerfile expects src/generated/smithy-o-platform-client.tgz to exist before the build.

Kubernetes Deployment

Prerequisites

Configure Pulumi secrets:

cd /Users/zeroman/workplace/nowzone/now-zeromoblt
pulumi config set studentApiEndpoint https://api.zeromoblt.com
pulumi config set --secret studentApiAuthToken "your-jwt-token"

Import deployment in index.ts:

import "./deployments/student-mcp";

Deploy:

pulumi up

View Logs

kubectl logs -n student-mcp-dev -l app=student-mcp-server -f

Project Structure

OPlatformStudentMCP/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── client/
│   │   └── apiClient.ts      # Student API HTTP client
│   ├── tools/
│   │   ├── getStudent.ts     # Get student by ID tool
│   │   └── searchStudents.ts # Search students tool
│   └── schemas/
│       └── redis-schema.txt  # Redis search documentation
├── package.json
├── tsconfig.json
├── Dockerfile
└── README.md

Environment Variables

Variable	Required	Description
`STUDENT_API_ENDPOINT`	Yes	Student API base URL
`STUDENT_API_AUTH_TOKEN`	No	Default JWT authentication token (can be overridden per-request)

Authentication

The server supports two authentication modes:

Per-Request Token (Recommended): Pass authToken parameter with each tool call
- Allows dynamic token refresh
- More secure (token not hardcoded)
- Example: { "id": "ZST123", "authToken": "eyJ..." }
Default Environment Token: Set STUDENT_API_AUTH_TOKEN environment variable
- Used when no token provided in request
- Simpler for single-user scenarios

See for detailed authentication guide.

API Reference

Tools

`get_student`

Retrieve a student by their unique Zrn identifier.

Input:

{
  id: string  // Zrn format: Z[A-Z]{2}[0-9]{5,10}
}

Output: Full student object with all fields from Smithy model.

`search_students`

Search students using Redis FT.SEARCH syntax.

Input:

{
  query: string,          // Required: Redis FT.SEARCH query
  offset?: number,        // Pagination offset
  limit?: number,         // Results per page (max 100)
  longitude?: number,     // Geo search: center longitude
  latitude?: number,      // Geo search: center latitude
  radius?: number,        // Geo search: radius distance
  unit?: "km" | "mi"      // Geo search: distance unit
}

Output:

{
  students: StudentDetails[],
  total: number
}

Testing Queries

You can ask Claude questions like:

"How many active students are there?"
"Find all class 12 students at campus ZCA00123"
"Show me students within 10km of coordinates (17.367737, 78.563020)"
"List students with pending dues"
"Find students named Kumar in grades 11 or 12"

Troubleshooting

MCP Server Not Connecting

Check Claude Desktop config path
Verify environment variables are set
Check logs: tail -f ~/Library/Logs/Claude/mcp*.log

Authentication Errors

Verify JWT token is valid and not expired
Check token has proper permissions for Student API

Build Errors

"Cannot find module '@smithy/o-platform-client'": Run npm run model to build and pack the Smithy models
Missing tarball in Docker build: Run npm run model before docker build
OPlatformModels build fails: Ensure Smithy models compile: cd ../OPlatformModels && ./gradlew clean build

Development

Watch Mode

npm run watch

Run Locally

npm run dev

License

MIT

Contributing

Generated from Smithy model at /Users/zeroman/workplace/nowzone/OPlatformModels/models/student.smithy