Skip to main content
Glama
ZhaoDay

stu-management-mcp

by ZhaoDay
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

学生管理 MCP

stuManagementMcp 是一个基于 TypeScript 和 npm 的本地 stdio MCP 服务，提供平均分计算、成绩评价和学生姓名查询工具。

环境要求

  • Node.js 22 或更高版本

  • npm

Related MCP server: mcp-poc

安装与构建

在项目目录执行：

npm install
npm run build

构建后的服务入口为 dist/index.js。

使用 MCP Inspector 测试

先构建项目，再启动 Inspector：

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

浏览器打开命令输出的 Inspector 地址，在 Tools 页面选择工具并填写参数。调试信息使用 console.error 输出，可在 Inspector 右侧的 Console 标签中查看。

注意：stdio MCP 的标准输出用于 MCP 协议通信，不要使用 console.log 打印调试信息，否则可能导致协议通信异常。

工具列表

calculate_average

计算三个数值的平均值。

输入：

{
  "a": 1,
  "b": 2,
  "c": 3
}

输出：

{
  "average": 2
}

evaluate_score

根据 0-100 的整数分数返回成绩评价。非整数或超出范围的输入会被拒绝。

输入：

{
  "score": 85
}

输出：

{
  "result": "良好"
}

评价规则：

分数范围

评价

0-59

不及格

60-70

及格

71-89

良好

90-100

优秀

get_student_name

根据固定学号查询学生姓名。

学号

姓名

10000

张三

10001

李四

10002

王五

10003

赵六

10004

钱七

输入：

{
  "studentId": 10001
}

输出：

{
  "name": "李四"
}

未找到学号时，工具返回“未找到该用户”。

get_joke

从公开接口获取笑话。type 可选值为 random（随机笑话）、cold（冷笑话）和 duanzi（段子）。

输入：

{
  "type": "cold"
}

输出中的 joke 保留上游笑话接口返回的原始 JSON 内容。接口访问失败时，工具返回“获取笑话失败”。

get_call_logs_by_date

查询某一天的调用日志。date 必填，格式为 YYYY-MM-DD；可选 keyword 在整条日志中模糊匹配；可选 success 用于筛选成功或失败的调用。结果按时间倒序返回，最多 100 条。

{
  "date": "2026-08-12",
  "keyword": "get_student_name",
  "success": true
}

get_call_logs_by_range

查询闭区间日期范围内的调用日志。startDate 和 endDate 必填，格式均为 YYYY-MM-DD；其余筛选参数与单日查询相同。开始日期不能晚于结束日期。

{
  "startDate": "2026-08-11",
  "endDate": "2026-08-12",
  "success": false
}

调用埋点日志

每次进入工具业务处理的调用都会追加记录到：

log/YYYY-MM-DD/calls.jsonl

日期和时间使用中国大陆时区（Asia/Shanghai），时间格式为 YYYY-MM-DD HH:mm:ss.SSS。每行是一条独立 JSON 记录，包含工具名、调用参数、成功状态、错误信息和耗时（毫秒）。

示例：

{"timestamp":"2026-08-11 22:42:07.014","tool":"calculate_average","parameters":{"a":2,"b":3,"c":5},"success":true,"durationMs":20.01}

参数 schema 校验失败的请求不会进入业务代码，因此不会写入埋点日志。日志写入失败不会影响工具的正常返回。

宿舍规则知识库

知识库源文档为 docs/601宿舍管理规则.md，分块逻辑位于 src/rag/：优先按 Markdown 标题拆分，过长内容再按约 500 个字符均匀分块，并保留约 80 个字符的重叠上下文。

本版本使用本地关键词检索，不依赖 Docker、Python、ChromaDB 或 embedding 模型。索引数据保存为 src/db/dorm-rules-index.json。先调用 index_dorm_rules 将文档写入知识库；成功时返回分块数量。之后调用 search_dorm_rules 并传入问题：

{
  "query": "周五晚上需要熄灯吗？"
}

检索会提取问题中的中文词语、中文双字词和英文单词，在分块内容中进行匹配并按命中次数排序。后续可在不影响现有工具的前提下新增语义 embedding 检索工具。

在 CC Switch 中配置 stdio MCP

在 CC Switch 新增 MCP 页面中：

  • MCP 标题：stuManagementMcp

  • 显示名称：学生管理 MCP

  • 启用到应用：勾选 Codex

在“完整的 JSON 配置”中填写：

{
  "type": "stdio",
  "command": "D:\\Program Files (x86)\\coding\\nodejs\\node.exe",
  "args": [
    "D:\\workspace\\mcp\\dist\\index.js"
  ]
}

添加配置后，完全退出并重启 Codex Desktop。之后直接使用自然语言请求调用工具，例如“调用 get_student_name 查询 studentId=10001”。修改 src/index.ts 后，需要再次执行 npm run build，然后重启 Codex Desktop 以加载新的构建产物。

Available Tools

3 tools
calculate_average计算A

计算三个数值的平均值

ParametersJSON Schema
NameRequiredDescriptionDefault
aYes
bYes
cYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
averageYes

TDQS

A4.1/5.0
Behavior4/5

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

Given there are no annotations, the description carries the burden of transparency. It declares the core behavior (computing an average) and, being a pure calculation with no side effects, nothing more is required. The existence of an output schema covers return format, so the description is sufficiently 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, concise sentence that immediately states the tool's purpose. It contains no filler words or redundant details, making it optimally front-loaded and easy to scan.

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 a simple, deterministic calculation, the description, combined with the input schema (which defines the three number parameters) and the presence of an output schema, is fully complete. There are no hidden prerequisites, side effects, or complex behaviors that require additional explanation.

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

Parameters3/5

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

The input schema has no descriptions for a, b, c, and the description only states that they are 'three numerical values.' This adds little beyond the 'number' type already present in the schema, but since the average is order-invariant, not distinguishing parameters is acceptable. The description provides minimal compensation for the 0% schema coverage.

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 ('计算' / calculate) and identifies the exact resource ('三个数值的平均值' / average of three values), clearly distinguishing it from sibling tools like evaluate_score and get_student_name. It precisely states the tool's function 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 Guidelines3/5

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

The description implies usage (when you need to average three numbers) but provides no explicit guidance on when to prefer this tool over alternatives, nor any exclusions. The intended use is obvious from the purpose, but this dimension requires more explicit context for a higher score.

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

evaluate_score成绩评价B

根据 0 至 100 的整数分数返回成绩评价

ParametersJSON Schema
NameRequiredDescriptionDefault
scoreYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. However, it only restates that a score yields a grade evaluation, omitting details such as the grading scale (e.g., letter grades, pass/fail), output format, or error handling for out-of-range inputs. It adds little beyond the tool's name.

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, compact sentence that immediately conveys the tool's operation. It contains no filler or redundant phrases, making it highly concise and front-loaded with the essential information.

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

Completeness3/5

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

For a simple tool with one parameter and a provided output schema, the description is minimally adequate. It states the core purpose clearly but omits specific details about the returned grade evaluation (e.g., possible values or criteria). The existence of an output schema lessens the need to explain return values, so this is a borderline acceptable level of completeness.

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

Parameters2/5

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

The schema has zero description coverage for the 'score' property. The description repeats the 0-100 integer range already present in the schema but does not elaborate on what the score represents or how it maps to evaluations. Since there is only one parameter and the description adds no new semantic context, it fails to compensate for the schema's lack of description.

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 that the tool returns a grade evaluation based on an integer score from 0 to 100. It uses a specific verb (returns) and resource (grade evaluation), and this purpose distinguishes it from sibling tools like calculate_average and get_student_name.

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?

The description provides no guidance on when to use this tool versus calculate_average or get_student_name. It simply states the tool's function without mentioning alternatives, exclusions, or contextual triggers, leaving the agent to infer usage from the tool name alone.

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

get_student_name查询用户姓名B

根据固定学号查询用户姓名

ParametersJSON Schema
NameRequiredDescriptionDefault
studentIdYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It does not explicitly state that this is a read-only operation, nor does it mention possible errors (e.g., student not found) or any restrictions implied by '固定学号'. The lack of detail leaves behavioral traits opaque.

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 immediately conveys the purpose. There is no redundancy or extraneous information, and the key information is front-loaded.

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

Completeness3/5

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

For a simple lookup tool with an output schema, the description provides the basic purpose. However, the ambiguous phrase '固定学号' could confuse the agent about whether the ID is hardcoded or a parameter. Missing usage context and error behavior make it only minimally viable for the tool's simplicity.

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

Parameters2/5

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

Schema coverage is 0%, so the description must compensate by explaining the parameter. However, it only mentions '学号' (student ID) in passing without clarifying format, range, or acceptable values. This adds minimal meaning beyond the parameter name 'studentId' already visible in the schema.

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 (查询/query) and resource (用户姓名/user name), with the qualifier 根据固定学号 (based on fixed student ID). This distinguishes it from sibling tools like calculate_average and evaluate_score, which are calculation-oriented.

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 given about when to use this tool versus the siblings. There is no mention of exclusions, prerequisites, or alternative tools. The usage context is only implied by the tool's obvious purpose, but no explicit guidance is provided.

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 observedcalculate_average
    • First observedevaluate_score
    • First observedget_student_name
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: one computes an average, one evaluates a score, and one retrieves a student name. There is no overlap in functionality, so an agent can easily differentiate them.

Naming Consistency5/5

All tool names follow the same snake_case verb_noun pattern: calculate_average, evaluate_score, get_student_name. This consistency makes the set predictable and easy to navigate.

Tool Count4/5

With only 3 tools, the set is relatively small but not unreasonably thin for a focused utility server. However, given the 'student management' label, the count feels slightly sparse, though still within a reasonable range.

Completeness2/5

The tools do not form a coherent student management surface. Only get_student_name pertains to students, while the other two are generic utilities. Missing are typical student CRUD operations, so an agent cannot perform meaningful management workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • ai-mcp

    wangyj641
    F
    license
    A
    quality
    D
    maintenance
    Lightweight MCP server that exposes tools for system information and weather lookup, designed for agent integration via stdio.
    1
    -

  • mcp-poc

    RenoLu
    A
    license
    Not graded
    quality
    D
    maintenance
    A minimal MCP server with four tools (add, greet, text_stats, divide) demonstrating typed parameters, structured outputs, and error handling over stdio transport.
    MIT

  • MCP Demo

    VictorC55
    F
    license
    Not graded
    quality
    C
    maintenance
    A model-agnostic MCP server exposing example tools (add1, multiply2, greet) for learning purposes, working with any LLM through stdio transport.
    -

  • MPC-PoC-1

    mzoffoli85
    F
    license
    A
    quality
    C
    maintenance
    A learning-oriented MCP server that exposes basic tools (echo, add, reverse) over stdio transport to validate MCP handshake and tool calls.
    3
    -