feat(mcp): add modular MCP server & Inspector/Claude integration #71

devroopsaha744 · 2025-10-25T15:39:49Z

Summary

This PR adds a modular Model Context Protocol (MCP) server that exposes LeetCode functionality as MCP tools and documents how to run and inspect it with the MCP Inspector and Claude Desktop. The MCP implementation is split into three modules: users, problems, and discussions. It includes a shared server bootstrap, an Inspector launcher, and README updates with setup and usage instructions.

What changed

Add modular MCP entrypoint and bootstrap

index.ts - entrypoint that composes modules and supports running a single module or the full suite via CLI arg or environment variable
serverUtils.ts - shared helpers for server lifecycle and GraphQL execution; fix to avoid double-starting stdio transport
leetCodeService.ts - LeetCode GraphQL query helpers used by modules

Add tool modules

userTools.ts - user related tools (profile, badges, submissions, calendar, etc.)
problemTools.ts - problem related tools (daily, select, list, filters)
discussionTools.ts - discussion related tools (trending, topic, comments)

Dev and inspect helpers

runInspector.ts - helper to launch the official MCP Inspector against this server
package.json - add script mcp:inspect

Documentation

README.md - add "MCP server integration" section with build, Inspector, and Claude Desktop configuration examples using generic paths

Naming and validation

Tool identifiers updated to conform to MCP name pattern (only alphanumeric, underscore, hyphen). Example: leetcode_user_data

Files added or modified (high level)

Added

index.ts
serverUtils.ts
leetCodeService.ts
userTools.ts
problemTools.ts
discussionTools.ts
runInspector.ts

Modified

package.json (scripts)
README.md (MCP integration docs)

Rationale

Provide interactive, LLM-friendly access to LeetCode data without requiring the REST API as an intermediary.
Make tools modular so developers can run only the domain they need during development or deployment.
Ensure tool names conform to MCP client validation so they appear in Inspector and Claude Desktop.

How to test

Install and build

npm install
npm run build

Configure Claude Desktop

Open %AppData%\Claude\claude_desktop_config.json.
Add a server entry pointing at the built file. Example:

   {
     "mcpServers": {
       "leetcode-suite": {
         "command": "node",
         "args": ["C:\\path\\to\\alfa-leetcode-api\\dist\\mcp\\index.js"]
       }
     }
   }

Restart Claude Desktop and verify tools appear under Search and tools

Demo

Notes and compatibility

The MCP server queries https://leetcode.com/graphql directly. It does not call the existing HTTP REST API in this repo.
HTTP REST endpoints remain unchanged.
Tool names were changed to meet MCP naming rules. Clients must use the updated identifiers.
The server is subject to the same rate limits as direct GraphQL calls. Use Inspector to validate tool schemas before integrating into Claude Desktop.

Checklist

✅ Typescript build passes: npm run build
✅ Tool identifiers conform to MCP name pattern
✅ README updated with MCP integration instructions
⚠️ Manual Inspector test recommended before Claude Desktop integration

alfaarghya · 2025-10-25T16:44:29Z

hii @devroopsaha744

I appreciate your efforts and contributions, but I was unable to find the previous discussion for this feature!

Could you provide the issue number or the discussion number?

devroopsaha744 · 2025-10-25T19:11:16Z

hi @alfaarghya

Thanks for the feedback! I wasn’t aware that prior discussion or an issue was required before opening a feature PR. The goal of this PR is to add an MCP (Model Context Protocol) server layer so that the API can be accessed directly by AI agents and LLMs through Claude Desktop or similar tools.

Shall I open a discussion for this feature and then link it back here (if approved)?

alfaarghya · 2025-10-25T19:30:44Z

Yes, in every open-source project, you first need to ask the maintainer or the community about the feature you want to add by posting an issue or opening up a discussion.

So, please open up some discussion or feature(issue), so that others can give their opinions and also let's discuss if we need this feature or not!

Meanwhile, I will be going through your changes and reviewing your code.

devroopsaha744 · 2025-10-26T06:55:54Z

hi @alfaarghya

I’ve opened a detailed discussion outlining this feature proposal here: #73

It covers the motivation, technical breakdown, and rationale behind adding the MCP server for AI Agent and LLM integration.
We can continue the conversation there to evaluate alignment before reopening or refining the PR.

alfaarghya

hii @devroopsaha744

Your implementation looks solid! But we need some changes before I merge it!

add proper comments for your functions
move type or interface to other directory or file.
Provide instructions for other OS like Linux and MAC OS

alfaarghya · 2025-10-27T15:21:24Z

mcp/index.ts

+type Mode = 'all' | 'users' | 'problems' | 'discussions';
+
+type ModuleConfig = {
+  modules: ToolModule[];
+  name: string;
+};


I saw you are putting types in the files themselves. But I would suggest trying to keep them in a separate file or directory(like mcp/types.ts).

alfaarghya · 2025-10-27T15:22:01Z

README.md

+1. Open `%AppData%/Claude/claude_desktop_config.json`.
+2. Add a server entry pointing at the built file. Example:
+
+   ```json
+   {
+     "mcpServers": {
+       "leetcode-suite": {
+         "command": "node",
+         "args": ["C:\\path\\to\\alfa-leetcode-api\\dist\\mcp\\index.js"]
+       }
+     }
+   }
+   ```


This is how we can configure the MCP server for Windows. What about Linux and MAC OS?

Need instructions for those!

alfaarghya · 2025-10-27T15:23:01Z

mcp/leetCodeService.ts

+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>;


Keep types in a separate file(mcp/types.ts)

alfaarghya · 2025-10-27T15:24:12Z

mcp/serverUtils.ts

+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+type GraphQLParams = Record<string, unknown>;


Keep types in a separate file(mcp/types.ts)

alfaarghya · 2025-10-27T15:26:04Z

mcp/serverUtils.ts

+type GraphQLParams = Record<string, unknown>;
+
+const GRAPHQL_ENDPOINT = 'https://leetcode.com/graphql';
+export const SERVER_VERSION = '2.0.1';


The current server version is 2.0.2.

But why do we need this?

alfaarghya · 2025-10-27T15:26:33Z

mcp/serverUtils.ts

+export type ToolResponse = { content: { type: 'text'; text: string }[] };
+
+export type ToolExecutor = () => Promise<unknown>;


Keep types in a separate file(mcp/types.ts)

… MCP setup client‑agnostic

devroopsaha744 · 2025-10-31T09:49:31Z

Hi @alfaarghya

first of all sorry the delay.

I have implemented the changes as per your request:

moved the types and interfaces onto one file
corrected the server version, it was a typo actually, it is was meant to be the version of the MCP server not the API server
Regarding the instructions, these are same for all the operating systems as long as that particular MCP client (claude desktop, cursor etc) is installed in that operating system and made the setup instructions more clear and robust.

can you please review them

alfaarghya · 2025-11-02T06:14:24Z

Hi @devroopsaha744, I'll review your changes, but meanwhile, please resolve the merge conflicts on package-lock.json.

alfaarghya · 2025-11-06T10:45:03Z

package-lock.json

Resolve these merge conflicts

alfaarghya

Hii @devroopsaha744, your code looks solid, and I will approve the PR. But first, please resolve the conflict!

devroopsaha744 · 2025-11-06T11:18:34Z

Hi @alfaarghya , I have resolved the conflicts. let me know if you need anything else!

feat(mcp): add modular MCP server & Inspector/Claude integration

0778b4d

alfaarghya requested changes Oct 27, 2025

View reviewed changes

refactor(mcp): extract types to types.ts, simplify comments, and make…

c2e5ebf

… MCP setup client‑agnostic

alfaarghya reviewed Nov 6, 2025

View reviewed changes

package-lock.json

Copy link

Owner

alfaarghya Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolve these merge conflicts

alfaarghya requested changes Nov 6, 2025

View reviewed changes

Merge branch 'main' into mcp

0ee9641

		export type ToolResponse = { content: { type: 'text'; text: string }[] };

		export type ToolExecutor = () => Promise<unknown>;

feat(mcp): add modular MCP server & Inspector/Claude integration #71

Are you sure you want to change the base?

feat(mcp): add modular MCP server & Inspector/Claude integration #71

Uh oh!

Conversation

devroopsaha744 commented Oct 25, 2025

Summary

What changed

Add modular MCP entrypoint and bootstrap

Add tool modules

Dev and inspect helpers

Documentation

Naming and validation

Files added or modified (high level)

Added

Modified

Rationale

How to test

Install and build

Configure Claude Desktop

Demo

Notes and compatibility

Checklist

Uh oh!

alfaarghya commented Oct 25, 2025

hii @devroopsaha744

Uh oh!

devroopsaha744 commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alfaarghya commented Oct 25, 2025

Uh oh!

devroopsaha744 commented Oct 26, 2025

Uh oh!

alfaarghya left a comment

Choose a reason for hiding this comment

hii @devroopsaha744

Uh oh!

alfaarghya Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

alfaarghya Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

alfaarghya Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

alfaarghya Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

alfaarghya Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

alfaarghya Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

devroopsaha744 commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alfaarghya commented Nov 2, 2025

Uh oh!

alfaarghya Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

alfaarghya left a comment

Choose a reason for hiding this comment

Uh oh!

devroopsaha744 commented Nov 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

devroopsaha744 commented Oct 25, 2025 •

edited

Loading

devroopsaha744 commented Oct 31, 2025 •

edited

Loading