refactor(mcp): extract types to types.ts, simplify comments, and make MCP setup client‑agnostic

devroopsaha744 · devroopsaha744 · commit c2e5ebf0a238 · 2025-10-31T15:11:49.000+05:30
diff --git a/README.md b/README.md
@@ -47,10 +47,17 @@ npm run build
 
 The build step produces `dist/mcp/index.js`, the entry point used by MCP clients.
 
-### Claude Desktop setup
+### MCP client setup
 
-1. Open `%AppData%/Claude/claude_desktop_config.json`.
-2. Add a server entry pointing at the built file. Example:
+1. The configuration is the same across operating systems as long as your MCP client is installed and supports external servers (Claude Desktop, Cursor, Windsurf, etc.).
+
+2. Add a server entry pointing at the built file by pasting the JSON below into your MCP client's config file &mdash; for example:
+
+   - `claude_desktop_config.json` for Claude Desktop
+   - `mcp.json` for Cursor
+   - the equivalent JSON config file for other MCP clients
+
+   Example (paste into the appropriate file):
 
    ```json
    {
@@ -63,7 +70,7 @@ The build step produces `dist/mcp/index.js`, the entry point used by MCP clients
    }
    ```
 
-3. Restart Claude Desktop. A "Search & tools" toggle appears once the server launches successfully.
+3. Restart your MCP client. A "Search & tools" toggle (or similar UI element) should appear once the server launches successfully.
 
 To run only a subset of tools, append the module name (`users`, `problems`, or `discussions`) as an extra argument or set the `MCP_SERVER_MODE` environment variable.
 
diff --git a/mcp/index.ts b/mcp/index.ts
@@ -1,21 +1,16 @@
 import { DiscussionToolsModule } from './modules/discussionTools';
 import { ProblemToolsModule } from './modules/problemTools';
 import { UserToolsModule } from './modules/userTools';
-import { SERVER_VERSION, startServer, ToolModule } from './serverUtils';
-
-type Mode = 'all' | 'users' | 'problems' | 'discussions';
-
-type ModuleConfig = {
-  modules: ToolModule[];
-  name: string;
-};
+import { SERVER_VERSION, startServer } from './serverUtils';
+import { Mode, ModuleConfig, ToolModule } from './types';
 
 const modulesByKey: Record<Exclude<Mode, 'all'>, ToolModule> = {
   users: new UserToolsModule(),
   problems: new ProblemToolsModule(),
   discussions: new DiscussionToolsModule(),
 };
 
+// Normalizes the input mode string to a valid Mode type.
 function normalizeMode(input: string | undefined): Mode {
   if (!input) {
     return 'all';
@@ -36,6 +31,7 @@ function normalizeMode(input: string | undefined): Mode {
   process.exit(1);
 }
 
+// Resolves the modules and server name based on the selected mode.
 function resolveModules(mode: Mode): ModuleConfig {
   if (mode === 'all') {
     return {
@@ -50,6 +46,7 @@ function resolveModules(mode: Mode): ModuleConfig {
   };
 }
 
+// Main entry point for the MCP server. Parses command line arguments, sets up modules, and starts the server.
 async function main() {
   const modeInput = process.env.MCP_SERVER_MODE ?? process.argv[2];
   const mode = normalizeMode(modeInput);
diff --git a/mcp/leetCodeService.ts b/mcp/leetCodeService.ts
@@ -43,14 +43,9 @@ import type {
   UserData,
 } from '../src/types';
 import { executeGraphQL } from './serverUtils';
+import { SubmissionArgs, CalendarArgs, ProblemArgs, DiscussCommentsArgs, Variables } from './types';
 
-type SubmissionArgs = { username: string; limit?: number };
-type CalendarArgs = { username: string; year: number };
-type ProblemArgs = { limit?: number; skip?: number; tags?: string; difficulty?: string };
-type DiscussCommentsArgs = { topicId: number; orderBy?: string; pageNo?: number; numPerPage?: number };
-
-type Variables = Record<string, unknown>;
-
+// Builds GraphQL variables by filtering out undefined, null, and NaN values.
 function buildVariables(input: Record<string, unknown>): Variables {
   const result: Variables = {};
   for (const [key, value] of Object.entries(input)) {
@@ -61,82 +56,98 @@ function buildVariables(input: Record<string, unknown>): Variables {
   return result;
 }
 
+// Retrieves the formatted user profile summary.
 export async function getUserProfileSummary(username: string) {
   const data = await executeGraphQL(userProfileQuery, { username });
   return formatUserData(data as UserData);
 }
 
+// Retrieves the formatted user badges data.
 export async function getUserBadges(username: string) {
   const data = await executeGraphQL(userProfileQuery, { username });
   return formatBadgesData(data as UserData);
 }
 
+// Retrieves the formatted user contest data.
 export async function getUserContest(username: string) {
   const data = await executeGraphQL(contestQuery, { username });
   return formatContestData(data as UserData);
 }
 
+// Retrieves the formatted user contest history.
 export async function getUserContestHistory(username: string) {
   const data = await executeGraphQL(contestQuery, { username });
   return formatContestHistoryData(data as UserData);
 }
 
+// Retrieves the formatted solved problems statistics.
 export async function getSolvedProblems(username: string) {
   const data = await executeGraphQL(userProfileQuery, { username });
   return formatSolvedProblemsData(data as UserData);
 }
 
+// Retrieves recent submissions for a user.
 export async function getRecentSubmission(args: SubmissionArgs) {
   const variables = buildVariables({ username: args.username, limit: args.limit });
   const data = await executeGraphQL(submissionQuery, variables);
   return formatSubmissionData(data as UserData);
 }
 
+// Retrieves recent accepted submissions for a user.
 export async function getRecentAcSubmission(args: SubmissionArgs) {
   const variables = buildVariables({ username: args.username, limit: args.limit });
   const data = await executeGraphQL(AcSubmissionQuery, variables);
   return formatAcSubmissionData(data as UserData);
 }
 
+// Retrieves the submission calendar for a user in a given year.
 export async function getSubmissionCalendar(args: CalendarArgs) {
   const variables = buildVariables({ username: args.username, year: args.year });
   const data = await executeGraphQL(userProfileCalendarQuery, variables);
   return formatSubmissionCalendarData(data as UserData);
 }
 
+// Retrieves the aggregated user profile data.
 export async function getUserProfileAggregate(username: string) {
   const data = await executeGraphQL(getUserProfileQuery, { username });
   return formatUserProfileData(data);
 }
 
+// Retrieves the language statistics for a user.
 export async function getLanguageStats(username: string) {
   const data = await executeGraphQL(languageStatsQuery, { username });
   return formatLanguageStats(data as UserData);
 }
 
+// Retrieves the skill statistics for a user.
 export async function getSkillStats(username: string) {
   const data = await executeGraphQL(skillStatsQuery, { username });
   return formatSkillStats(data as UserData);
 }
 
+// Retrieves the daily problem.
 export async function getDailyProblem() {
   const data = await executeGraphQL(dailyProblemQuery, {});
   return formatDailyData(data as DailyProblemData);
 }
 
+// Retrieves the raw daily problem data.
 export async function getDailyProblemRaw() {
   return executeGraphQL(dailyProblemQuery, {});
 }
 
+// Retrieves a selected problem by title slug.
 export async function getSelectProblem(titleSlug: string) {
   const data = await executeGraphQL(selectProblemQuery, { titleSlug });
   return formatQuestionData(data as SelectProblemData);
 }
 
+// Retrieves the raw data for a selected problem by title slug.
 export async function getSelectProblemRaw(titleSlug: string) {
   return executeGraphQL(selectProblemQuery, { titleSlug });
 }
 
+// Retrieves a list of problems based on the given arguments.
 export async function getProblemSet(args: ProblemArgs) {
   const limit = args.skip !== undefined && args.limit === undefined ? 1 : args.limit ?? 20;
   const skip = args.skip ?? 0;
@@ -155,19 +166,23 @@ export async function getProblemSet(args: ProblemArgs) {
   return formatProblemsData(data as ProblemSetQuestionListData);
 }
 
+// Retrieves the official solution for a problem.
 export async function getOfficialSolution(titleSlug: string) {
   return executeGraphQL(officialSolutionQuery, { titleSlug });
 }
 
+// Retrieves trending discussion topics.
 export async function getTrendingTopics(first: number) {
   const data = await executeGraphQL(trendingDiscussQuery, { first });
   return formatTrendingCategoryTopicData(data as TrendingDiscussionObject);
 }
 
+// Retrieves a discussion topic by ID.
 export async function getDiscussTopic(topicId: number) {
   return executeGraphQL(discussTopicQuery, { topicId });
 }
 
+// Retrieves comments for a discussion topic.
 export async function getDiscussComments(args: DiscussCommentsArgs) {
   const variables = buildVariables({
     topicId: args.topicId,
@@ -178,36 +193,44 @@ export async function getDiscussComments(args: DiscussCommentsArgs) {
   return executeGraphQL(discussCommentsQuery, variables);
 }
 
+// Retrieves raw language statistics for a user.
 export async function getLanguageStatsRaw(username: string) {
   return executeGraphQL(languageStatsQuery, { username });
 }
 
+// Retrieves raw submission calendar data for a user.
 export async function getUserProfileCalendarRaw(args: CalendarArgs) {
   const variables = buildVariables({ username: args.username, year: args.year });
   return executeGraphQL(userProfileCalendarQuery, variables);
 }
 
+// Retrieves raw user profile data.
 export async function getUserProfileRaw(username: string) {
   return executeGraphQL(getUserProfileQuery, { username });
 }
 
+// Retrieves the legacy daily problem data.
 export async function getDailyProblemLegacy() {
   return executeGraphQL(dailyProblemQuery, {});
 }
 
+// Retrieves raw skill statistics for a user.
 export async function getSkillStatsRaw(username: string) {
   return executeGraphQL(skillStatsQuery, { username });
 }
 
+// Retrieves the question progress for a user.
 export async function getUserProgress(username: string) {
   const data = await executeGraphQL(userQuestionProgressQuery, { username });
   return formatProgressStats(data as UserData);
 }
 
+// Retrieves the contest ranking information for a user.
 export async function getUserContestRankingInfo(username: string) {
   return executeGraphQL(userContestRankingInfoQuery, { username });
 }
 
+// Retrieves raw question progress data for a user.
 export async function getUserProgressRaw(username: string) {
   return executeGraphQL(userQuestionProgressQuery, { username });
 }
diff --git a/mcp/modules/discussionTools.ts b/mcp/modules/discussionTools.ts
@@ -1,9 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { getDiscussComments, getDiscussTopic, getTrendingTopics } from '../leetCodeService';
-import { runTool, ToolModule } from '../serverUtils';
+import { runTool } from '../serverUtils';
+import { ToolModule } from '../types';
 
 export class DiscussionToolsModule implements ToolModule {
+  // Registers discussion-related tools with the MCP server.
   register(server: McpServer): void {
     server.registerTool(
         'leetcode_discuss_trending',
diff --git a/mcp/modules/problemTools.ts b/mcp/modules/problemTools.ts
@@ -9,9 +9,11 @@ import {
   getSelectProblem,
   getSelectProblemRaw,
 } from '../leetCodeService';
-import { runTool, ToolModule } from '../serverUtils';
+import { runTool } from '../serverUtils';
+import { ToolModule } from '../types';
 
 export class ProblemToolsModule implements ToolModule {
+  // Registers problem-related tools with the MCP server.
   register(server: McpServer): void {
     server.registerTool(
       'leetcode_problem_daily',
diff --git a/mcp/modules/userTools.ts b/mcp/modules/userTools.ts
@@ -20,12 +20,14 @@ import {
   getUserProgress,
   getUserProgressRaw,
 } from '../leetCodeService';
-import { runTool, ToolModule } from '../serverUtils';
+import { runTool } from '../serverUtils';
+import { ToolModule } from '../types';
 
 const usernameSchema = z.string();
 const limitSchema = z.number().int().positive().max(50).optional();
 
 export class UserToolsModule implements ToolModule {
+  // Registers user-related tools with the MCP server.
   register(server: McpServer): void {
     server.registerTool(
       'leetcode_user_data',
diff --git a/mcp/serverUtils.ts b/mcp/serverUtils.ts
@@ -1,22 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-
-type GraphQLParams = Record<string, unknown>;
+import { GraphQLParams, GraphQLClientError, ToolResponse, ToolExecutor, ToolModule } from './types';
 
 const GRAPHQL_ENDPOINT = 'https://leetcode.com/graphql';
-export const SERVER_VERSION = '2.0.1';
-
-export class GraphQLClientError extends Error {
-  readonly status: number;
-  readonly body: unknown;
-
-  constructor(message: string, status: number, body: unknown) {
-    super(message);
-    this.status = status;
-    this.body = body;
-  }
-}
+export const SERVER_VERSION = '1.0.0';
 
+// Executes a GraphQL query against the LeetCode API.
 export async function executeGraphQL(query: string, variables: GraphQLParams = {}): Promise<unknown> {
   const requestInit: RequestInit = {
     method: 'POST',
@@ -41,10 +30,12 @@ export async function executeGraphQL(query: string, variables: GraphQLParams = {
   return payload.data;
 }
 
+// Converts data to tool content format.
 export function toToolContent(data: unknown): { type: 'text'; text: string }[] {
   return [{ type: 'text', text: JSON.stringify(data, null, 2) }];
 }
 
+// Creates a tool result from data.
 export function createToolResult(data: unknown): {
   content: { type: 'text'; text: string }[];
 } {
@@ -53,6 +44,7 @@ export function createToolResult(data: unknown): {
   };
 }
 
+// Creates an error tool result from an error.
 export function createErrorResult(error: unknown): {
   content: { type: 'text'; text: string }[];
 } {
@@ -72,10 +64,7 @@ export function createErrorResult(error: unknown): {
   return createToolResult({ message: 'Unknown error', detail: error });
 }
 
-export type ToolResponse = { content: { type: 'text'; text: string }[] };
-
-export type ToolExecutor = () => Promise<unknown>;
-
+// Runs a tool executor and handles errors.
 export async function runTool(executor: ToolExecutor): Promise<ToolResponse> {
   try {
     const data = await executor();
@@ -85,10 +74,7 @@ export async function runTool(executor: ToolExecutor): Promise<ToolResponse> {
   }
 }
 
-export interface ToolModule {
-  register(server: McpServer): void;
-}
-
+// Starts the MCP server with the given modules.
 export async function startServer(
   serverInfo: { name: string; version?: string },
   modules: ToolModule[],
diff --git a/mcp/types.ts b/mcp/types.ts
