alfaarghya
diff --git a/‎README.md‎
Lines changed: 56 additions & 0 deletions b/‎README.md‎
Lines changed: 56 additions & 0 deletions
diff --git a/‎mcp/index.ts‎
Lines changed: 61 additions & 0 deletions b/‎mcp/index.ts‎
Lines changed: 61 additions & 0 deletions
diff --git a/‎mcp/leetCodeService.ts‎
Lines changed: 236 additions & 0 deletions b/‎mcp/leetCodeService.ts‎
Lines changed: 236 additions & 0 deletions
@@ -34,6 +34,62 @@ https://alfa-leetcode-api.onrender.com/
 docker run -p 3000:3000 alfaarghya/alfa-leetcode-api:2.0.2
 ```
 
+## MCP server integration 🤖
+
+The repository also ships a Model Context Protocol (MCP) server that exposes the same LeetCode data as interactive tools for Claude Desktop or the MCP Inspector.
+
+### Build
+
+```powershell
+npm install
+npm run build
+```
+
+The build step produces `dist/mcp/index.js`, the entry point used by MCP clients.
+
+### MCP client setup
+
+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 — 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
+   {
+     "mcpServers": {
+       "leetcode-suite": {
+         "command": "node",
+         "args": ["C:\\path\\to\\alfa-leetcode-api\\dist\\mcp\\index.js"]
+       }
+     }
+   }
+   ```
+
+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.
+
+### MCP Inspector
+
+Use the Inspector to debug tools locally:
+
+```powershell
+npx @modelcontextprotocol/inspector node C:\path\to\alfa-leetcode-api\dist\mcp\index.js
+```
+
+For TypeScript-on-the-fly development:
+
+```powershell
+npx @modelcontextprotocol/inspector npx ts-node mcp/index.ts
+```
+
+Choose the *Tools* tab in the Inspector UI to invoke individual operations and confirm responses before wiring them into Claude.
+
 ## Wanna Contribute 🤔??
 
 follow this documentation => <a href="CONTRIBUTING.md" target="_blank">CONTRIBUTING.md</a>
 
@@ -0,0 +1,61 @@
+import { DiscussionToolsModule } from './modules/discussionTools';
+import { ProblemToolsModule } from './modules/problemTools';
+import { UserToolsModule } from './modules/userTools';
+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';
+  }
+
+  const normalized = input.trim().toLowerCase();
+
+  if (normalized === 'all' || normalized === 'suite' || normalized === 'default') {
+    return 'all';
+  }
+
+  if (normalized in modulesByKey) {
+    return normalized as Exclude<Mode, 'all'>;
+  }
+
+  console.error(`Unknown MCP server mode: ${input}`);
+  console.error('Expected one of: all, users, problems, discussions');
+  process.exit(1);
+}
+
+// Resolves the modules and server name based on the selected mode.
+function resolveModules(mode: Mode): ModuleConfig {
+  if (mode === 'all') {
+    return {
+      modules: Object.values(modulesByKey),
+      name: 'alfa-leetcode-suite',
+    };
+  }
+
+  return {
+    modules: [modulesByKey[mode]],
+    name: `alfa-leetcode-${mode}`,
+  };
+}
+
+// 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);
+  const { modules, name } = resolveModules(mode);
+
+  await startServer({ name, version: SERVER_VERSION }, modules);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
@@ -0,0 +1,236 @@
+import {
+  formatAcSubmissionData,
+  formatBadgesData,
+  formatContestData,
+  formatContestHistoryData,
+  formatDailyData,
+  formatLanguageStats,
+  formatProblemsData,
+  formatProgressStats,
+  formatQuestionData,
+  formatSolvedProblemsData,
+  formatSubmissionCalendarData,
+  formatSubmissionData,
+  formatTrendingCategoryTopicData,
+  formatSkillStats,
+  formatUserData,
+  formatUserProfileData,
+} from '../src/FormatUtils';
+import {
+  AcSubmissionQuery,
+  contestQuery,
+  dailyProblemQuery,
+  discussCommentsQuery,
+  discussTopicQuery,
+  getUserProfileQuery,
+  languageStatsQuery,
+  officialSolutionQuery,
+  problemListQuery,
+  selectProblemQuery,
+  submissionQuery,
+  trendingDiscussQuery,
+  userProfileCalendarQuery,
+  userProfileQuery,
+  userQuestionProgressQuery,
+  userContestRankingInfoQuery,
+  skillStatsQuery,
+} from '../src/GQLQueries';
+import type {
+  DailyProblemData,
+  ProblemSetQuestionListData,
+  SelectProblemData,
+  TrendingDiscussionObject,
+  UserData,
+} from '../src/types';
+import { executeGraphQL } from './serverUtils';
+import { SubmissionArgs, CalendarArgs, ProblemArgs, DiscussCommentsArgs, Variables } from './types';
+
+// 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)) {
+    if (value !== undefined && value !== null && !(typeof value === 'number' && Number.isNaN(value))) {
+      result[key] = value;
+    }
+  }
+  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;
+  const tags = args.tags ? args.tags.split(' ') : [];
+  const difficulty = args.difficulty ?? undefined;
+  const variables = buildVariables({
+    categorySlug: '',
+    limit,
+    skip,
+    filters: {
+      tags,
+      difficulty,
+    },
+  });
+  const data = await executeGraphQL(problemListQuery, variables);
+  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,
+    orderBy: args.orderBy ?? 'newest_to_oldest',
+    pageNo: args.pageNo ?? 1,
+    numPerPage: args.numPerPage ?? 10,
+  });
+  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 });
+}