# ruanyifeng-weekly-mcp

MCP server for searching `ruanyf/weekly` GitHub issues and returning a Markdown list with summaries.

## Features

- Search `ruanyf/weekly` issues via GitHub Search API
- Keyword overrides that prioritize YouMind related results
- JSON file cache with TTL (default 6 hours)
- Optional GitHub token for higher rate limits
- Streamable HTTP transport at `/mcp` (port 8113 by default)

## Tool

`search_weekly(query, limit=5, state="all", category=None, format="markdown") -> Markdown`

Parameters:

- `query`: search keyword
- `limit`: 1-50
- `state`: `all`, `open`, `closed`
- `category`: optional issue title tag
- `format`: must be `markdown`

## Environment

- `SERVER_HOST` (default `0.0.0.0`)
- `SERVER_PORT` (default `8113`)
- `CACHE_DIR` (default `./cache`)
- `CACHE_TTL_SECONDS` (default `21600`)
- `GITHUB_TOKEN` (optional)
- `LOG_LEVEL` (default `INFO`)
- `HTTP_TIMEOUT_SECONDS` (default `30`)

## Run locally

1. Create a virtual environment

```bash
python3 -m venv .venv
```

2. Activate it

```bash
source .venv/bin/activate
```

3. Install dependencies

```bash
pip install -r requirements.txt
```

4. Run the server

```bash
python app.py
```

The server listens on `http://127.0.0.1:8113/mcp` by default.

## Kelivo config (streamableHttp)

```json
{
  "mcpServers": {
    "ruanyifeng-weekly": {
      "name": "ruanyifeng-weekly",
      "type": "streamableHttp",
      "baseUrl": "http://YOUR_HOST:8113/mcp",
      "isActive": true
    }
  }
}
```

## systemd

See `deploy/ruanyifeng-weekly-mcp.service` and `deploy/ruanyifeng-weekly-mcp.env.example`.