Skip to main content
Glama
jpsiddharth2008

MyAmrita_MCP

by jpsiddharth2008
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

Amrita AI Assistant

A personal MCP server that lets an AI assistant (Claude, ChatGPT, etc.) read data from the Amrita Vishwa Vidyapeetham student portal (students.amrita.edu) on your behalf — attendance, timetable, marks, and more — using your own logged-in session.

Built on NitroStack (typescript-starter template).

What This Includes

  • auth module — captures and persists a Microsoft SSO-backed portal session

  • attendance module — attendance_get_attendance, attendance_get_low_attendance_subjects

  • More modules tracked as issues on this repo, built one at a time

Related MCP server: hello-mcp

Setup

npm install
cp .env.example .env

Generate a real value for SESSION_ENCRYPTION_KEY in .env:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Logging In

The portal's login is federated through Microsoft Entra ID (Microsoft SSO) — there's no username/password form to automate directly, and the MCP client host (e.g. NitroStudio) often can't display a browser window itself. So logging in is a two-step, semi-manual process:

1. Launch a debuggable browser yourself, in your own terminal:

"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\amrita-edge-profile"

Leave that Edge window open.

2. Call the auth_login tool (from NitroStudio, or any MCP client connected to this server). It connects to that already-open browser, navigates it to the Amrita SSO login page, and waits (up to 5 minutes) for you to sign in yourself — including any MFA step. Once you land back on the portal dashboard, the resulting session is captured and persisted (encrypted, to .amrita-session.enc) so every other tool reuses it automatically until the portal session itself expires. Re-run auth_login (with the Edge window open again) whenever auth_status reports authenticated: false.

auth_logout clears the locally stored session.

Common Commands

npm run dev     # start in development mode (STDIO transport)
npm run build   # compile TypeScript + bundle widgets
npm start       # build and run the production server

Testing with NitroStudio

NitroStudio is the recommended way to inspect and manually test tools during development: open it, point it at this project folder, and use the Tools page to execute tools, inspect input schemas, and view JSON output.

Manual auth test script

scripts/manual-auth-test.mjs connects to the built server directly over stdio with a generous per-call timeout, useful for testing auth_login end-to-end outside of NitroStudio:

npm run build
node scripts/manual-auth-test.mjs

Links

Available Tools

3 tools
auth_loginA

Open a real browser window for the user to log in to the Amrita student portal via Microsoft SSO. Only call this after the user has explicitly asked to log in or re-authenticate — it opens a visible browser window and blocks until the user finishes signing in themselves (or times out after 5 minutes). Once logged in, the session is reused automatically by every other tool until it expires.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that a visible browser window opens, the tool blocks until the user finishes or times out after 5 minutes, and that the session is reused by other tools until expiration.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it starts with the core action, then specifies the only valid invocation condition, then explains behavioral outcomes. Every sentence contributes meaningful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an interactive login tool with no parameters and no output schema, the description covers the necessary context: when to call it, what the user sees, blocking/timeout behavior, and session reuse. Nothing essential is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema coverage is 100% vacuously. The description adds no parameter-specific detail, but none is needed. Baseline 4 is appropriate for a zero-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Open a real browser window'), the target resource ('Amrita student portal via Microsoft SSO'), and the purpose (user login). This distinguishes it from the sibling tools auth_status and auth_logout.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the tool ('Only call this after the user has explicitly asked to log in or re-authenticate') and describes the blocking behavior and timeout. However, it does not mention the alternative sibling tools or when to prefer auth_status or auth_logout.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

auth_logoutA

Clear the locally stored Amrita portal session.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose that the session is cleared locally, which is a meaningful scope qualifier. However, it does not mention whether the server-side session is affected, token invalidation, or any post-condition, leaving some behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that gets straight to the point with no redundant wording. It is perfectly sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a zero-parameter action with no output schema, the description is nearly complete. It clearly states the purpose and local scope, though it lacks explicit guidance on when to invoke it relative to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema description coverage is 100%, so there is nothing the description needs to explain. Baseline for zero-parameter tools is 4, and this is met.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Clear') and a specific resource ('locally stored Amrita portal session'), making the tool's function unambiguous. It clearly indicates a logout operation and is naturally distinguishable from its siblings auth_status and auth_login.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus auth_status or auth_login. The description simply states what it does without any context about typical invocation scenarios or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

auth_statusA

Check whether there is currently a valid, active session with the Amrita student portal.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It accurately conveys that the tool performs a non-mutating status check, but it does not describe the return format or behavior when the session is missing or expired. This is adequate for a simple status probe but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that states the tool's purpose clearly with no unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter status check, the description covers the essential semantics. It implicitly suggests a boolean-style result via 'whether', but because no output schema exists, an explicit statement of the return value or possible states would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema provides complete coverage, so no parameter-level explanation is needed. The baseline of 4 applies because there is nothing for the description to add.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks for a valid, active session with the named portal. The verb 'Check' and the specific resource distinguish it from the sibling login/logout tools without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given about when to call this tool versus auth_login or auth_logout. The intended context is implied by the name and sibling list, but the description itself offers no conditions, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedauth_login
    • First observedauth_logout
    • First observedauth_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool covers a distinct lifecycle step: status checks the session, login initiates it, and logout terminates it. There is no semantic overlap or ambiguity between the three tools.

Naming Consistency4/5

All tools share the auth_ prefix and use snake_case, so the naming is mostly consistent. However, auth_status is a noun-like command while auth_login and auth_logout are verb-like, so a name like get_auth_status would be more uniform.

Tool Count4/5

Three tools is a reasonable size for an authentication submodule, and each tool earns its place. Given the server name MyAmrita_MCP, the count feels slightly under-scoped if the server is intended to cover the full student portal experience.

Completeness2/5

The authentication lifecycle itself is complete, but there are no tools to access or act on any Amrita portal data. Since the descriptions imply the session is meant to be reused by other tools, the absence of any portal-facing tools creates significant gaps that will cause agent failures.

Maintenance

ActivityMaintained
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers