Skip to main content
Glama
sweetwisdom

MCP Project Query Server

by sweetwisdom

MCP Project Query Server

一个基于 Model Context Protocol (MCP) 的项目查询服务器,采用 TypeScript 开发,具有 Spring Boot 风格的目录结构。

项目结构

mcp-demo/
├── src/
│   ├── main/
│   │   ├── controllers/     # 控制器层 - 处理MCP工具调用
│   │   │   ├── ProjectController.ts
│   │   │   └── WallpaperController.ts
│   │   ├── services/        # 服务层 - 业务逻辑处理
│   │   │   ├── ProjectService.ts
│   │   │   └── WallpaperService.ts
│   │   ├── repositories/    # 数据访问层 - 数据持久化
│   │   │   └── ProjectRepository.ts
│   │   ├── models/          # 数据模型 - 接口定义
│   │   │   └── Project.ts
│   │   ├── config/          # 配置类
│   │   │   └── AppConfig.ts
│   │   └── index.ts         # 主入口文件
│   └── resources/           # 资源文件
│       └── projects.json    # 项目数据
├── dist/                    # 构建输出目录
├── package.json
├── rollup.config.mjs
└── tsconfig.json

Related MCP server: Project Tracker MCP Server

功能特性

项目管理功能

  • get_project_info: 根据项目名称查询项目信息

  • get_project_count: 获取项目总数

  • get_project_all: 获取所有项目列表

  • add_project: 新增项目

壁纸功能

  • get_random_wallpaper: 从 Bing 壁纸获取随机壁纸

开发指南

安装依赖

npm install

开发模式

npm run dev

构建项目

npm run build

启动服务

npm start

构建输出

构建完成后,dist 目录将包含:

dist/
├── index.js              # 统一的 CommonJS 入口文件
└── resources/            # 复制的资源文件
    └── projects.json     # 项目数据文件

架构设计

本项目采用分层架构设计,参考 Spring Boot 的目录结构:

  1. Controller 层: 负责处理 MCP 工具调用,参数验证和响应格式化

  2. Service 层: 包含业务逻辑,处理具体的业务需求

  3. Repository 层: 负责数据访问和持久化

  4. Model 层: 定义数据结构和接口

  5. Config 层: 管理应用配置

这种设计提供了良好的代码组织、可维护性和可扩展性。

技术栈

  • TypeScript: 提供类型安全和更好的开发体验

  • Rollup: 模块打包工具

  • MCP SDK: Model Context Protocol 开发工具包

  • Zod: 运行时类型验证

Available Tools

5 tools
add_projectD

新增项目

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYes

TDQS

D1.3/5.0
Behavior1/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure but fails completely. '新增项目' (add project) implies a write/mutation operation, but there's no information about permissions required, whether the operation is idempotent, what happens on failure, or what the response looks like. For a tool that creates data with multiple required parameters, this lack of behavioral context is a critical gap.

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

Conciseness2/5

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

While technically concise with just two characters, this represents under-specification rather than effective brevity. The description doesn't provide enough information to be useful, making it inefficient rather than well-structured. A single phrase without any elaboration fails to communicate necessary information about the tool's purpose and usage.

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

Completeness1/5

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

Given the complexity (5 required parameters in a nested object, no output schema, no annotations), the description is completely inadequate. It doesn't explain what the tool returns, what happens when it executes, what errors might occur, or how to interpret the parameters. For a mutation tool with significant complexity and no supporting structured data, this description provides almost no useful context.

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

Parameters1/5

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

The schema description coverage is 0%, meaning none of the 5 nested parameters (name, description, startDate, investment, progress) have descriptions in the schema. The tool description provides absolutely no information about these parameters - not what they represent, what formats are expected, or what constraints apply. For a tool with 5 required parameters, this is severely inadequate.

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

Purpose2/5

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

The description '新增项目' (add project) is a tautology that merely restates the tool name without providing any meaningful elaboration. It doesn't specify what kind of project is being added, what system it's being added to, or how it differs from sibling tools like get_project_all or get_project_info. While the verb 'add' is clear, the lack of context makes this minimally informative.

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

Usage Guidelines1/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 alternatives. There are multiple sibling tools for retrieving project information (get_project_all, get_project_info, get_project_count), but the description doesn't indicate whether this is for creating new projects versus updating existing ones, or what prerequisites might be needed. No context about appropriate use cases is provided.

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

get_project_allC

获取全部项目

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.8/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. It only states the action ('获取全部项目') without disclosing behavioral traits like pagination, sorting, filtering, rate limits, authentication needs, or what 'all' entails (e.g., archived projects). This is inadequate for a tool with zero annotation coverage.

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

Conciseness4/5

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

The description is a single, efficient phrase ('获取全部项目') that's front-loaded and wastes no words. However, it's under-specified rather than concise, as it lacks necessary details for clarity, but it's not verbose or poorly structured.

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

Completeness2/5

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

Given the complexity (a read operation with no parameters but potential behavioral nuances), no annotations, and no output schema, the description is incomplete. It doesn't explain return values, error handling, or operational constraints, leaving significant gaps for an AI agent to understand how to use it effectively.

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 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description doesn't need to add parameter details, and it correctly implies no filtering or options are available. Baseline is 4 for zero parameters, as it aligns with the schema.

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

Purpose3/5

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

The description '获取全部项目' (Get all projects) states a clear verb ('获取' - get) and resource ('项目' - projects), but it's vague about scope and doesn't differentiate from siblings like 'get_project_count' or 'get_project_info'. It's better than a tautology but lacks specificity about what '全部' (all) means in practice.

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?

There's no guidance on when to use this tool versus alternatives like 'get_project_info' (for specific project details) or 'get_project_count' (for just the number). The description implies a comprehensive retrieval, but it doesn't specify prerequisites, exclusions, or contextual usage scenarios.

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

get_project_countC

获取项目总数

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/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 full burden. '获取项目总数' only states what the tool does, not how it behaves. It doesn't disclose whether this is a cached count or real-time calculation, what permissions are required, whether it's rate-limited, what format the count is returned in (integer, string with formatting), or any error conditions. For a tool with zero annotation coverage, this is insufficient behavioral disclosure.

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 extremely concise - just three Chinese characters that directly state the tool's function. There's zero waste or unnecessary elaboration. For a simple count retrieval tool, this minimal description is appropriately sized 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.

Completeness2/5

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

Given no annotations, no output schema, and a simple but potentially ambiguous purpose relative to siblings, the description is incomplete. It doesn't explain what 'count' means (total projects? active projects?), what the return value looks like, or how this differs from 'get_project_all'. For a tool that could have various interpretations in a project management context, more context is needed.

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 0 parameters with 100% schema description coverage (empty schema). The description doesn't need to explain any parameters since none exist. The baseline for 0 parameters is 4, as there's no parameter information to provide beyond what the schema already indicates (no parameters).

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

Purpose3/5

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

The description '获取项目总数' (Get project count) states a clear verb ('获取' - get) and resource ('项目总数' - project count), which establishes the basic purpose. However, it doesn't differentiate from sibling tools like 'get_project_all' or 'get_project_info' - it's unclear if this returns just a number while others return detailed lists or information. The purpose is clear but lacks sibling differentiation.

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 alternatives. With siblings like 'get_project_all' (presumably listing all projects) and 'get_project_info' (presumably getting detailed info about specific projects), there's no indication whether this tool should be used for quick counts, summary statistics, or dashboard metrics versus the other retrieval tools.

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

get_project_infoC

根据项目名称查询项目基本信息,包括开始日期、简介、投资金额和当前进度

ParametersJSON Schema
NameRequiredDescriptionDefault
projectNameYes要查询的项目名称

TDQS

C2.9/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. It states this is a query operation ('查询'), implying it's likely read-only and non-destructive, but doesn't explicitly confirm safety aspects like permissions, rate limits, or error handling. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior beyond basic functionality.

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

Conciseness4/5

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

The description is a single, efficient sentence that front-loads the core purpose and lists returned fields. There's no wasted text, and it's appropriately sized for a simple query tool. However, it could be slightly more structured by separating purpose from returned data for better readability.

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?

Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally adequate. It covers what the tool does and what it returns, but lacks details on behavioral traits, usage context, and error handling. Without annotations or output schema, the agent has incomplete information for reliable invocation.

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 description adds minimal value beyond the input schema, which has 100% coverage. It mentions '根据项目名称' (based on project name), aligning with the schema's single parameter 'projectName'. However, it doesn't provide additional context like format constraints, examples, or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.

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

Purpose4/5

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

The description clearly states the tool's purpose: '根据项目名称查询项目基本信息' (query basic project information based on project name). It specifies the verb '查询' (query) and resource '项目基本信息' (basic project information), and lists the specific fields returned: start date, description, investment amount, and current progress. However, it doesn't explicitly distinguish this tool from sibling tools like 'get_project_all' or 'get_project_count', which likely have overlapping functionality.

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 alternatives. It doesn't mention sibling tools like 'get_project_all' (which might return all projects) or 'get_project_count' (which might return counts), nor does it specify prerequisites, exclusions, or contextual triggers for usage. The agent must infer usage from the tool name and description alone.

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

get_random_wallpaperC

从Bing壁纸获取随机壁纸,返回壁纸的URL、标题和描述信息

ParametersJSON Schema
NameRequiredDescriptionDefault
resolutionNo壁纸分辨率,可选值:1920x1080, 3840x2160, 1366x768等,默认为1920x1080
marketNo地区市场,如zh-CN(中国), en-US(美国)等,默认为zh-CN

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states it fetches from Bing and returns specific data fields, but doesn't mention rate limits, authentication requirements, error conditions, whether results are truly random or cached, or any other behavioral traits. The description is minimal and lacks important operational context.

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

Conciseness4/5

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

The description is a single, efficient sentence that communicates the core functionality. It's appropriately concise without being overly terse, though it could potentially benefit from slightly more context about the tool's behavior.

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

Completeness2/5

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

For a tool with no annotations and no output schema, the description is insufficient. It doesn't explain the return format beyond listing fields, doesn't mention error handling, rate limits, or authentication requirements. Given the lack of structured metadata, the description should provide more complete operational context.

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 schema description coverage is 100%, with both parameters ('resolution' and 'market') well-documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema, so it meets the baseline score of 3 for high schema coverage.

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

Purpose4/5

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

The description clearly states the action ('获取随机壁纸' - get random wallpaper), source ('从Bing壁纸' - from Bing wallpaper), and return values ('返回壁纸的URL、标题和描述信息' - returns wallpaper URL, title, and description). It's specific about what the tool does, though it doesn't explicitly differentiate from sibling tools which appear unrelated to wallpaper fetching.

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 alternatives. It doesn't mention any prerequisites, limitations, or context for when this tool is appropriate versus other wallpaper-fetching methods or the unrelated sibling tools listed.

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. 5 tool updates
    • First observedadd_project
    • First observedget_project_all
    • First observedget_project_count
    • First observedget_project_info
    • First observedget_random_wallpaper

TDQS

C2.4/5.0

Scored across 5 tools

Disambiguation3/5

Four tools clearly target project-related operations (add, list all, count, get info), but 'get_random_wallpaper' is an unrelated outlier that creates domain confusion. The project tools themselves are distinct in purpose, though 'get_project_all' and 'get_project_info' could potentially overlap if an agent needs specific project details versus a full list.

Naming Consistency4/5

Four of the five tools follow a consistent 'verb_project_noun' pattern (e.g., add_project, get_project_all), with clear action-object naming. The outlier 'get_random_wallpaper' breaks this pattern by using a different object (wallpaper) and lacks the 'project' prefix, but the core set is mostly consistent.

Tool Count3/5

With 5 tools, the count is reasonable for a project management server, but the inclusion of an unrelated wallpaper tool makes the scope feel thin for the stated purpose. The project domain has only 4 dedicated tools, which is borderline minimal for basic CRUD operations (e.g., missing update/delete).

Completeness2/5

For a project query server, there are significant gaps in coverage: it provides create (add_project) and read operations (get all, count, info), but lacks update and delete tools, leaving the lifecycle incomplete. The unrelated wallpaper tool does not contribute to the domain, and the absence of project modification capabilities will likely cause agent failures in workflows requiring edits or removals.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers