# @furkankoykiran/coderlegion-mcp

[![CI](https://github.com/furkankoykiran/coderlegion-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/furkankoykiran/coderlegion-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40furkankoykiran%2Fcoderlegion-mcp)](https://www.npmjs.com/package/@furkankoykiran/coderlegion-mcp)
[![GitHub Package](https://img.shields.io/badge/GitHub%20Packages-available-blue?logo=github)](https://github.com/furkankoykiran/coderlegion-mcp/pkgs/npm/coderlegion-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/node/v/%40furkankoykiran%2Fcoderlegion-mcp)](package.json)

TypeScript MCP server for CoderLegion — connect AI agents (Claude, Cursor, Cline) to the developer community platform.

Built with the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk), it exposes **13 tools** covering post management, profile editing, content search, and social interactions — all accessible from any MCP-compatible client.

---

## Features

| Category | Tools |
|---|---|
| **Posts** | `create_post`, `edit_post`, `delete_post`, `get_post`, `list_posts`, `add_comment` |
| **Profile** | `get_profile`, `edit_profile` |
| **Search** | `search_posts`, `browse_tag`, `get_categories` |
| **Social** | `react_to_post`, `get_notifications`, `get_activity_feed` |

---

## Prerequisites

1. **Node.js 20+** (`node --version`)
2. A **CoderLegion account** with valid session cookies

---

## Installation

### Option 1 — Run directly with npx (no install required)

```bash
CODERLEGION_PHPSESSID=xxx CODERLEGION_QA_SESSION=xxx npx @furkankoykiran/coderlegion-mcp
```

### Option 2 — Install globally from npm

```bash
npm install -g @furkankoykiran/coderlegion-mcp
CODERLEGION_PHPSESSID=xxx CODERLEGION_QA_SESSION=xxx coderlegion-mcp
```

### Option 3 — Install from GitHub Packages

```bash
npm install -g @furkankoykiran/coderlegion-mcp --registry=https://npm.pkg.github.com
CODERLEGION_PHPSESSID=xxx CODERLEGION_QA_SESSION=xxx coderlegion-mcp
```

### Option 4 — Build from source

```bash
git clone https://github.com/furkankoykiran/coderlegion-mcp.git
cd coderlegion-mcp
npm install
npm run build
node build/index.js
```

---

## Configuration

The server is configured entirely via environment variables — no config file needed.

| Variable | Default | Description |
|---|---|---|
| `CODERLEGION_PHPSESSID` | *(empty)* | PHP session ID — **required** |
| `CODERLEGION_QA_SESSION` | *(empty)* | Q2A session cookie — **required** |
| `CODERLEGION_QA_NOTICED` | `1` | Notice acknowledgement cookie |

### Getting your cookies

1. Log in to [coderlegion.com](https://coderlegion.com) in your browser
2. Open **Developer Tools** (F12) > **Application** > **Cookies** > `https://coderlegion.com`
3. Copy the values for `PHPSESSID` and `qa_session`

---

## MCP Client Setup

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "coderlegion": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/coderlegion-mcp"],
      "env": {
        "CODERLEGION_PHPSESSID": "your-php-session-id",
        "CODERLEGION_QA_SESSION": "your-qa-session-value"
      }
    }
  }
}
```

### VS Code (Cline / Continue)

Add to your MCP server settings:

```json
{
  "coderlegion": {
    "command": "npx",
    "args": ["-y", "@furkankoykiran/coderlegion-mcp"],
    "env": {
      "CODERLEGION_PHPSESSID": "your-php-session-id",
      "CODERLEGION_QA_SESSION": "your-qa-session-value"
    }
  }
}
```

### Built from source

```json
{
  "coderlegion": {
    "command": "node",
    "args": ["/absolute/path/to/coderlegion-mcp/build/index.js"],
    "env": {
      "CODERLEGION_PHPSESSID": "your-php-session-id",
      "CODERLEGION_QA_SESSION": "your-qa-session-value"
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add -s user coderlegion \
  -e CODERLEGION_PHPSESSID=your-php-session-id \
  -e CODERLEGION_QA_SESSION=your-qa-session-value \
  -- npx -y @furkankoykiran/coderlegion-mcp
```

---

## Available Tools

### Posts

#### `create_post`
Create a new post on CoderLegion. Supports Articles, Tutorials, Launches, and Videos with Markdown content, scheduling, and category-specific fields.

> **Note:** CoderLegion enforces a maximum of **4 tags** per post.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `title` | string | Yes | Post title |
| `content` | string | Yes | Post content in Markdown |
| `tags` | string | Yes | Comma-separated tags, max 4 (e.g. `python,automation,mcp`) |
| `category` | enum | Yes | `2` Articles, `5` Tutorials, `1971` Launches, `2005` Videos |
| `draft` | boolean | No | Save as draft (default: false) |
| `schedule_time` | string | No | Publish time: `YYYY-MM-DDThh:mm` |
| `schedule_utc` | string | No | Timezone offset in minutes for scheduling |
| `source_url` | string | No | Source URL for attribution |
| `os_type` | enum | No | `Project` or `Product` (Launches only) |
| `os_tagline` | string | No | Short tagline (Launches only) |
| `repo_url` | string | No | Repository URL (Launches only) |
| `web_url` | string | No | Website/demo URL (Launches only) |
| `os_status` | enum | No | `Active`, `Development`, `Experimental`, `Archived`, `None` (Launches only) |
| `os_license` | enum | No | `1` MIT, `2` Apache 2.0, `3` GPL v3, `4` BSD, `5` Other (Launches only) |
| `os_availability` | enum | No | `Free`, `Paid`, `Trial`, `None` (Launches only) |
| `vdo_type` | string | No | Video type e.g. `Tutorials`, `Product Demos` (Videos only) |
| `vdo_url` | string | No | Video URL e.g. YouTube link (Videos only) |

#### `edit_post`
Edit an existing post's title, content, tags, or category. Only the fields you provide are changed; everything else remains as-is.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Post ID (numeric) |
| `slug` | string | Yes | Post URL slug |
| `title` | string | No | New title |
| `content` | string | No | New Markdown content |
| `tags` | string | No | New comma-separated tags |
| `category` | enum | No | New category ID |

#### `delete_post`
Hide (soft-delete) a post. The post becomes invisible to other users but is not permanently removed.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Post ID (numeric) |
| `slug` | string | Yes | Post URL slug |

#### `get_post`
Retrieve a post's title, content snippet, tags, and author information.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Post ID (numeric) |
| `slug` | string | Yes | Post URL slug |

#### `list_posts`
Retrieve all posts by a specific CoderLegion user.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `username` | string | Yes | CoderLegion username |

#### `add_comment`
Add a Markdown comment to a post thread.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Post ID (numeric) |
| `slug` | string | Yes | Post URL slug |
| `content` | string | Yes | Comment text in Markdown |
| `comment_id` | string | Yes | Comment thread ID (from the post page) |

---

### Profile

#### `get_profile`
Get the authenticated user's CoderLegion profile information — name, tagline, location, website, about, skills, interests, achievements, fun fact, and quote. No parameters required.

#### `edit_profile`
Edit the authenticated user's profile. Only the fields you provide are updated; others remain unchanged.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Full display name |
| `tagline` | string | No | Short tagline/headline shown under the name |
| `about` | string | No | About/bio section |
| `location` | string | No | Location (e.g. `Istanbul, Türkiye`) |
| `website` | string | No | Personal website URL |
| `skills` | string | No | Skills description |
| `interests` | string | No | Interests description |
| `achievements` | string | No | Achievements description |
| `fun_fact` | string | No | Fun fact about you |
| `quote` | string | No | Favorite quote |

---

### Search

#### `search_posts`
Full-text search across all CoderLegion posts.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Search query |

#### `browse_tag`
Browse posts filtered by a specific tag.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `tag` | string | Yes | Tag name (e.g. `python`, `javascript`) |

#### `get_categories`
Retrieve all post categories with their IDs and descriptions. No parameters required.

---

### Social

#### `react_to_post`
React to a post with a like or love. Calling again on the same post toggles the reaction off.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `post_id` | string | Yes | Post ID to react to |
| `type` | enum | Yes | `like` or `love` |

#### `get_notifications`
Retrieve your notification feed (comments, reactions, follows). No parameters required.

#### `get_activity_feed`
Retrieve the social activity feed from followed users. No parameters required.

---

## Development

```bash
# Clone and install
git clone https://github.com/furkankoykiran/coderlegion-mcp.git
cd coderlegion-mcp
npm install

# Run in development mode (auto-reloads on change)
npm run dev

# Type-check
npm run typecheck

# Build for production
npm run build
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

Set the environment variables in the Inspector UI and verify all 13 tools are listed.

---

## Contributing

Contributions are welcome. Please read the [contributing guidelines](.github/PULL_REQUEST_TEMPLATE.md) and open an issue before submitting a pull request for significant changes.

---

## License

MIT — see [LICENSE](LICENSE).