DWZ Short URL MCP Server

Instructions

Implementation Reference

• src/mcp/tools/listShortUrls.js:57-87 (handler)

  The handler function for the 'list_short_urls' MCP tool. It logs the call, invokes the short link service to fetch the list, formats the pagination response, and returns structured data.

  handler: async function (args) {
    logger.info('MCP工具调用: list_short_urls', { args });
  
    return ErrorHandler.asyncWrapper(async () => {
      // 调用服务层获取短链接列表
      const result = await defaultShortLinkService.listShortUrls(args);
  
      // 格式化返回结果
      return {
        success: true,
        message: '获取短网址列表成功',
        data: {
          list: result.list || [],
          pagination: {
            total: result.total,
            page: result.page,
            size: result.size,
            total_pages: Math.ceil(result.total / result.size),
          },
        },
        meta: {
          operation: 'list_short_urls',
          timestamp: new Date().toISOString(),
          filters: {
            domain: args.domain || null,
            keyword: args.keyword || null,
          },
        },
      };
    })();
  },

• src/mcp/tools/listShortUrls.js:18-50 (schema)

  Input schema definition for the 'list_short_urls' tool, specifying properties for pagination (page, page_size), filtering (domain, keyword) with types, descriptions, constraints, and examples.

  inputSchema: {
    type: 'object',
    properties: {
      page: {
        type: 'integer',
        description: '页码，从1开始',
        minimum: 1,
        default: 1,
        examples: [1, 2, 3],
      },
      page_size: {
        type: 'integer',
        description: '每页数量，最大100，默认10',
        minimum: 1,
        maximum: 100,
        default: 10,
        examples: [10, 20, 50],
      },
      domain: {
        type: 'string',
        description: '按域名筛选（可选）',
        pattern: '^[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
        examples: ['short.ly'],
      },
      keyword: {
        type: 'string',
        description: '搜索关键词，搜索URL、标题或描述（可选）',
        maxLength: 100,
        examples: ['产品', '活动', 'github.com'],
      },
    },
    required: [],
  },

• src/mcp/server.js:72-88 (registration)

  Registration of all MCP tools including 'list_short_urls' (via listShortUrlsTool) into the server's tools Map during server initialization.

  registerTools() {
    const tools = [
      createShortUrlTool,
      getUrlInfoTool,
      listShortUrlsTool,
      deleteShortUrlTool,
      batchCreateShortUrlsTool,
      listDomainsTool,
    ];
  
    for (const tool of tools) {
      this.tools.set(tool.name, tool);
      logger.debug(`注册工具: ${tool.name}`);
    }
  
    logger.info(`已注册 ${tools.length} 个工具`);
  }

• src/services/shortLinkService.js:323-370 (helper)

  Helper service method that validates parameters, normalizes pagination, constructs query params, calls the remote API to list short URLs, handles response, and manages errors.

  async listShortUrls(params = {}) {
    try {
      // 验证参数
      const validatedParams = validateOrThrow('listShortUrls', params);
  
      // 标准化分页参数
      const paginationParams = normalizePaginationParams(validatedParams);
  
      logger.info('列出短链接:', paginationParams);
  
      // 构建查询参数
      const queryParams = {
        page: paginationParams.page,
        page_size: paginationParams.page_size,
      };
  
      // 添加可选参数
      if (validatedParams.domain) {
        queryParams.domain = validatedParams.domain;
      }
      if (validatedParams.keyword) {
        queryParams.keyword = validatedParams.keyword;
      }
  
      // 发送请求
      const response = await this.httpClient.get(
        getApiUrl('/short_links'),
        queryParams
      );
  
      // 处理响应
      const result = this.handleApiResponse(response, '列出短链接');
  
      logger.info('获取短链接列表成功:', {
        total: result.total,
        page: result.page,
        size: result.size,
        count: result.list?.length || 0,
      });
  
      return result;
  
    } catch (error) {
      logger.error('列出短链接失败:', error);
      const handledError = ErrorHandler.handle(error);
      throw ErrorHandler.createMcpErrorResponse(handledError, error);
    }
  }

• src/utils/validation.js:157-162 (schema)

  Joi validation schema used by the service layer for 'listShortUrls' parameters, referencing common rules for page, page_size, domain, and keyword.

  listShortUrls: Joi.object({
    page: commonRules.page,
    page_size: commonRules.pageSize,
    domain: commonRules.domain,
    keyword: commonRules.keyword,
  }),