skill4agent MCP Server

Instructions

Implementation Reference

• src/tools/search.ts:33-67 (handler)

  Main handler function for search_skills tool. Validates input using Zod schema, calls the API client to search for skills, and returns formatted JSON response with error handling.

  export async function searchSkillsHandler(
    args: z.infer<typeof searchSkillsSchema>
  ): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
    const api = getAPIClient();
  
    try {
      const result = await api.searchSkills({
        keyword: args.keyword,
        categories: args.categories,
        limit: args.limit || 10,
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Search failed';
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: message,
              message: 'Search failed. Please check: 1. Parameter format is correct 2. Network connection is normal',
            }, null, 2),
          },
        ],
      };
    }
  }

• src/tools/search.ts:27-31 (schema)

  Zod schema definition for search_skills tool input validation. Defines keyword (required), categories (optional array), and limit (optional number 1-100) parameters with descriptions.

  export const searchSkillsSchema = z.object({
    keyword: z.string().describe('Search keyword. Can be English, Chinese, or mixed. (e.g., "React", "n8n-workflow", "frontend development", "copywriting", "langchain docs")'),
    categories: z.array(z.enum(CATEGORIES as [string, ...string[]])).optional().describe('Optional category filter. Supports both English and Chinese category names. Can pass multiple categories. (e.g., ["Frontend Development", "AI & Machine Learning"])'),
    limit: z.number().min(1).max(100).optional().describe('Limit the number of results returned. Default is 10, maximum is 100. Set according to your needs to avoid returning too many results.'),
  });

• src/server.ts:26-35 (registration)

  Registration of search_skills tool with MCP server. Registers tool name, description, inputSchema, and handler function.

  server.registerTool(
    'search_skills',
    {
      description: 'Search for Skills by keyword, with optional category filtering. Returns a list of matching skills.\n\nUse cases:\n- When looking for skills in a specific domain\n- When unsure what skill is needed but have a general direction',
      inputSchema: searchSkillsSchema,
    },
    async (args) => {
      return searchSkillsHandler(args);
    }
  );

• src/api/client.ts:29-46 (helper)

  APIClient method that makes the HTTP POST request to /search endpoint. Handles API communication and error handling for the search_skills functionality.

  async searchSkills(params: SearchSkillsParams): Promise<SearchSkillsResponse> {
    try {
      const response = await this.client.post<SearchSkillsResponse>(
        '/search',
        {
          keyword: params.keyword,
          categories: params.categories,
          limit: params.limit || 10,
        }
      );
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw this.handleError(error);
      }
      throw new Error('Failed to search skills: Unknown error');
    }
  }

• src/types/index.ts:1-26 (schema)

  TypeScript interface definitions for SearchSkillsParams, SkillSearchResult, and SearchSkillsResponse. Defines the data structures for the search skills API.

  export interface SearchSkillsParams {
    keyword: string;
    categories?: string[];
    limit?: number;
  }
  
  export interface SkillSearchResult {
    skillId: string;
    skillName: string;
    description: string;
    descriptionTranslated: string;
    categoryName: string;
    tags: string;
    tagsCn: string;
    totalInstalls: number;
    relevance: number;
  }
  
  export interface SearchSkillsResponse {
    skills: SkillSearchResult[];
    total: number;
    query: string;
    categories?: string[];
    suggestions?: string[];
    warnings?: string[];
  }