codewars-mcp 1.0.0

package/README.md

@@ -0,0 +1,24 @@
+# Codewars MCP
+
+Keyless MCP server for Codewars: user ranks, honor, kata.
+
+Pairs well with `leetcode-mcp`, `codeforces-mcp`, and `github-intel-mcp`.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `get_user`: Honor, rank, clan, languages.
+- `get_kata`: Kata by id or slug.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required.

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+export declare class CodewarsError extends Error {
+}
+export interface Codewarrior {
+    username: string;
+    honor?: number;
+    clan?: string;
+    leaderboard?: number;
+    overall?: string;
+    totalCompleted?: number;
+    languages: string[];
+}
+export declare function getUser(username: string): Promise<Codewarrior>;
+export interface Kata {
+    id?: string;
+    name?: string;
+    rank?: string;
+    tags: string[];
+}
+export declare function getKata(idOrSlug: string): Promise<Kata>;
+export declare function formatUser(u: Codewarrior): string;
+export declare function formatKata(k: Kata): string;

package/dist/api.js

@@ -0,0 +1,63 @@
+/**
+ * Codewars API v1 client, keyless.
+ * Docs: https://dev.codewars.com/
+ */
+const BASE = "https://www.codewars.com/api/v1";
+export class CodewarsError extends Error {
+}
+async function getJson(path) {
+    const res = await fetch(`${BASE}${path}`, {
+        headers: { "User-Agent": "codewars-mcp/1.0", Accept: "application/json" },
+        signal: AbortSignal.timeout(20000),
+    });
+    if (res.status === 404)
+        throw new CodewarsError("Not found on Codewars.");
+    if (!res.ok)
+        throw new CodewarsError(`Codewars error ${res.status}`);
+    return (await res.json());
+}
+export async function getUser(username) {
+    if (!/^[\w-]+$/.test(username.trim()))
+        throw new CodewarsError(`Not a username: "${username}".`);
+    const u = await getJson(`/users/${encodeURIComponent(username.trim())}`);
+    const ranks = (u.ranks ?? {});
+    const overall = (ranks.overall ?? {});
+    const langs = (ranks.languages ?? {});
+    const completed = (u.codeChallenges ?? {});
+    return {
+        username: String(u.username ?? username),
+        honor: u.honor,
+        clan: u.clan && u.clan !== "None" ? String(u.clan) : undefined,
+        leaderboard: u.leaderboardPosition,
+        overall: overall.name,
+        totalCompleted: completed.totalCompleted,
+        languages: Object.entries(langs)
+            .map(([lang, r]) => `${lang}(${r.name ?? "?"})`)
+            .slice(0, 8),
+    };
+}
+export async function getKata(idOrSlug) {
+    if (!/^[\w-]+$/.test(idOrSlug.trim()))
+        throw new CodewarsError(`Not a kata id or slug: "${idOrSlug}".`);
+    const k = await getJson(`/code-challenges/${encodeURIComponent(idOrSlug.trim().toLowerCase())}`);
+    return {
+        id: k.id ?? k.slug,
+        name: k.name,
+        rank: k.rank?.name ?? k.rank,
+        tags: Array.isArray(k.tags) ? k.tags.map(String).slice(0, 6) : [],
+    };
+}
+export function formatUser(u) {
+    const lines = [
+        `${u.username}${u.overall ? ` (${u.overall})` : ""}`,
+        u.honor !== undefined ? `Honor: ${u.honor.toLocaleString()}` : "",
+        u.leaderboard ? `Leaderboard: #${u.leaderboard}` : "",
+        u.clan ? `Clan: ${u.clan}` : "",
+        u.totalCompleted !== undefined ? `Completed kata: ${u.totalCompleted}` : "",
+        u.languages.length ? `Languages: ${u.languages.join(", ")}` : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function formatKata(k) {
+    return `[${k.id ?? "?"}] ${k.name ?? "(unnamed)"}${k.rank ? ` (${k.rank})` : ""}${k.tags.length ? `\nTags: ${k.tags.join(", ")}` : ""}`;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,50 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CodewarsError, formatKata, formatUser, getKata, getUser } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "codewars-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("get_user", {
+        title: "Get user",
+        description: "A Codewars user: honor, rank, clan, languages, completed kata.",
+        inputSchema: z.object({
+            username: z.string().describe("Codewars username"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ username }) => {
+        try {
+            return text(formatUser(await getUser(username)));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_kata", {
+        title: "Get kata",
+        description: "One kata by id or slug: name, rank, tags.",
+        inputSchema: z.object({
+            id_or_slug: z.string().describe("Kata id or slug, e.g. 'valid-parentheses'"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ id_or_slug }) => {
+        try {
+            return text(formatKata(await getKata(id_or_slug)));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof CodewarsError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "codewars-mcp",
+  "version": "1.0.0",
+  "description": "Keyless MCP server for Codewars: user ranks, honor, kata.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/codewars-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "codewars-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "codewars",
+    "coding",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}