DEV Community: Furkan Köykıran

GitHub Actions Self-Hosted Runner on Linux: Setup Guide

Furkan Köykıran — Wed, 06 May 2026 15:53:45 +0000

GitHub Actions gives private repositories a monthly quota of free minutes: 2,000 on the Free plan, 3,000 on Pro and Team. Run a multi-step CI pipeline on every push and every PR and the quota goes faster than you'd expect. Mine ran out in May 2026. Instead of paying for more minutes, I turned a Linux server I already had running into a self-hosted runner. This guide walks through the setup step by step: a dedicated user, checksum verification, a systemd service, labels, and the security cost of a runner that keeps its disk.

Why a self-hosted runner

According to GitHub's billing docs, jobs on self-hosted runners don't consume Actions minutes. Past the quota, a standard Linux runner costs $0.006 a minute. My server was on anyway, so the extra cost was CPU and disk.

There's a second benefit: the runner's disk persists between jobs. In my project the first run was slow because Poetry installed every dependency from scratch. After that, runs were noticeably faster because the virtualenv was still there. That persistence is also the biggest downside, which I'll come back to in the security section.

It helps to know how the runner talks to GitHub. It opens an outbound HTTPS connection and waits for work, so you don't need to open any inbound ports on the server:

Create a dedicated user

Don't run the runner as root; config.sh refuses to anyway. Create a system user for it:

sudo useradd -r -m -d /opt/github-runner -s /bin/bash \
  -c "GitHub Actions Runner" github-runner

-r makes it a system account and -m -d creates its home at /opt/github-runner. The account has no password, so nobody can log in with one, and it has no sudo rights. I give it /bin/bash because the next steps run as this user.

Download the runner and verify its hash

Do everything from here on as the runner user, so files get the right owner from the start:

sudo -iu github-runner
cd /opt/github-runner

VERSION=2.338.1
curl -fsSLO "https://github.com/actions/runner/releases/download/v${VERSION}/actions-runner-linux-x64-${VERSION}.tar.gz"

echo "08e9ccb3604d2462c24b5e33604dc30810296ca15cc65f23cffd4317eb144c37  actions-runner-linux-x64-${VERSION}.tar.gz" | sha256sum -c

tar xzf "actions-runner-linux-x64-${VERSION}.tar.gz"

The version and hash in the example belong to runner 2.338.1. Every release lists the hash for each package in its notes, right below the Linux x64 install commands:

Use the current version from the releases page and the hash from that release. You're downloading a binary that will run code on your server; don't skip the checksum.

Register the runner with your repository

Repository → Settings → Actions → Runners → New self-hosted runner shows a registration token. It's valid for one hour, so have the command ready before you generate it:

./config.sh \
  --url https://github.com/YOUR_USER/YOUR_REPO \
  --token YOUR_REGISTRATION_TOKEN \
  --name prod-server-01 \
  --labels prod \
  --unattended

The runner adds the self-hosted, linux and x64 labels on its own, so --labels only needs your custom ones. --unattended skips the interactive prompts. On success you'll see something like:

√ Connected to GitHub
√ Runner successfully added
√ Settings Saved

Then exit back to your own user.

Install it as a systemd service

svc.sh in the runner folder generates a systemd unit. Run it as root and tell it which user the service runs as:

cd /opt/github-runner
sudo ./svc.sh install github-runner
sudo ./svc.sh start
sudo ./svc.sh status

Logs go to journald:

sudo journalctl -u 'actions.runner.*' -n 50 --no-pager

Look for Listening for Jobs. Once that line shows up, the runner is waiting for work, and it appears as "Idle" in the repository's Runners list.

Point your workflows at it

Replace runs-on with the labels:

jobs:
  lint:
    runs-on: [self-hosted, linux, prod]
    steps:
      - uses: actions/checkout@v7
      - run: poetry install --no-interaction
      - run: poetry run ruff check .

A job goes to a runner that has every label in the list. With several servers, labels like prod and staging let you choose where each job runs.

When I opened my first PR after the switch, the Actions page showed Running job: Backend Lint (ruff). The job was running on the server in front of me, not on a VM spun up somewhere in Azure. The whole setup, from creating the user to updating the workflow files, took about 20 minutes.

Security: the cost of a persistent runner

GitHub-hosted runners start every job on a fresh VM. A self-hosted runner doesn't. Anything one job leaves on disk is there for the next one. These are the rules I follow:

Don't use self-hosted runners on public repositories. A pull request from a fork can change your workflow and run code on your server, and GitHub's secure use guide says as much. My runner only serves private repos.
Lock the runner directory to the runner user: sudo chown -R github-runner:github-runner /opt/github-runner and sudo chmod 700 /opt/github-runner.
Keep the runner user out of sudoers. If a job really needs a root command, write a narrow sudoers rule for that one command.
Adding the runner user to the docker group is effectively giving it root. If jobs need Docker, make that choice knowingly or use rootless Docker.
Avoid steps that write secrets to disk, and delete them at the end of the job if you must. The next job sees the same disk.
If every job needs a clean start, register the runner with --ephemeral. It takes one job and then deregisters. The trade-off is that something has to register a new runner for each job, usually a script or Actions Runner Controller.

By default the runner downloads and installs new versions itself. Leave that on: GitHub stops sending jobs to runners that fall too far behind. OS patches are still your job.

To remove the runner, stop the service first, then delete the registration:

cd /opt/github-runner
sudo ./svc.sh stop
sudo ./svc.sh uninstall
sudo -u github-runner ./config.sh remove --token YOUR_REMOVAL_TOKEN

You get the removal token from the runner's menu on the Runners page.

Which one when

	GitHub-hosted	Self-hosted
Cost	Free within quota, then per minute	No Actions minutes, you pay for the server
Maintenance	None	Runner and OS updates
Speed	Setup and cache download every job	Fast after the first job thanks to local cache
Isolation	Fresh VM every job	Jobs share the same disk
Network	GitHub's network	Your network, easy access to internal services

If you're under the quota, GitHub-hosted runners are the right default. If you regularly blow through it and have a server sitting idle, a self-hosted runner makes sense as long as you follow the security rules above.

Where to go next

My awesome-trending-repos post shows a cron-driven Actions workflow that deploys to GitHub Pages, and the GitLab to GitHub migration story compares GitHub Actions with GitLab CI from the time I had to use both. For the official steps, GitHub's guide to adding self-hosted runners is the most current source.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

freqtrade-mcp: Freqtrade Botuma Claude Üzerinden Sormak

Furkan Köykıran — Sat, 04 Apr 2026 14:14:52 +0000

Bir Freqtrade botu çalıştırıyorum. Strateji hazır, bot işini yapıyor, benim bakmama gerek yok. Teoride. Pratikte gece on birde FreqUI'yı açıp sekmelere tıklıyor, bir sayıya bakıp kapatıyor, on beş dakika sonra yine açıyordum.

Claude zaten açıktı ve botun düzgün bir REST API'si vardı. Aradaki köprüyü freqtrade-mcp adıyla yazdım: Freqtrade'in REST API'sini MCP araçları olarak sunan bir TypeScript MCP sunucusu. Claude Desktop, Claude Code, Cursor ve Cline gibi Model Context Protocol konuşan her istemciyle çalışıyor. 1.0.0 sürümünü 4 Nisan 2026'da npm'e yayınladım.

Ne işe yarıyor

Botla ilgili sorduğum sorular genelde şunlar:

"Bu ay kârda mıyım?"

"Açık pozisyonlarda zararda olan var mı?"

"BTC/USDT 4 saatlikte son 50 mum nasıl görünüyor?"

Claude her soruyu ilgili araca çeviriyor, Freqtrade'den gelen JSON'u okuyup özetliyor. Sayıları kendim ayıklamak zorunda kalmıyorum. Araçlar altı gruba ayrılıyor:

Grup	Araçlar
Hesap	`get_profit_stats`, `get_balance`, `get_performance`
İşlemler	`get_open_trades`, `get_trade`, `get_trade_history`
Piyasa verisi	`get_market_data`
Çift listeleri	`get_whitelist`, `get_blacklist`, `add_to_blacklist`, `remove_from_blacklist`
İşlem açma/kapama	`execute_trade`, `force_exit_trade`
Bot yönetimi	`start_bot`, `stop_bot`, `reload_config`, `get_bot_info`, `get_locks`, `delete_lock`

Kodda toplam 19 araç var. README hâlâ "15 araç" diyor, onu da düzeltmem gerekiyor.

Birkaç pratik not:

get_market_data, Freqtrade'in /pair_candles endpoint'ini kullanıyor. Bu endpoint botun kendi analiz ettiği mum verisini döndürüyor, yani pratikte yalnızca botun takip ettiği çiftler için çalışıyor.
get_trade_history ve get_market_data en fazla 500 kayıt döndürüyor.
get_bot_info, sürüm bilgisini son strateji döngüsünün zamanıyla birlikte veriyor. "Bot ayakta mı, yoksa sessizce takılmış mı?" sorusunun cevabı burada.

Mimari

Sunucu, istemciyle stdio üzerinden konuşan tek bir Node.js süreci. Freqtrade'e HTTP Basic Auth ile /api/v1 altından bağlanıyor:

Kod üç katmanlı:

src/client.ts: Freqtrade API'si için tipli bir HTTP istemcisi. Node 18+ ile gelen fetch'i kullanıyor, her isteği AbortController ile 10 saniyede kesiyor ve 2xx dışı yanıtlarda Freqtrade'in detail alanını hata mesajına ekliyor.
src/tools/*.ts: Her grup için bir dosya. Her araç parametrelerini bir zod şemasıyla tanımlıyor.
src/index.ts: İstemciyi ortam değişkenlerinden kurup araçları kaydediyor ve StdioServerTransport ile bağlanıyor.

Repo bu yüzden küçük: src/ altında kod, yanında bir .env.example ve CI ile npm yayını için .github/ klasörü.

Bir aracın tamamı şu kadar:

server.tool(
  'get_trade',
  'Retrieve detailed information about a specific trade by its ID, including full history, fees, and profit/loss.',
  {
    trade_id: z.number().int().positive().describe('The numeric trade ID to look up.'),
  },
  async ({ trade_id }) => {
    try {
      const data = await client.getTrade(trade_id);
      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
    } catch (err) {
      return {
        content: [{ type: 'text', text: `Error fetching trade ${trade_id}: ${(err as Error).message}` }],
        isError: true,
      };
    }
  },
);

Hataları fırlatmak yerine isError: true ile döndürüyorum. Model böylece "trade 42 bulunamadı" mesajını görüp kullanıcıya düzgün bir cevap verebiliyor ve oturum düşmüyor. Modelin aracı ne zaman seçeceğini de açıklama metinleri belirliyor. execute_trade açıklamasına "100 USDT'lik BTC al" gibi doğal dil örneklerini ve bunların hangi parametrelere karşılık geldiğini yazdım.

Bugün yeniden yazsam tek bir şeyi değiştirirdim. MCP TypeScript SDK'nın yeni sürümleri server.tool() yerine registerTool() kullanmayı öneriyor. Sunucu 1.x SDK ile sorunsuz çalışıyor, ama yeni bir projeye registerTool() ile başlardım.

Kurulum

Önce Freqtrade'in REST API'sini açın, varsayılan olarak kapalı geliyor. config.json içine şunu ekleyin:

"api_server": {
  "enabled": true,
  "listen_ip_address": "127.0.0.1",
  "listen_port": 8080,
  "verbosity": "error",
  "enable_openapi": false,
  "jwt_secret_key": "rastgele-uzun-bir-deger",
  "username": "Freqtrader",
  "password": "GucluBirSifre"
}

listen_ip_address değerini 127.0.0.1 bırakın. API'yi internete açarsanız botunuz ve borsa hesabınız tek bir şifreye kalır. Freqtrade dokümantasyonu da aynı uyarıyı yapıyor:

Sonra Claude Desktop yapılandırmasına (claude_desktop_config.json) sunucuyu ekleyin:

{
  "mcpServers": {
    "freqtrade": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/freqtrade-mcp"],
      "env": {
        "FREQTRADE_API_URL": "http://127.0.0.1:8080",
        "FREQTRADE_USERNAME": "Freqtrader",
        "FREQTRADE_PASSWORD": "GucluBirSifre"
      }
    }
  }
}

Claude Desktop'ı yeniden başlatınca araçlar listede görünüyor. Claude Code kullanıyorsanız aynı şeyi tek komutla yapabilirsiniz:

claude mcp add freqtrade \
  -e FREQTRADE_API_URL=http://127.0.0.1:8080 \
  -e FREQTRADE_USERNAME=Freqtrader \
  -e FREQTRADE_PASSWORD=GucluBirSifre \
  -- npx -y @furkankoykiran/freqtrade-mcp

Araçları bir istemciye bağlamadan önce denemek isterseniz MCP Inspector işinizi görür: npx @modelcontextprotocol/inspector npx -y @furkankoykiran/freqtrade-mcp.

Canlı işlemde dikkat edilecekler

execute_trade ve force_exit_trade stratejiyi atlayıp doğrudan Freqtrade'in /forceenter ve /forceexit endpoint'lerini çağırıyor. Sunucuda onay adımı yok.

Warning:
Bot canlı moddaysa bu araçlar gerçek borsada, gerçek parayla, geri alınamayan bir emir veriyor.

Güvenmeden önce şunları bilmeniz gerekiyor:

Freqtrade /forceenter çağrılarını yalnızca config'te force_entry_enable: true varsa kabul ediyor. Bu ayar kapalıyken execute_trade hata döndürüyor. Ayarı bilerek açmanız gerekiyor.
side: "short" yalnızca futures ya da margin modunda çalışan botlarda anlamlı. Spot modda short açamazsınız.
Önce dry_run: true ile deneyin. Freqtrade bu modda emirleri simüle ediyor, araçların davranışını risksiz görürsünüz.
Claude Desktop ve Claude Code araç çağrılarından önce izin istiyor. İşlem açan araçlar için "her zaman izin ver" seçeneğini hiç kullanmıyorum.

Kodu ve sonraki adımlar

Çözmek istediğim şey basitti: FreqUI'yı açmadan bota bakabilmek. REST API zaten oradaydı, MCP sunucusu onu sohbete taşıdı. "Acaba bir şey değişti mi" hissi geçmedi, ama sormak artık tek bir cümle.

Kod MIT lisanslı ve GitHub'da, projenin özeti de proje sayfamda. Kendi botunuza bağlamadan önce bir hafta dry_run: true ile çalıştırıp get_profit_stats ve get_open_trades sonuçlarını FreqUI ile karşılaştırın. Python tarafında bot geliştirmeyle ilgileniyorsanız Python ile Telegram trading botu ve yapay zekâ destekli trading stratejileri yazılarına, başka bir MCP sunucusunu nasıl sardığımı görmek için de CLI-Anything katkıma bakabilirsiniz.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

freqtrade-mcp: An MCP Server for Your Freqtrade Bot

Furkan Köykıran — Sat, 04 Apr 2026 14:14:38 +0000

I run a Freqtrade bot. Like most people with a trading bot, I tell myself I don't check it all the time, and then I check it all the time: open FreqUI, click through tabs, look at one number, close the tab, open it again fifteen minutes later.

Claude was already open, and the bot already had a perfectly good REST API. So I wrote freqtrade-mcp, a TypeScript MCP server that exposes Freqtrade's REST API as MCP tools. It works with Claude Desktop, Claude Code, Cursor, Cline and anything else that speaks the Model Context Protocol. Version 1.0.0 went to npm on April 4, 2026.

What it does

The questions I actually ask look like this:

"Am I up this month?"

"Are any open trades in the red?"

"What do the last 50 BTC/USDT candles on the 4h look like?"

Claude maps each question to a tool, reads the JSON that comes back from Freqtrade and summarizes it, so I don't have to parse numbers at 11pm. The tools fall into six groups:

Group	Tools
Account	`get_profit_stats`, `get_balance`, `get_performance`
Trades	`get_open_trades`, `get_trade`, `get_trade_history`
Market data	`get_market_data`
Pair lists	`get_whitelist`, `get_blacklist`, `add_to_blacklist`, `remove_from_blacklist`
Execution	`execute_trade`, `force_exit_trade`
Lifecycle	`start_bot`, `stop_bot`, `reload_config`, `get_bot_info`, `get_locks`, `delete_lock`

That's 19 tools in the code. The README still says 15, which is on my list to fix.

A few practical notes:

get_market_data uses Freqtrade's /pair_candles endpoint, which returns the candle data the bot has analyzed. In practice that means pairs the bot is tracking, not any pair on the exchange.
get_trade_history and get_market_data return at most 500 rows.
get_bot_info returns the bot version together with the time of the last strategy cycle. That answers "is the bot running, or has it been silently stuck?"

Architecture

The server is a single Node.js process that talks stdio to the client and HTTP Basic Auth to Freqtrade under /api/v1:

The code has three layers:

src/client.ts is a typed HTTP client for the Freqtrade API. It uses the fetch built into Node 18+, aborts each request after 10 seconds with an AbortController, and puts Freqtrade's detail field into the error message on non-2xx responses.
src/tools/*.ts has one file per group, and each tool declares its parameters with a zod schema.
src/index.ts builds the client from environment variables, registers the tools and connects a StdioServerTransport.

That keeps the repo small: the code under src/, a .env.example, and a .github/ folder for CI and the npm release.

A complete tool is this short:

server.tool(
  'get_trade',
  'Retrieve detailed information about a specific trade by its ID, including full history, fees, and profit/loss.',
  {
    trade_id: z.number().int().positive().describe('The numeric trade ID to look up.'),
  },
  async ({ trade_id }) => {
    try {
      const data = await client.getTrade(trade_id);
      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
    } catch (err) {
      return {
        content: [{ type: 'text', text: `Error fetching trade ${trade_id}: ${(err as Error).message}` }],
        isError: true,
      };
    }
  },
);

I return errors with isError: true instead of throwing them. The model sees "trade 42 not found", can tell the user something sensible, and the session stays up. The descriptions matter too, because they decide when the model picks a tool. For execute_trade I put natural-language examples like "buy 100 USDT of BTC" in the description, along with the parameters each one maps to.

If I started it today I'd change one thing: newer releases of the MCP TypeScript SDK recommend registerTool() over server.tool(). The server works fine on the 1.x SDK, but a new project should start with registerTool().

Setup

First, turn on Freqtrade's REST API, which is off by default. In config.json:

"api_server": {
  "enabled": true,
  "listen_ip_address": "127.0.0.1",
  "listen_port": 8080,
  "verbosity": "error",
  "enable_openapi": false,
  "jwt_secret_key": "some-long-random-value",
  "username": "Freqtrader",
  "password": "YourStrongPassword"
}

Keep listen_ip_address at 127.0.0.1. Exposing the API to the internet puts your bot and your exchange account behind a single password. The Freqtrade docs say the same:

Then add the server to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "freqtrade": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/freqtrade-mcp"],
      "env": {
        "FREQTRADE_API_URL": "http://127.0.0.1:8080",
        "FREQTRADE_USERNAME": "Freqtrader",
        "FREQTRADE_PASSWORD": "YourStrongPassword"
      }
    }
  }
}

Restart Claude Desktop and the tools show up. With Claude Code it's one command:

claude mcp add freqtrade \
  -e FREQTRADE_API_URL=http://127.0.0.1:8080 \
  -e FREQTRADE_USERNAME=Freqtrader \
  -e FREQTRADE_PASSWORD=YourStrongPassword \
  -- npx -y @furkankoykiran/freqtrade-mcp

To poke at the tools before wiring them into a client, use the MCP Inspector: npx @modelcontextprotocol/inspector npx -y @furkankoykiran/freqtrade-mcp.

Live trading caveats

execute_trade and force_exit_trade skip the strategy and call Freqtrade's /forceenter and /forceexit endpoints directly. The server has no confirmation step.

Warning:
If the bot is live, these tools place a real order on a real exchange, and you can't take it back.

Things to know before you rely on it:

Freqtrade only accepts /forceenter when the config has force_entry_enable: true. Without it, execute_trade returns an error. Turning that on should be a deliberate choice.
side: "short" only makes sense for bots running in futures or margin mode. You can't short in spot mode.
Try everything with dry_run: true first. Freqtrade simulates the orders, so you can see how the tools behave without risk.
Claude Desktop and Claude Code ask for permission before tool calls. I never pick "always allow" for the tools that place orders.

Where the code is

What I wanted was simple: check the bot without opening FreqUI. The REST API was already there; the MCP server moved it into the chat. I still wonder whether something changed while I wasn't looking, but now finding out takes one sentence.

The code is MIT licensed and on GitHub, with a summary on my project page. Before you point it at your own bot, run it for a week with dry_run: true and compare what get_profit_stats and get_open_trades report with FreqUI. To see a different MCP integration, where I wrapped someone else's MCP server as a CLI, read my CLI-Anything contribution. If your Python services lean on async I/O the way trading bots do, the asyncio guide is a good next read.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

awesome-trending-repos: Tracking GitHub Trending Daily

Furkan Köykıran — Fri, 27 Mar 2026 20:12:20 +0000

awesome-trending-repos is a small project of mine that tracks GitHub Trending on its own. Every night at 00:00 UTC a GitHub Actions job scrapes the trending list, compares it with the previous day, commits the result as JSON and redeploys a React dashboard to GitHub Pages. It has run without me touching it since March 2026. This post walks through both versions of the project, the data pipeline, and the mistakes I made along the way.

Why I built it

I looked at the trending page most days but couldn't remember what was on it yesterday. Seeing which repos were new, which were climbing and which languages were hot meant keeping history somewhere. GitHub doesn't keep it for you, so I started keeping it myself.

Version 1: a script that wrote the README

The March 17, 2026 release was plain Node.js. scripts/update.js scraped the trending page and wrote everything straight into README.md: language breakdowns, rank changes, ASCII charts, the fastest risers. The last 7 days of data lived in .data/.

It worked, but a README is a poor data UI. No filters, no search, and the charts were text. Ten days later I split the interface out.

Version 2: JSON data, React front end

PR #5, merged on March 27, split the project in two. The script no longer touches the README; it only writes public/data/trending.json and public/data/feed.json, and the README became a static landing page. The front end is a single-page app that reads that JSON:

React 19 and Vite 6
Tailwind CSS v4 through the @tailwindcss/vite plugin
Framer Motion for transitions, Recharts for the language distribution chart
Language filter, instant search across name, owner and description, and a feed that lists each update

Here is the top of the live site. The Trending, Stats and Feed tabs, the language chips and the search box all read the same JSON:

With 25 repos, filtering doesn't need anything clever:

const q = searchQuery.toLowerCase();

const filteredRepos = repos.filter((repo) => {
  const matchesLang = filter === 'All' || repo.language === filter;
  const matchesSearch =
    repo.name.toLowerCase().includes(q) ||
    repo.owner.toLowerCase().includes(q) ||
    (repo.description ?? '').toLowerCase().includes(q);
  return matchesLang && matchesSearch;
});

The data pipeline

The real work happens in scripts/update.js:

It fetches github.com/trending/<language>?since=daily for 15 languages with axios and parses the HTML with cheerio. The all-languages page changed structure at some point, and going language by language turned out to be more reliable.
If that yields fewer than 25 repos, the GitHub Search API fills the gap.
Invalid entries and anything outside a list of popular languages are dropped.
If the list is still short, repos from the last 7 days of snapshots are added.
The result is compared with yesterday's snapshot: new entries, risers, fallers and a "rising star".
.data/history.json keeps at most 7 snapshots, and older snapshot files are deleted.

Two numbers in there are guesses. The Search API doesn't tell you how many stars a repo got today, so for repos that come from search I estimate daily stars as 1% of total stars. Repos pulled back in from history get half of their old daily count. Both are rough fillers, not measurements. Flagging them in the UI is on my list.

The GitHub Actions workflow

The workflow runs once a day on a cron, on manual dispatch, and on pushes that touch src/ or scripts/. It updates the data, builds, commits any changes and deploys to Pages. Here is a trimmed version of the one in the repo:

name: Update and Deploy Trends

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:
  push:
    branches: [main]
    paths: ['src/**', 'scripts/**', 'package.json', 'package-lock.json']

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  update-and-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: '22'
          cache: npm
      - run: npm ci
      - run: npm run update
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: npm run build
      - name: Commit data changes
        run: |
          if [ -z "$(git status --porcelain .data/ public/data/)" ]; then exit 0; fi
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          git add .data/ public/data/
          git commit -m "chore: update trending repositories [skip ci]"
          git push
      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./dist

  deploy:
    needs: update-and-build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

The file in the repo still pins checkout@v4, setup-node@v4, upload-pages-artifact@v3 and Node 20, which reached end of life in April 2026. If you're starting fresh, use the versions above.

A few details that pull their weight:

[skip ci] keeps the bot's commit from kicking off another run. Pushes made with GITHUB_TOKEN don't start new workflow runs anyway, but the marker costs nothing.
concurrency stops two deploys from racing each other.
The build runs after the update. Vite copies public/ into dist/, so the site always ships with that day's JSON.

My commit step above adds the whole public/data/ folder. The workflow in the repo only commits public/data/trending.json and leaves feed.json out. So each run reads the stale feed from the repo and appends one entry, and the live feed always shows the March 27 entry plus today's. The fix is the one line shown above.

Vite on GitHub Pages: the base path

The site is a project page served under /awesome-trending-repos/. If Vite doesn't know that, the built asset URLs point at the domain root and everything 404s in production:

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  base: '/awesome-trending-repos/',
});

Vite already adds content hashes to file names in production builds, so you don't need extra rollupOptions for cache busting. The app loads its data with fetch('./data/trending.json'), a relative path that works with any base.

The custom domain mistake

Putting the root domain in a project's public/CNAME is a common mistake, and this repo had exactly that file. furkankoykiran.com.tr belongs to my user site (furkankoykiran.github.io). Project pages inherit that domain automatically and are served at furkankoykiran.com.tr/awesome-trending-repos/. A project repo with the root domain in its own CNAME is trying to claim the same domain as the user site.

PR #7 removed public/CNAME and dist/CNAME. With actions/deploy-pages, a CNAME file inside the artifact is ignored anyway; the domain comes from Settings → Pages → Custom domain, and for a project page that field should stay empty.

What's next

The project still runs every day. Next on the list: fix the feed bug, mark estimated star counts in the UI, and bump the workflow's action versions.

The live site is at furkankoykiran.com.tr/awesome-trending-repos, and there's a summary on the project page. If your Actions minutes are running low, my self-hosted runner post shows how I moved CI onto my own server. The story of how this blog ended up on GitHub Pages is in my GitLab and GitHub migration post.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

awesome-trending-repos: GitHub Trending'i Her Gün İzlemek

Furkan Köykıran — Fri, 27 Mar 2026 20:12:18 +0000

awesome-trending-repos, GitHub Trending sayfasını her gün kendiliğinden takip eden küçük bir projem. Her gece UTC 00:00'da bir GitHub Actions işi trending listesini çekiyor, bir önceki günle karşılaştırıyor, sonucu JSON olarak repoya yazıyor ve React ile yazdığım arayüzü GitHub Pages'e yeniden yayınlıyor. Mart 2026'dan beri elle dokunmadan çalışıyor. Bu yazıda projenin iki sürümünü, veri hattını ve yolda yaptığım hataları anlatıyorum.

Neden yazdım

Trending sayfasına her gün bakıyordum ama dünkü listeyi hatırlamıyordum. Hangi repo yeni girdi, hangisi yükseliyor, hangi dil öne çıkıyor, bunları görmek için geçmişi bir yerde tutmak gerekiyordu. GitHub bunu sunmuyor, bu yüzden kendim tutmaya karar verdim.

Birinci sürüm: README'ye yazan bir script

17 Mart 2026'daki ilk sürüm tamamen Node.js'ti. scripts/update.js trending sayfasını kazıyıp sonucu doğrudan README.md dosyasına yazıyordu: dil kırılımları, sıralama değişiklikleri, ASCII grafikler, en hızlı yükselen repolar. Son 7 günün verisi .data/ klasöründe tutuluyordu.

Çalışıyordu ama README bir veri arayüzü olarak sınırlı. Filtre yok, arama yok, grafikler metin. On gün sonra arayüzü ayırmaya karar verdim.

İkinci sürüm: JSON veri, React arayüz

27 Mart'ta merge ettiğim PR #5 projeyi ikiye böldü. Script artık README'ye dokunmuyor, yalnızca public/data/trending.json ve public/data/feed.json dosyalarını üretiyor. README statik bir tanıtım sayfasına dönüştü. Arayüz ise bu JSON'u okuyan tek sayfalık bir uygulama:

React 19 ve Vite 6
Tailwind CSS v4 (@tailwindcss/vite eklentisiyle)
Framer Motion ile geçişler, Recharts ile dil dağılımı grafiği
Dile göre filtreleme, isim/sahip/açıklamada anlık arama ve her güncellemenin listelendiği bir akış (feed)

Canlı sitenin üst kısmı aşağıda. Trending, Stats ve Feed sekmeleri, dil filtreleri ve arama kutusu aynı JSON'dan besleniyor:

Filtreleme kodu basit, 25 repo için başka bir şeye gerek yok:

const q = searchQuery.toLowerCase();

const filteredRepos = repos.filter((repo) => {
  const matchesLang = filter === 'All' || repo.language === filter;
  const matchesSearch =
    repo.name.toLowerCase().includes(q) ||
    repo.owner.toLowerCase().includes(q) ||
    (repo.description ?? '').toLowerCase().includes(q);
  return matchesLang && matchesSearch;
});

Veri hattı

Asıl iş scripts/update.js içinde. Adımları sırasıyla:

15 dil için github.com/trending/<dil>?since=daily sayfaları axios ile çekilip cheerio ile ayrıştırılıyor. Dilsiz genel sayfa yapısı değiştiği için dil dil gitmek daha sağlam çıktı.
25 repoya ulaşılamazsa GitHub Search API devreye giriyor.
Geçersiz kayıtlar ve popüler dil listesi dışındakiler eleniyor.
Hâlâ eksik varsa son 7 günün snapshot'larından repo ekleniyor.
Sonuç dünkü snapshot'la karşılaştırılıyor: yeni girenler, yükselenler, düşenler, günün yıldızı.
.data/history.json en fazla 7 snapshot tutuyor, eski snapshot dosyaları siliniyor.

İki sayı ölçüm değil, tahmin. Search API "bugün kaç yıldız aldı" bilgisini vermiyor, bu yüzden oradan gelen repolar için günlük yıldızı toplam yıldızın %1'i olarak tahmin ediyorum. Geçmişten eklenen repolarda da eski günlük yıldızın yarısını kullanıyorum. İkisi de listeyi doldurmak için kaba tahminler, gerçek veri değil. Arayüzde bunları ayrı işaretlemek yapılacaklar listemde.

GitHub Actions workflow'u

Workflow günde bir kez cron ile, istendiğinde elle ve src/ ya da scripts/ değiştiğinde push ile çalışıyor. Önce veriyi güncelliyor, sonra build alıyor, değişiklik varsa commit atıyor ve Pages'e yayınlıyor. Repodaki halinin kısaltılmışı:

name: Update and Deploy Trends

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:
  push:
    branches: [main]
    paths: ['src/**', 'scripts/**', 'package.json', 'package-lock.json']

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  update-and-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: '22'
          cache: npm
      - run: npm ci
      - run: npm run update
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: npm run build
      - name: Commit data changes
        run: |
          if [ -z "$(git status --porcelain .data/ public/data/)" ]; then exit 0; fi
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          git add .data/ public/data/
          git commit -m "chore: update trending repositories [skip ci]"
          git push
      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./dist

  deploy:
    needs: update-and-build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

Repodaki dosya hâlâ checkout@v4, setup-node@v4, upload-pages-artifact@v3 ve Node 20 kullanıyor. Node 20'nin desteği Nisan 2026'da bitti. Sıfırdan kuruyorsanız yukarıdaki sürümleri kullanın.

Birkaç ayrıntı işe yarıyor:

[skip ci] olmadan botun commit'i workflow'u yeniden tetikleyebilir. GITHUB_TOKEN ile atılan push'lar zaten yeni workflow başlatmıyor ama işareti bırakmak zararsız.
concurrency aynı anda iki deploy'un çakışmasını önlüyor.
Build, update'ten sonra çalışıyor. Vite public/ içeriğini dist/ içine kopyaladığı için site her zaman günün JSON'uyla yayınlanıyor.

Yukarıdaki commit adımında public/data/ klasörünün tamamını ekliyorum. Repodaki workflow ise yalnızca public/data/trending.json dosyasını commit ediyor ve feed.json dışarıda kalıyor. Sonuç: her çalıştırma repodaki eski feed'i okuyup üstüne tek bir satır ekliyor. Canlı sitedeki akış bu yüzden hep 27 Mart kaydı ile günün kaydından oluşuyor. Düzeltmesi yukarıdaki gibi tek satır.

Vite ve GitHub Pages: base yolu

Site bir proje sayfası olarak /awesome-trending-repos/ altında yayınlanıyor. Vite'a bunu söylemezseniz build'deki asset yolları kökü gösterir ve production'da her şey 404 verir:

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  base: '/awesome-trending-repos/',
});

Vite production build'de dosya adlarına zaten içerik hash'i ekliyor, cache kırmak için ek bir rollupOptions ayarı gerekmiyor. Arayüz JSON'u fetch('./data/trending.json') ile göreli yoldan okuyor, bu da base ile uyumlu.

Özel alan adı hatası

Proje sayfasında public/CNAME dosyasına kök alan adını yazmak sık yapılan bir hata ve bu repoda da öyle bir dosya vardı. furkankoykiran.com.tr kullanıcı sitemin (furkankoykiran.github.io) alan adı. Proje sayfaları bu alan adını kendiliğinden devralıyor ve furkankoykiran.com.tr/awesome-trending-repos/ adresinden yayınlanıyor. Projenin kendi CNAME dosyasında kök alan adını taşıması, kullanıcı sitesiyle aynı adı sahiplenmeye çalışması demek.

PR #7 ile public/CNAME ve dist/CNAME dosyalarını sildim. actions/deploy-pages kullanıyorsanız artifact içindeki CNAME dosyası zaten yok sayılıyor. Alan adını repo ayarlarındaki Settings → Pages → Custom domain alanı belirliyor. Proje sayfası için bu alan boş kalmalı.

Sonraki adımlar

Proje her gün çalışmaya devam ediyor. Sıradaki işler: feed hatasını kapatmak, tahmini yıldız sayılarını arayüzde işaretlemek ve workflow sürümlerini güncellemek.

Canlı siteye furkankoykiran.com.tr/awesome-trending-repos adresinden, projenin özetine proje sayfasından bakabilirsiniz. GitHub Actions dakikalarınız bitiyorsa self-hosted runner yazım, daha büyük pipeline'lar için GitHub Actions CI/CD yazısı iyi bir devam olur. Bu blogun GitHub Pages yolculuğunu da GitLab ve GitHub macerası yazısında anlattım.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

CLI-Anything Browser Harness: My First MCP Backend PR

Furkan Köykıran — Sun, 22 Mar 2026 22:40:08 +0000

In March 2026 I sent a pull request that added browser automation to CLI-Anything. PR #118 became the project's first harness that talks to an MCP server instead of calling an application directly. This post covers how the harness is built, what came up in review, and the bugs that only showed up after it was merged.

CLI-Anything's premise is that if you wrap software in a clean command-line interface, AI agents can drive it. The repo has "harnesses" for GIMP, Blender, LibreOffice and dozens of other tools. Browsers were missing.

Issue #90: browsing a page like a filesystem

On March 16, @apireno, the author of DOMShell, opened issue #90. DOMShell is a Chrome extension plus MCP server that exposes Chrome's Accessibility Tree as a virtual filesystem, so an agent moves through a page with ls, cd, grep and click. In apireno's benchmarks with Claude, this cut API calls by half compared with screenshot-based browsing. That number is his; I didn't measure it myself.

The Accessibility Tree is the simplified tree the browser derives from the DOM for screen readers. Each node has a role such as button, link or textbox, and the CSS classes and wrapper divs are gone. That makes it less brittle than CSS selectors when a site's markup changes, and the page → section → element hierarchy maps cleanly onto directories.

In the issue thread, @omerarslan0 sketched an integration: DOMShell's MCP server as the backend, command groups like page on the CLI side, and state (URL, working directory) kept by the CLI. apireno asked to keep the filesystem-style commands rather than switch to selectors, and recommended the official mcp Python SDK over stdio. I built on that discussion and opened the PR on March 21.

How the harness is built

Most harnesses shell out to an application or call its API. This one puts an MCP client in the middle:

There are four command groups:

page: open, reload, back, forward, info
fs: ls, cd, cat, grep, pwd
act: click, type
session: status, daemon-start, daemon-stop

In use:

cli-anything-browser page open https://example.com
cli-anything-browser fs ls /
cli-anything-browser fs grep "Login"
cli-anything-browser act click /main/button[0]
cli-anything-browser --json fs ls /

Every one-shot command starts a fresh session. Stateful flows, like cd followed by a bare ls, belong in the REPL, which opens when you run cli-anything-browser with no arguments.

The MCP call in Python

When I wrote the PR, DOMShell exposed one MCP tool per command (domshell_ls, domshell_click and so on). DOMShell 2.0 collapsed those into a single domshell_execute tool, and the harness was updated for it. A minimal client for DOMShell 2.x looks like this:

import asyncio
import os

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="npx",
    args=[
        "-p", "@apireno/domshell", "domshell-proxy",
        "--port", os.environ.get("DOMSHELL_PORT", "3001"),
        "--token", os.environ["DOMSHELL_TOKEN"],
    ],
)


async def main() -> None:
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "domshell_execute", {"command": "ls", "group_id": "new"}
            )
            print(result.content[0].text)


asyncio.run(main())

domshell-proxy is a stdio bridge to a DOMShell server that is already running, and DOMSHELL_TOKEN is the token that server prints at startup. group_id: "new" asks DOMShell 2.x for an isolated tab group for the agent. None of this was in my original PR, and the section after the review explains why.

A sync CLI on top of an async SDK

The MCP Python SDK is fully async and Click commands are sync, so each command opens a short session inside asyncio.run() and closes it. The cost is spawning an npx subprocess on every command. To avoid that during interactive use I added a daemon mode: while the REPL runs, one MCP connection stays open and every command reuses it. It only works inside a single process. Separate CLI invocations don't share it, and the README says so.

Tests

Two layers. The 31 unit tests in test_core.py mock MCP responses and cover path resolution and session state, with no Chrome needed. The end-to-end tests in test_full_e2e.py drive a real Chrome with the DOMShell extension and only run when you ask for them:

pytest cli_anything/browser/tests/test_core.py -v
DOMSHELL_E2E=1 pytest cli_anything/browser/tests/test_full_e2e.py -v

The DOMSHELL_E2E gate came out of a Copilot comment. Before it, pytest could try to run npx during test collection.

Review

Copilot reviewed the PR twice, with 10 comments and then 9. The ones that mattered most:

A context manager leak in daemon mode. _start_daemon() called __aenter__ on stdio_client(...) without keeping a reference, and _stop_daemon() called __aexit__ on a brand-new client, so the original subprocess never shut down. I now keep the reference in a module-level _daemon_client_context.
page back and page forward replayed navigation from a local history list, which is always empty in one-shot mode. They now call DOMShell's own back and forward tools.
The REPL split quoted arguments. act type /path "Hello, World!" now goes through shlex.split().
act type echoed the typed text, which leaves passwords in terminal scrollback. It no longer does.
fs cd only updates the working directory when the backend reports success.

omerarslan0 listed 8 issues in his first review, all of which earlier commits had already fixed. I replied with the commit for each one, and he checked and approved. @yuh-yang asked me to fix the contributor field in registry.json, then approved and merged on March 22. Final size: 15 commits, 21 files, 3,095 lines added:

I also added an "MCP Backend Pattern" section to cli-anything-plugin/HARNESS.md so the next MCP integration has something to follow.

What broke after the merge

I learned the most from this PR after it was merged. Right after the merge, apireno tested the harness against a real DOMShell server. All 31 unit tests passed and 9 of 10 end-to-end tests passed, but several commands failed when he used them by hand:

In one-shot mode every command started a new npx @apireno/domshell process, which tried to bind ports 9876 and 3001. If another client such as Claude Desktop was already running DOMShell, every command failed.
I was sending the wrong parameter names to some tools (ls, cat, click).
DOMShell didn't support --version, which my availability check relied on. apireno fixed that on the DOMShell side.

apireno fixed the port and parameter problems in PR #135, merged on March 24, which moved the connection to the domshell-proxy bridge with token auth. My unit tests passed because they mocked a server interface that didn't match the real one. Pulling the tool schemas from the server with list_tools and building the mocks from them would have caught this before review.

Security hardening in PR #156

After I shared the contribution on LinkedIn, Ilhan Goktas pointed out several attack surfaces: SSRF through arbitrary navigation, prompt injection hidden in ARIA labels, and escaping the virtual filesystem. I followed up with PR #156, which omerarslan0 merged on April 7.

It added:

URL validation that blocks file://, javascript:, data: and vbscript: schemes
Optional blocking of private network addresses, switched on with an environment variable
A basic sanitizer for known prompt injection patterns in page content
42 security tests, plus security notes for agents in SKILL.md

The sanitizer catches obvious patterns and nothing more. If you give an agent a browser, treat every piece of page text as untrusted input.

Where the code went next

I wrote the harness, and most of the code that runs now has been through other hands since. apireno did the DOMShell 2.0 migration and the fixes after it, and other contributors followed. That's normal for open source, and it's a good reason to write code that's easy for the next person to change.

What I took away from this PR:

When you wrap an MCP server, run at least one end-to-end test against the real server before asking for a merge.
When you bridge an async SDK into a sync CLI, keep the connection lifecycle in one place. That's where the leaks come from. I go deeper into the asyncio side in my asyncio guide.
Answer review comments with the commit hash for each fix. It makes the reviewer's job much easier.

Where to go next

The code is in browser/agent-harness. For an MCP server I built from scratch, read the freqtrade-mcp post. For another open source contribution, with a very different codebase, see my Keploy contribution.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

CLI-Anything'e Tarayıcı Desteği: İlk MCP Backend Katkım

Furkan Köykıran — Sun, 22 Mar 2026 22:40:06 +0000

Mart 2026'da CLI-Anything projesine tarayıcı otomasyonu ekleyen bir PR gönderdim. PR #118, projede bir MCP sunucusunu backend olarak kullanan ilk "harness" oldu. Bu yazıda neyi neden öyle kurduğumu, review'da neler çıktığını ve merge'den sonra ortaya çıkan, benim kaçırdığım hataları anlatıyorum.

CLI-Anything'in fikri basit: bir yazılımı komut satırından yönetilebilir hale getirirsen, AI ajanları da onu kullanabilir. Projede GIMP, Blender, LibreOffice gibi uygulamalar için "harness" denen CLI sarmalayıcıları var. Tarayıcı listede yoktu.

Issue #90: tarayıcı neden dosya sistemi gibi gezilsin?

16 Mart 2026'da DOMShell'in geliştiricisi @apireno, issue #90'ı açtı. DOMShell, Chrome'un Accessibility Tree'sini sanal bir dosya sistemi olarak sunan bir Chrome eklentisi ve MCP sunucusu. Ajan sayfada ls, cd, grep, click gibi komutlarla dolaşıyor. apireno'nun Claude ile yaptığı ölçümlere göre bu yaklaşım, ekran görüntüsü tabanlı gezinmeye kıyasla API çağrılarını yarıya indiriyordu. Bu rakam onun benchmark'ı, ben ayrıca ölçmedim.

Accessibility Tree, tarayıcının ekran okuyucular için DOM'dan çıkardığı sadeleştirilmiş ağaç. Her öğe bir rol taşıyor: button, link, textbox. CSS sınıfları ve iç içe geçmiş div'ler burada yok, bu yüzden sayfa tasarımı değiştiğinde selector'lara göre daha az kırılıyor. Sayfa → bölümler → öğeler hiyerarşisi de bir dizin yapısına doğal olarak oturuyor.

Issue altında @omerarslan0 bir entegrasyon taslağı önerdi: DOMShell'in MCP sunucusu backend olacak, CLI tarafı page gibi komut grupları sunacak, durum (URL, çalışma dizini) CLI'da tutulacak. apireno da selector tabanlı komutlar yerine dosya sistemi komutlarının korunmasını ve resmi mcp Python SDK'sının stdio transport'uyla kullanılmasını önerdi. Ben bu konuşmanın üzerine implementasyonu yazıp 21 Mart'ta PR'ı açtım.

Harness'ın yapısı

Diğer harness'lar genelde uygulamanın kendi API'sini ya da CLI'ını çağırıyor. Burada araya bir MCP istemcisi giriyor:

Komutlar dört grupta toplandı:

page: open, reload, back, forward, info
fs: ls, cd, cat, grep, pwd
act: click, type
session: status, daemon-start, daemon-stop

Kullanımı şöyle:

cli-anything-browser page open https://example.com
cli-anything-browser fs ls /
cli-anything-browser fs grep "Login"
cli-anything-browser act click /main/button[0]
cli-anything-browser --json fs ls /

Her tek seferlik komut yeni bir oturumla başlıyor. cd yapıp ardından yolsuz ls çalıştırmak gibi durum gerektiren akışlar için REPL var (cli-anything-browser komutunu argümansız çalıştırınca açılıyor).

MCP çağrısı Python'da nasıl görünüyor

PR'ı yazdığım günlerde DOMShell her komut için ayrı bir MCP aracı sunuyordu (domshell_ls, domshell_click gibi). DOMShell 2.0 bunları tek bir domshell_execute aracında topladı ve harness da buna göre güncellendi. DOMShell 2.x ile çalışan minimal bir istemci şöyle:

import asyncio
import os

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="npx",
    args=[
        "-p", "@apireno/domshell", "domshell-proxy",
        "--port", os.environ.get("DOMSHELL_PORT", "3001"),
        "--token", os.environ["DOMSHELL_TOKEN"],
    ],
)


async def main() -> None:
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "domshell_execute", {"command": "ls", "group_id": "new"}
            )
            print(result.content[0].text)


asyncio.run(main())

domshell-proxy, zaten çalışan bir DOMShell sunucusuna stdio köprüsü kuruyor. DOMSHELL_TOKEN o sunucunun açılışta verdiği token. group_id: "new" ise DOMShell 2.x'te ajana ayrı bir sekme grubu açıyor. Bu ayrıntıların hiçbiri benim ilk PR'ımda yoktu, aşağıda nedenini anlatıyorum.

Senkron CLI, asenkron SDK

MCP Python SDK tamamen async. Click komutları ise senkron. Her komut kendi içinde asyncio.run() ile kısa bir oturum açıp kapatıyor. Bunun bedeli, her komutta npx ile alt süreç başlatmak. Bu yüzden bir de daemon modu ekledim: REPL açıkken tek bir MCP bağlantısı açık kalıyor ve bütün komutlar onu kullanıyor. Daemon modu yalnızca tek bir süreç içinde çalışıyor. Ayrı CLI çağrıları arasında bağlantı taşınmıyor, bunu README'ye de açıkça yazdım.

Testler

İki katman vardı. test_core.py içindeki 31 unit test MCP yanıtlarını mock'luyor, yol çözümlemeyi ve oturum durumunu test ediyordu. Chrome gerekmiyordu. test_full_e2e.py içindeki E2E testler ise gerçek Chrome ve DOMShell eklentisiyle çalışıyor ve yalnızca açıkça istendiğinde koşuyordu:

pytest cli_anything/browser/tests/test_core.py -v
DOMSHELL_E2E=1 pytest cli_anything/browser/tests/test_full_e2e.py -v

DOMSHELL_E2E bayrağını Copilot'un bir yorumundan sonra ekledim. Öncesinde test toplama aşaması bile npx çalıştırmaya kalkabiliyordu.

Review süreci

PR'a Copilot iki tur review yaptı: ilk turda 10, ikinci turda 9 yorum. Birkaçı gerçekten önemliydi:

Daemon modunda context manager sızıntısı. _start_daemon() içinde stdio_client(...) için __aenter__ çağrılıyor ama referans saklanmıyordu, _stop_daemon() ise yepyeni bir istemcide __aexit__ çağırıyordu. Asıl alt süreç hiç kapanmıyordu. Referansı _daemon_client_context adlı modül değişkeninde tutarak düzelttim.
page back ve page forward CLI içindeki yerel geçmişten yeniden navigasyon yapıyordu. Tek seferlik kullanımda geçmiş hep boş olduğu için çalışmıyordu. DOMShell'in kendi geri/ileri araçlarını çağıracak şekilde değiştirdim.
REPL'de tırnaklı argümanlar bölünüyordu. act type /path "Hello, World!" artık shlex.split() ile doğru ayrıştırılıyor.
act type yazılan metni ekrana basıyordu. Şifre yazdırırsanız terminal geçmişinde kalıyor. Artık basmıyor.
fs cd yalnızca backend başarılı yanıt verince çalışma dizinini değiştiriyor.

omerarslan0 ilk review'unda 8 madde sıraladı. Hepsi önceki commit'lerde düzeltilmişti, commit'leri tek tek eşleştirip cevap yazdım, o da kontrol edip onayladı. @yuh-yang registry.json'daki contributor alanının düzeltilmesini istedi, sonra PR'ı onaylayıp 22 Mart'ta merge etti. Toplam: 15 commit, 21 dosya, 3.095 satır ekleme:

Projenin cli-anything-plugin/HARNESS.md dosyasına da diğer MCP entegrasyonları için bir "MCP Backend Pattern" bölümü ekledim.

Merge'den sonra ne bozuldu

Bu PR'dan en çok şeyi merge'den sonra öğrendim. Merge'den hemen sonra apireno harness'ı gerçek DOMShell sunucusuna karşı test etti. 31 unit testin hepsi geçti, E2E'de 10 testten 9'u geçti. Elle denemelerde ise birkaç komut çalışmadı:

Tek seferlik modda her komut yeni bir npx @apireno/domshell süreci başlatıyordu ve bu süreç 9876 ile 3001 portlarını açmaya çalışıyordu. Claude Desktop gibi başka bir istemci DOMShell'i zaten çalıştırıyorsa bütün komutlar düşüyordu.
Bazı MCP araçlarına yanlış parametre adları gönderiyordum (ls, cat, click için).
--version desteği DOMShell'de yoktu, bunu apireno kendi tarafında düzeltti.

Port ve parametre sorunlarını apireno PR #135 ile düzeltti (24 Mart'ta merge edildi). Bağlantı modeli domshell-proxy köprüsüne ve token tabanlı kimlik doğrulamaya geçti. Yani benim unit testlerim mock'larla geçiyordu ama mock'lar sunucunun gerçek arayüzünü yansıtmıyordu. Bir MCP sunucusunu sararken araç şemalarını sunucudan list_tools ile çekip testleri ona göre kurmak bu hatayı baştan yakalardı.

Güvenlik sertleştirmesi: PR #156

LinkedIn'de bu katkıyı paylaştıktan sonra Ilhan Goktas birkaç saldırı yüzeyine dikkat çekti: rastgele URL açtırarak SSRF, ARIA etiketlerine gizlenmiş prompt injection, sanal dosya sisteminden kaçış. Bunun üzerine PR #156'yı açtım. omerarslan0 onu 7 Nisan'da merge etti.

PR şunları ekledi:

file://, javascript:, data: ve vbscript: şemalarını engelleyen URL doğrulaması
Bir ortam değişkeniyle açılabilen özel ağ engellemesi
Sayfa içeriğinde bilinen prompt injection kalıpları için basit bir temizleme katmanı
42 yeni güvenlik testi ve ajanlar için SKILL.md içine güvenlik notları

Temizleme katmanı yalnızca bariz kalıpları yakalıyor, prompt injection'ı tek başına çözmüyor. Bir ajana tarayıcı veriyorsanız sayfadaki her metni güvenilmeyen girdi olarak görmek zorundasınız.

Kodun sonraki hayatı

Harness'ı ilk ben yazdım, çalışan kodun büyük kısmı ise sonradan başkalarının elinden geçti. DOMShell 2.0 geçişini ve sonraki düzeltmeleri apireno yaptı, ardından başka katkıcılar da dokundu. Açık kaynakta bu olağan, bu yüzden bir sonraki kişinin kolayca değiştirebileceği kod yazmaya değer.

Bu PR'dan aklımda kalanlar:

Bir MCP sunucusunu sarıyorsanız gerçek sunucuya karşı en az bir uçtan uca test koşmadan merge istemeyin.
Async SDK'yı senkron CLI'a bağlarken bağlantının yaşam döngüsünü tek bir yerde tutun. Sızıntıların çoğu oradan çıkıyor. asyncio tarafını asyncio rehberimde daha ayrıntılı anlattım.
Review yorumlarına her düzeltmenin commit hash'iyle cevap verin. Reviewer'ın kontrol etmesi çok kolaylaşıyor.

Sırada ne var

Kodu incelemek isterseniz browser/agent-harness dizininden başlayın. Kendi yazdığım MCP sunucularından biri için freqtrade-mcp yazısına, diğer açık kaynak katkılarım için MCP ve AI platformlarına katkılarım ve Keploy katkım yazılarına bakabilirsiniz.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

Keploy Contribution: Go defer and HTTP Body Leaks

Furkan Köykıran — Sat, 21 Mar 2026 00:27:26 +0000

While following GitHub trending with awesome-trending-repos, I came across Keploy, an API testing tool written in Go. Its issue tracker had two resource management bugs, and I sent a PR for each. This post covers that Keploy contribution: using defer correctly in Go, and why an HTTP response body needs to be both drained and closed. Both PRs were merged on March 20, 2026. They were my first contributions to Keploy.

What Keploy does

Keploy captures your application's real traffic with eBPF and turns it into API tests and mocks for external dependencies. When the tests run again, database and third-party calls are answered from those mocks.

The two bugs I fixed sit at the edges of this flow: one where Keploy detects the application's language, the other in the HTTP client Keploy uses to talk to its own agent.

PR #3927: reading from a closed file

The bug

Issue #3821 pointed at isGoBinary in utils/utils.go. The function opened an ELF file, closed it right away, and then tried to read sections from the closed file:

f, err := elf.Open(filePath)
if err != nil {
    logger.Debug(fmt.Sprintf("failed to open file %s", filePath), zap.Error(err))
    return false
}
if err := f.Close(); err != nil { // the file is closed here
    LogError(logger, err, "failed to close file", zap.String("file", filePath))
}

sections := []string{".go.buildinfo", ".gopclntab"}
for _, section := range sections {
    if sect := f.Section(section); sect != nil { // ...and used here
        fmt.Println(section)
        return true
    }
}

DetectLanguage relies on isGoBinary, so the bug sat right where Keploy decides whether an application is written in Go.

The fix

I moved Close() into a defer. A deferred call runs when the function returns, whichever way it exits: an early return, the normal path, or a panic. I also removed a leftover debug fmt.Println(section).

The PR's first commit used a plain defer f.Close(). Copilot's automated review pointed out that this swallows the error from Close(), while the rest of the file logs close errors, and that it would probably trip golangci-lint's errcheck. The final version matches the other call sites:

f, err := elf.Open(filePath)
if err != nil {
    logger.Debug(fmt.Sprintf("failed to open file %s", filePath), zap.Error(err))
    return false
}
defer func() {
    if err := f.Close(); err != nil {
        LogError(logger, err, "failed to close file", zap.String("file", filePath))
    }
}()

sections := []string{".go.buildinfo", ".gopclntab"}
for _, section := range sections {
    if sect := f.Section(section); sect != nil {
        return true
    }
}
return false

PR #3927 was a +5/−4 change. AkashKumar7902 merged it on March 20.

PR #3932: response bodies that were never closed

The bug

Issue #3854 pointed at MockOutgoing and UpdateMockParams in pkg/platform/http/agent.go. Both sent a request to the agent and never closed res.Body:

res, err := a.client.Do(req)
if err != nil {
    return fmt.Errorf("failed to send request for mockOutgoing: %s", err.Error())
}
// res.Body is never closed

var mockResp models.AgentResp
err = json.NewDecoder(res.Body).Decode(&mockResp)

The net/http docs are explicit: the caller must close the body. An unclosed body holds on to its TCP connection, so the connection can't go back to the pool and every request opens a new one. In a long-running process that can end in exhausted file descriptors or ports.

The fix: drain, then close

Side by side, the whole change is one deferred function:

res, err := a.client.Do(req)
if err != nil {
    return fmt.Errorf("failed to send request for mockOutgoing: %s", err.Error())
}
defer func() {
    io.Copy(io.Discard, res.Body)
    if err := res.Body.Close(); err != nil {
        utils.LogError(a.logger, err, "failed to close response body for mockOutgoing")
    }
}()

var mockResp models.AgentResp
err = json.NewDecoder(res.Body).Decode(&mockResp)

The io.Copy(io.Discard, res.Body) line was the most useful thing I learned from this PR. The maintainer, AkashKumar7902, asked me to address the Copilot comments, and one of them explained it: json.Decoder.Decode doesn't promise to read the body to the end. If the body is closed before it reaches EOF, the Transport can't reuse the connection. Draining it first is what makes keep-alive actually work.

One caveat: if the body can be large, an unbounded io.Copy may pull megabytes you don't need. In that case, cap the drain:

io.Copy(io.Discard, io.LimitReader(res.Body, 64<<10)) // at most 64 KiB

Keploy's agent responses are small, so the unbounded version was fine there. PR #3932 was merged with two commits and 12 added lines.

Rules I now follow with defer

Since these two PRs I stick to a few rules with defer.

Put the defer right after you acquire the resource and after the error check. If os.Open fails, f is nil, and a defer f.Close() placed before the check will panic.

Don't defer inside a loop. Deferred calls run when the function returns, not at the end of each iteration, so thousands of files can stay open. Move the loop body into its own function:

func countLines(paths []string) (int, error) {
    total := 0
    for _, p := range paths {
        n, err := countFile(p) // the defer runs when countFile returns
        if err != nil {
            return 0, err
        }
        total += n
    }
    return total, nil
}

func countFile(path string) (int, error) {
    f, err := os.Open(path)
    if err != nil {
        return 0, err
    }
    defer f.Close()

    n := 0
    scanner := bufio.NewScanner(f)
    for scanner.Scan() {
        n++
    }
    return n, scanner.Err()
}

Multiple defers run in reverse order (LIFO). Their arguments are evaluated when the defer statement runs, not when the function returns, so use a closure if you need a variable's final value.

For a file you only read, the Close() error rarely matters. For a file you write, it does: that's where you learn buffered data didn't make it to disk. In that case, return the error from the function instead of only logging it.

Where to go next

The two PRs added 17 lines in total, and I only learned the body-draining detail from the review comments. In your own Go code, grep for client.Do and check that every response body is drained and closed in a defer. For more, see the Go docs for net/http Client.Do and the CommonMistakes page on the Go wiki.

The tool I found Keploy with, awesome-trending-repos, has its own post. My other open source work is in MCP open source contributions and security and API fixes.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

Keploy Katkım: Go'da defer ve HTTP Body Sızıntısı

Furkan Köykıran — Sat, 21 Mar 2026 00:27:24 +0000

awesome-trending-repos ile GitHub trending listesini takip ederken Go ile yazılmış bir API test aracı olan Keploy gözüme çarptı. Issue listesinde iki kaynak yönetimi hatası buldum ve ikisi için de PR açtım. Bu yazı o Keploy katkısını anlatıyor: Go'da defer'in doğru kullanımı ve HTTP response body'lerinin neden hem okunup hem kapatılması gerektiği. İki PR da 20 Mart 2026'da merge edildi. Keploy'a ilk katkımdı.

Keploy ne yapıyor

Keploy, uygulamanızın gerçek trafiğini eBPF ile yakalayıp bundan API testleri ve dış bağımlılıklar için mock'lar üretiyor. Testleri yeniden çalıştırırken veritabanı ve dış servis çağrıları bu mock'lardan cevaplanıyor.

Benim düzelttiğim iki hata bu akışın kenarlarında duruyor: biri Keploy'un uygulamanın dilini tespit ettiği yerde, diğeri Keploy'un kendi agent'ıyla konuştuğu HTTP istemcisinde.

PR #3927: kapatılmış dosyadan okuma

Hata

#3821 numaralı issue, utils/utils.go içindeki isGoBinary fonksiyonunu gösteriyordu. Fonksiyon bir ELF dosyasını açıyor, hemen kapatıyor, sonra kapatılmış dosyanın section'larını okumaya çalışıyordu:

f, err := elf.Open(filePath)
if err != nil {
    logger.Debug(fmt.Sprintf("failed to open file %s", filePath), zap.Error(err))
    return false
}
if err := f.Close(); err != nil { // dosya burada kapanıyor
    LogError(logger, err, "failed to close file", zap.String("file", filePath))
}

sections := []string{".go.buildinfo", ".gopclntab"}
for _, section := range sections {
    if sect := f.Section(section); sect != nil { // kapalı dosya üzerinde çalışıyor
        fmt.Println(section)
        return true
    }
}

isGoBinary, DetectLanguage tarafından kullanılıyor. Yani hata, Keploy'un bir uygulamanın Go ile yazılıp yazılmadığına karar verdiği yeri etkiliyordu.

Düzeltme

Close() çağrısını defer ile fonksiyonun sonuna taşıdım. defer edilen çağrı, fonksiyon hangi yoldan çıkarsa çıksın (erken return, normal dönüş ya da panic) en sonda çalışıyor. Bir de debug'dan kalmış fmt.Println(section) satırını sildim.

PR'ın ilk commit'inde düz defer f.Close() yazmıştım. Copilot'un otomatik review'u iki şeye dikkat çekti: bu yazım Close() hatasını yutuyor, ayrıca dosyanın geri kalanında kapatma hataları loglanıyor. Muhtemelen golangci-lint'in errcheck kuralına da takılacaktı. Son hâli dosyadaki diğer kullanımlarla aynı:

f, err := elf.Open(filePath)
if err != nil {
    logger.Debug(fmt.Sprintf("failed to open file %s", filePath), zap.Error(err))
    return false
}
defer func() {
    if err := f.Close(); err != nil {
        LogError(logger, err, "failed to close file", zap.String("file", filePath))
    }
}()

sections := []string{".go.buildinfo", ".gopclntab"}
for _, section := range sections {
    if sect := f.Section(section); sect != nil {
        return true
    }
}
return false

PR #3927 +5/−4 satırlık bir değişiklikti. AkashKumar7902 onu 20 Mart'ta merge etti.

PR #3932: kapatılmayan response body'ler

Hata

#3854 numaralı issue, pkg/platform/http/agent.go içindeki MockOutgoing ve UpdateMockParams fonksiyonlarını gösteriyordu. İkisi de agent'a istek atıyor ama res.Body'yi hiç kapatmıyordu:

res, err := a.client.Do(req)
if err != nil {
    return fmt.Errorf("failed to send request for mockOutgoing: %s", err.Error())
}
// res.Body hiç kapatılmıyor

var mockResp models.AgentResp
err = json.NewDecoder(res.Body).Decode(&mockResp)

net/http dokümantasyonu açık: body'yi kapatmak çağıranın sorumluluğunda. Kapatılmayan her body, altındaki TCP bağlantısını da elinde tutuyor. Bağlantı havuza geri dönemiyor, her istek yeni bir bağlantı açıyor. Uzun çalışan bir süreçte bu, dosya tanımlayıcılarının ve portların tükenmesine kadar gidebiliyor.

Düzeltme: kapat, ama önce sonuna kadar oku

Yan yana koyunca değişikliğin tamamı tek bir defer fonksiyonu:

res, err := a.client.Do(req)
if err != nil {
    return fmt.Errorf("failed to send request for mockOutgoing: %s", err.Error())
}
defer func() {
    io.Copy(io.Discard, res.Body)
    if err := res.Body.Close(); err != nil {
        utils.LogError(a.logger, err, "failed to close response body for mockOutgoing")
    }
}()

var mockResp models.AgentResp
err = json.NewDecoder(res.Body).Decode(&mockResp)

io.Copy(io.Discard, res.Body) satırı bu PR'dan öğrendiğim en faydalı şey oldu. Bakımcı AkashKumar7902 Copilot yorumlarına bakmamı istedi ve yorumlardan biri tam da bunu söylüyordu: json.Decoder.Decode body'nin sonuna kadar okumayı garanti etmiyor. JSON nesnesi bittikten sonra body EOF'a ulaşmadan kapatılırsa, Transport bağlantıyı yeniden kullanamıyor. Body'yi önce EOF'a kadar tüketmek, keep-alive'ın gerçekten çalışmasını sağlıyor.

Bir uyarı: body çok büyük olabiliyorsa sınırsız io.Copy gereksiz yere megabaytlarca veri indirebilir. Böyle durumlarda okumayı sınırlamak daha iyi:

io.Copy(io.Discard, io.LimitReader(res.Body, 64<<10)) // en fazla 64 KiB

Keploy'daki agent yanıtları küçük olduğu için sınırsız hâli yeterliydi. PR #3932 iki commit ve 12 satırla merge edildi.

defer ile ilgili akılda tutulacaklar

Bu iki PR'dan sonra kendi Go kodumda da şu kurallara dikkat ediyorum.

defer kaynağı aldıktan hemen sonra ve hata kontrolünden sonra yazılır. os.Open hata döndürdüyse f nil'dir, defer f.Close() hata kontrolünden önce yazılırsa panic'e gider.

Döngü içinde defer kullanılmaz. Ertelenen çağrılar döngü bitince değil fonksiyon bitince çalışır, binlerce dosya açık kalabilir. Çözüm, döngünün gövdesini ayrı bir fonksiyona almak:

func countLines(paths []string) (int, error) {
    total := 0
    for _, p := range paths {
        n, err := countFile(p) // defer, countFile bitince çalışır
        if err != nil {
            return 0, err
        }
        total += n
    }
    return total, nil
}

func countFile(path string) (int, error) {
    f, err := os.Open(path)
    if err != nil {
        return 0, err
    }
    defer f.Close()

    n := 0
    scanner := bufio.NewScanner(f)
    for scanner.Scan() {
        n++
    }
    return n, scanner.Err()
}

Birden fazla defer ters sırada (LIFO) çalışır. Argümanlar ise defer satırına gelindiği anda değerlendirilir, fonksiyon bittiğinde değil. Değişkenin son değerini istiyorsanız closure kullanın.

Sadece okunan bir dosyada Close() hatası nadiren önemlidir. Yazılan bir dosyada ise önemlidir, çünkü tamponlanmış verinin diske yazılamadığını ancak orada öğrenirsiniz. O durumda hatayı loglamak yerine fonksiyonun döndürdüğü hataya eklemek daha doğru olur.

Sırada ne var

İki PR toplamda 17 satır ekledi. Body'yi boşaltma ayrıntısını review yorumları sayesinde öğrendim. Kendi Go kodunuzda client.Do çağrılarını tarayıp her birinin arkasında defer ile kapatılan ve boşaltılan bir body olup olmadığına bakın. Daha fazlası için Go'nun net/http Client.Do dokümantasyonuna ve Go wiki'deki yaygın hatalar sayfasına bakabilirsiniz.

Keploy'u bulduğum araç olan awesome-trending-repos için ayrı bir yazı var. Diğer açık kaynak katkılarım MCP ekosistemi, GitHub MCP Server ve güvenlik ve API düzeltmeleri yazılarında.

Originally published on my blog. I write about MCP servers, AI agents, developer tools and Python automation; more at furkankoykiran.com.tr.

Building DevTo-MCP: Bridging Forem API and AI Assistants with Google Gemini

Furkan Köykıran — Fri, 27 Feb 2026 14:41:39 +0000

This is a submission for the Built with Google Gemini: Writing Challenge

As software developers, DEV Community (dev.to) and the wider Forem ecosystem have increasingly become our digital home. It's the place we go for "React best practices", solutions to obscure bugs, and career advice. But as our workflows become more tightly integrated with AI assistants, a gap has emerged: why can't our AI tools natively interact with this vibrant community?

Why couldn't I tell my AI assistant to "list popular Rust articles on DEV," or "take this markdown draft and publish it directly to my DEV account"?

To solve this, I built DevTo-MCP. It's an open-source Model Context Protocol (MCP) server that acts as a secure, type-safe bridge between the Forem API and AI assistants. And throughout this journey of architectural design, debugging, and implementation, Google Gemini was my constant pair-programming companion.

What I Built with Google Gemini

DevTo-MCP is essentially a translation layer. The Model Context Protocol (MCP) is an open standard that lets AI models use external tools and resources securely. DevTo-MCP takes the complex world of Forem API endpoints and turns them into simple, standardized functions that AI assistants (like Claude Desktop, Cursor, and custom Gemini agents) can seamlessly trigger.

During the development process, Google Gemini played several pivotal roles:

1. Architectural Guidance and Type Safety

Building an MCP server requires strict data validation. AI models can sometimes hallucinate parameters, so your server's defense must be ironclad. I decided to build DevTo-MCP using TypeScript, Node.js, and Zod for runtime validation.

Gemini helped me quickly map out the Forem API responses to Zod schemas. For example, when defining the create_article tool, Gemini assisted in generating the complete schema configuration:

server.tool(
    "create_article",
    "Create a new article on DEV Community.",
    {
        title: "z.string().describe(\"Title of the article\"),"
        body_markdown: z.string().optional().describe("Article content in markdown"),
        published: z.boolean().optional().describe("Whether to publish immediately"),
        tags: z.array(z.string()).max(4).optional().describe("List of tags (max 4)"),
        canonical_url: z.string().url().optional(),
        organization_id: z.number().int().optional()
    },
    async (params) => {
        // Implementation logic
    }
);

Thanks to Gemini's suggestions, added strict .max(4) constraints and .url() validations to ensure we never send malformed data to the Forem API.

2. The Self-Healing API Client

Forem's API deals with millions of requests, meaning rate limits and occasional network blips are part of the game. I wanted my MCP server to be resilient. I tasked Gemini with helping me write a self-healing HTTP client.

Gemini generated the core logic for a robust fetch wrapper that:

Reads x-ratelimit-remaining headers.
Implements an exponential backoff strategy for 429 (Too Many Requests) and 500 errors.
Provides type-safe generic responses.

// A simplified look at the retry logic we implemented
private async request<T>(...): Promise<T> {
    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
        try {
            const response = await fetch(url, options);
            if (response.ok) return await response.json();

            if (this.isRetryable(response.status)) {
                const delay = this.getRetryDelay(attempt);
                await this.sleep(delay);
                continue;
            }
        } catch (error) {
             // Handle network level errors
        }
    }
}

3. CI/CD and NPM "Trusted Publishing"

A crucial goal was to automate the publishing of this package to NPM using GitHub Actions. I wanted to use modern OpenID Connect (OIDC) (NPM's Trusted Publishing) to avoid hardcoding NPM_TOKEN secrets.

I was stuck with persistent 404 errors during the pipeline execution. I pasted my YAML into Gemini, and it instantly spotted the missing piece: my workflow was missing the environment: production declaration required to establish trust.

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: production  # <-- The magic line Gemini pointed out!
    permissions:
      id-token: write

Demo

The project is fully open-source and available here:
GitHub: furkankoykiran/DevTo-MCP

You can install and use it in any MCP-compatible client (like Claude Desktop) by simply adding it to your configuration:

{
  "mcpServers": {
    "devto": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/devto-mcp"],
      "env": {
        "DEVTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Once installed, your AI assistant can fetch your latest followers, create article drafts, and analyze your reading list tags dynamically!

What I Learned

Building this project taught me several invaluable lessons:

The Art of "Feature Cutting"

Initially, I wanted to include a tool that allowed users to add reactions (like, unicorn, fire) to articles via the AI. However, I consistently encountered unreliable 401 errors from the API side. As tempting as it was to keep debugging it, I learned that in building AI tools, reliability is paramount. If an AI thinks it successfully reacted to a post but didn't, it breaks the chain of trust. I had to learn the difficult engineering skill of "Feature Cutting" and disabled the tool for the MVP.

Fallback Mechanisms for UX

When the AI tried to fetch a "Draft" article using the standard get_article_by_id endpoint, Forem would return a 404. Initially, the AI would give up and respond, "This article doesn't exist."
I learned to build fallback loops. Now, if the server receives a 404, it automatically makes a secondary request to /articles/me/all, searches for the ID locally, and returns the draft. This completely changed how smoothly the AI interacted with unpublished content.

Modern Release Pipelines

I leveled up my Devops skills by successfully setting up an automated, secret-less NPM release pipeline using OIDC and GitHub Actions, understanding exactly when and why workflows trigger.

Google Gemini Feedback

My experience with Google Gemini was incredibly positive, with a few notable learning curves.

What Worked Well:

Boilerplate and Structure: Gemini was fantastic at instantly generating the foundational boilerplate for a TypeScript Node project.
Error Decoding: When I encountered cryptic TypeScript errors regarding complex generic types for my API wrapper, Gemini was able to decipher them and explain the exact configuration changes needed in my tsconfig.json.
Regex and Parsing: Writing the logic to safely sanitize markdown payloads before sending them to the API was made trivial thanks to Gemini's rapid regex suggestions.

Where I Encountered Friction (The Candid Truth):

API Hallucinations: Because the Forem API has changed over time, Gemini occasionally hallucinated endpoints or parameter names that didn't exist or were deprecated. For example, it suggested sending data in a structure that the current API rejected. This actually reinforced my decision to use Zod—building strict validation layers meant I caught these AI hallucinations in my test environment immediately.
Context Window Management: When working across multiple files (api-client.ts, server.ts, and the Zod schema files), I sometimes found Gemini losing the thread of the specific generic types we had agreed upon earlier in the conversation. Reminding it of the interface definitions occasionally disrupted the flow state.

Look Forward

The future of software engineering lies in AI assistants that have secure, predictable access to our development ecosystems. DevTo-MCP is my contribution to ensuring the DEV community isn't left behind in this AI revolution.

I plan to expand DevTo-MCP to include organization-level analytics, more robust comment threading capabilities, and eventually figuring out a secure way to re-enable that elusive "Reactions" tool!

Thank you to MLH and Google for hosting this challenge, it was the perfect catalyst to reflect on this build journey.

(P.S. As a special proof-of-concept, this very article was drafted, formatted, and published autonomously to DEV.to by my AI Assistant (Gemini) using the DevTo-MCP server I built! A little meta-magic to wrap things up! 🪄)