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

#

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.

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:

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.

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.

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:

1. 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.
2. If that yields fewer than 25 repos, the GitHub Search API fills the gap.
3. Invalid entries and anything outside a list of popular languages are dropped.
4. If the list is still short, repos from the last 7 days of snapshots are added.
5. The result is compared with yesterday's snapshot: new entries, risers, fallers and a "rising star".
6. .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.

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:

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:

1. 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.
2. I was sending the wrong parameter names to some tools (ls, cat, click).
3. 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.

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.

Four PRs and how they ended

#

Statuses and dates come from the PR records on GitHub.

Jules SDK: deleting sessions

#

Jules is Google Labs' asynchronous coding agent, and jules-sdk is its TypeScript client. The API had an endpoint for deleting a session, but the SDK didn't expose it; issue #105 tracked the gap. My PR added a delete() method to SessionClient:

async delete(): Promise<void> {
  try {
    await this.request(`sessions/${this.id}`, { method: 'DELETE' });
  } catch (error: any) {
    // 404: the session is already gone, still clear the local cache
    if (error.status !== 404) {
      throw error;
    }
  }
  await this.sessionStorage.delete(this.id);
}

Two decisions are baked in. A 404 means the session no longer exists, so the local cache is cleared and the call succeeds. Any other error is rethrown without touching the cache, so the API and the cache never drift apart. The request helper only accepted 'GET' | 'POST', so I added 'DELETE' to that union. Three tests cover success, 404 and 403. Usage is one line: await session.delete();. davideast merged the PR on March 16:

notebooklm-py: exporting notebook metadata

#

notebooklm-py is an unofficial Python API and CLI for Google NotebookLM. Google later renamed the product to Gemini Notebook; the library kept its name. In #171, a user wanted a notebook's details and its source list in one call. My PR added two things:

• client.notebooks.get_metadata(notebook_id) fetches the notebook and its sources concurrently with asyncio.gather and returns a NotebookMetadata. Sources are reduced to SourceSummary(kind, title, url), and to_dict() always emits the same keys, with null for missing values.
• A notebooklm metadata CLI command with a --json flag.

There's also a small safety net: if the notebook reports a non-zero source count but the source listing comes back empty, the code logs a warning, so possible data loss doesn't go unnoticed.

Run notebooklm login once, then:

import asyncio
import json

from notebooklm import NotebookLMClient

async def main() -> None:
    async with NotebookLMClient.from_storage() as client:
        notebooks = await client.notebooks.list()
        meta = await client.notebooks.get_metadata(notebooks[0].id)
        print(f"{meta.title}: {len(meta.sources)} sources")
        print(json.dumps(meta.to_dict(), indent=2, default=str))

asyncio.run(main())

From the terminal, notebooklm metadata --json gives you the same data. The PR was merged on March 11. The library has grown a lot since then and the method now delegates to a separate service layer, but the public API is unchanged.

cli-agent: a /health command (closed)

#

cli-agent is a terminal agent that talks to several LLM providers. I proposed a /health command to show at a glance which API keys work. It checked six providers (Anthropic, OpenAI, DeepSeek, Google, OpenRouter, Ollama) concurrently with asyncio.gather and summarized the results with ✓, ✗ and ○. With tests and README changes, the diff went past 850 lines.

The maintainer's answer was short: not necessary, fork it if it's useful to you, the license is permissive.

Part of that was on me. I opened issue #6 sixteen seconds before the PR, which is announcing a feature rather than asking about it. For a new feature, open the issue and wait for the maintainer to agree, especially when the diff is that large.

The idea is still handy. Here's a minimal version with three providers:

import asyncio
import os

import httpx

def targets() -> dict[str, tuple[str, dict[str, str]] | None]:
    openai_key = os.getenv("OPENAI_API_KEY")
    anthropic_key = os.getenv("ANTHROPIC_API_KEY")
    return {
        "openai": (
            "https://api.openai.com/v1/models",
            {"Authorization": f"Bearer {openai_key}"},
        ) if openai_key else None,
        "anthropic": (
            "https://api.anthropic.com/v1/models",
            {"x-api-key": anthropic_key, "anthropic-version": "2023-06-01"},
        ) if anthropic_key else None,
        "ollama": ("http://localhost:11434/api/tags", {}),
    }

async def check(client: httpx.AsyncClient, name: str, target) -> str:
    if target is None:
        return f"○ {name}: not configured"
    url, headers = target
    try:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return f"✓ {name}: {response.elapsed.total_seconds() * 1000:.0f} ms"
    except httpx.HTTPError as exc:
        return f"✗ {name}: {exc}"

async def main() -> None:
    async with httpx.AsyncClient(timeout=5.0) as client:
        results = await asyncio.gather(
            *(check(client, name, target) for name, target in targets().items())
        )
    print("\n".join(results))

asyncio.run(main())

With asyncio.gather you wait as long as the slowest provider, not the sum of all of them. httpx.HTTPError covers both connection failures and 4xx/5xx responses.

Mission Control: running without the gateway

#

Mission Control is a self-hosted control panel for AI agents, built with Next.js. In #270, a user reported that the gateway always showed as offline on a VPS. The browser connects to the gateway over WebSocket on non-standard ports (18789 and 18790), and most VPS firewalls block them.

My PR did two things. First, a standalone mode enabled with NEXT_PUBLIC_GATEWAY_OPTIONAL=true: instead of a red "Disconnected" warning, the HUD shows a blue "Gateway Optional (Standalone)" badge. The task board, projects, agent registry, cron jobs and webhooks keep working without a gateway; live session updates and agent-to-agent messaging don't.

Second, documentation for the proper fix: proxy the WebSocket traffic through port 443. The general nginx pattern looks like this (adjust the path and port to your setup):

location /gateway/ {
    proxy_pass http://127.0.0.1:18789/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 1h;
}

Without the Upgrade and Connection headers, nginx won't forward the WebSocket handshake. proxy_read_timeout keeps idle connections from being dropped after the default 60 seconds.

The same day, the maintainer 0xNyk collected the open deployment issues into one PR. #291 bundled two Docker fixes with the gateway-optional behavior and its docs, was merged on March 11, and closed my issue #289 along the way. #271 was closed with a note pointing to #291:

The NEXT_PUBLIC_GATEWAY_OPTIONAL line is in the project's .env.example.

What four PRs taught me

#

• Both merged PRs solved a well-scoped issue that someone else had opened.
• In Jules SDK the new method reused the existing request helper and test layout, so there was little to discuss in review.
• In Mission Control my PR was closed, the idea shipped through the maintainer's PR, and the user's problem got fixed.

What's next

#

My other contributions from those weeks are in MCP open source contributions and security and API fixes. For more on asyncio.gather and async clients, see Python asyncio for concurrent processing. If you're looking for a first SDK contribution, start with issues of the form "the API supports this but the SDK doesn't". The scope is clear and the change is easy to test. For a Go example, see my Keploy contribution.

Three PRs and where they stand

#

Statuses and dates come from the PR records on GitHub.

LightRAG: Cypher injection through the workspace name

#

The hole

#

LightRAG can store its knowledge graph in Neo4j or Memgraph and separates workspaces with node labels. The API server can read the workspace name from the LIGHTRAG-WORKSPACE HTTP header. In Neo4JStorage and MemgraphStorage, _get_workspace_label() returned that value untouched, and it went into queries through f-strings. The pattern looks like this:

query = f"MATCH (n:`{workspace_label}` {{entity_id: $entity_id}}) RETURN n"

Values like $entity_id are passed as parameters, which is correct. The label, though, is pasted into the query text. A header value containing a backtick could close the label and append arbitrary Cypher. lighthousekeeper1212 reported it in #2698, and I picked up the fix.

First commit and the collision problem

#

The PostgreSQL backend already sanitized workspace names with re.sub(r"[^a-zA-Z0-9_]", "_", ...), so my first commit applied the same rule to Neo4j and Memgraph and added 20 tests. Then a side effect came up: team-a and team_a map to the same label, so two different workspaces could share data.

In the second commit I stopped stripping characters and escaped backticks by doubling them. Every workspace name now maps to exactly one label:

def _get_workspace_label(self) -> str:
    workspace = self.workspace.strip()
    if not workspace:
        return "base"
    return workspace.replace("`", "``")

Review: escaping depends on context

#

The maintainer, danielaskdd, found three problems in review. All three came from using the escaped value everywhere.

1. Labels returned by the driver are raw (foobar), and the code compared them with the escaped value (foo``bar`), so the comparison never matched.
2. The Memgraph index creation query used the label without backticks, where the escaped value produces invalid Cypher.
3. One query used the label as a string literal, WHERE '{label}' IN labels(n). Doubled backticks mean nothing inside a string, so that query never matched either.

Backtick escaping only applies to an identifier inside backticks. In a string context, bind the raw value as a parameter. Here are both, side by side, with the official neo4j Python driver:

from neo4j import GraphDatabase

def identifier_label(workspace: str) -> str:
    """Label for use inside backticks."""
    return (workspace.strip() or "base").replace("`", "``")

def raw_label(workspace: str) -> str:
    """Label for binding as a query parameter."""
    return workspace.strip() or "base"

def find_entity(driver, workspace: str, entity_id: str):
    label = identifier_label(workspace)
    # Identifier context: escaped value inside backticks
    by_label = f"MATCH (n:`{label}` {{entity_id: $entity_id}}) RETURN n"
    # String context: raw value as a parameter, never interpolated
    by_filter = (
        "MATCH (n) WHERE $label IN labels(n) "
        "AND n.entity_id = $entity_id RETURN n"
    )
    with driver.session() as session:
        first = session.run(by_label, entity_id=entity_id).single()
        second = session.run(
            by_filter, label=raw_label(workspace), entity_id=entity_id
        ).single()
    return first, second

if __name__ == "__main__":
    with GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password")) as driver:
        print(find_entity(driver, "team-a", "Alan Turing"))

How it landed: validation at the entry point too

#

danielaskdd took my branch and added a commit on top. The workspace value is now sanitized where it enters the system, both from --workspace / WORKSPACE and from the LIGHTRAG-WORKSPACE header: anything outside [a-zA-Z0-9_] becomes _, with a warning logged when the value changes. The combined change was merged as #2792 on March 18, 2026:

That's why my #2713 shows as closed while my commits are in main. _get_workspace_label() uses my escaping, and a separate helper binds the raw label as a parameter for string contexts. The two layers work together.

Don't rely on a single layer. Validate input against an allowlist at the edge, and escape or parameterize correctly for each context in the query.

OpenAI Python SDK: in-memory or in_memory?

#

Issue #2883 pointed out that the SDK typed prompt_cache_retention as Literal["in-memory", "24h"], while the API rejected "in-memory" with a 400 and only accepted "in_memory". The type checker suggested the wrong value and flagged the right one. The bug was in the value's spelling, not the parameter name.

My PR fixed the literal in nine files (+41/−41, across the Chat Completions and Responses types and tests). Six months later a maintainer closed it: the same fix had already landed in main through a commit from the SDK's code generation pipeline. openai-python isn't written by hand. It's generated with Stainless from OpenAI's OpenAPI spec, and the spec is where a lasting fix goes.

Before opening a PR against a generated SDK, read the README and CONTRIBUTING file. For projects like this, a good issue is often more useful than a PR. Correct usage:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.1",
    input="Summarize this text in three bullet points: ...",
    prompt_cache_retention="24h",  # or "in_memory"
)
print(response.output_text)

Coinbase AgentKit: decimals hardcoded to 18

#

AgentKit is a toolkit that lets AI agents act onchain. Its Morpho withdraw action converted the amount with Web3.to_wei(assets, "ether"), and the "ether" unit always means 18 decimals. USDC uses 6. An agent withdrawing 100 USDC would request 100 × 10¹⁸ base units, 10¹² times too many. The bug was reported in #946.

The deposit action in the same provider already did this right by reading decimals() from the token contract. My PR made withdraw follow the same path: it adds a token_address field to the schema, reads decimals through wallet_provider.read_contract(...), converts the amount accordingly, and adds a test for a 6-decimal token.

Here's the conversion on its own, independent of AgentKit and runnable as is:

from decimal import Decimal

def to_atomic(amount: str, decimals: int) -> int:
    value = Decimal(amount)
    if value <= 0:
        raise ValueError("amount must be positive")
    scaled = value.scaleb(decimals)
    if scaled != scaled.to_integral_value():
        raise ValueError(f"{amount} has more than {decimals} decimal places")
    return int(scaled)

assert to_atomic("100", 6) == 100_000_000                 # USDC
assert to_atomic("0.5", 18) == 500_000_000_000_000_000    # WETH

I keep the amount as a Decimal built from a string, never a float, so values like 0.1 don't pick up rounding errors. Reading decimals with web3.py is short:

from web3 import Web3

ERC20_DECIMALS_ABI = [{
    "name": "decimals", "type": "function", "stateMutability": "view",
    "inputs": [], "outputs": [{"name": "", "type": "uint8"}],
}]

w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))
usdc = w3.eth.contract(
    address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  # USDC on Base
    abi=ERC20_DECIMALS_ABI,
)
print(usdc.functions.decimals().call())  # 6

The PR is open and waiting for review:

Until it's merged, withdraw in main keeps using to_wei(..., "ether"). If you call it with a token that doesn't use 18 decimals, check the amount yourself.

Three PRs, three endings

#

• In LightRAG my code landed, and the fix was complete once the maintainer added validation at the entry point.
• In the OpenAI SDK I fixed a real bug in the wrong place. In a generated codebase, the source spec is where the patch belongs.
• In AgentKit the fix and its test are ready, and the PR is waiting for review.

What's next

#

My other contributions from those weeks are in MCP open source contributions and SDK and CLI contributions, and the Go side is in my Keploy contribution. If your own code talks to a graph database, start by checking where the labels and relationship types in your f-string queries come from.

Five PRs and where they stand

#

Statuses and dates come from the PR records on GitHub.

Playwright MCP: header values with colons

#

When you connect Playwright MCP to a remote browser over CDP, you can pass headers with --cdp-header or the PLAYWRIGHT_MCP_CDP_HEADERS environment variable. The headerParser function split each value with arg.split(':') and destructured the first two parts, so X-Custom: http://example.com silently became http. Anything with a colon in the value got cut: URLs, host:port pairs, some tokens.

The fix is to split on the first colon only:

const colonIndex = arg.indexOf(':');
const name = colonIndex === -1 ? arg.trim() : arg.substring(0, colonIndex).trim();
const value = colonIndex === -1 ? '' : arg.substring(colonIndex + 1).trim();

The test sends X-Forwarded-Proto: value:with:colons plus an empty X-Empty header and checks what actually reaches the test server. It was merged on March 10.

Playwright MCP: malformed Unicode in responses

#

The problem

#

In playwright-mcp#1447, frankhommers reported that MCP responses from some pages failed with JSON errors. The cause was lone surrogates: half of a UTF-16 surrogate pair with no partner, for example an emoji cut in the middle.

const s = `Hello ${String.fromCharCode(0xD800)}`;

s.isWellFormed();   // false
JSON.stringify(s);  // '"Hello \\ud800"' (no error, but the lone surrogate is still there)
s.toWellFormed();   // 'Hello �', displayed as "Hello �"

Modern JSON.stringify doesn't throw here. It escapes the character as \ud800. The failure shows up further down the chain, when a stricter JSON parser on the client side rejects the payload with errors along the lines of "invalid high surrogate". The client sees the error, but the server is where it should be fixed.

Where the fix belongs

#

frankhommers' first attempt (#1448) sanitized the output in cli.js, at the transport layer, and was closed. I looked at where the text is produced instead. In packages/playwright-core/src/tools/backend/response.ts, every response already went through redactText(), so adding the cleanup there covered every tool in one place. The diagram shows where each attempt sits in the chain:

The change itself is short:

text: sanitizeUnicode(redactText(text.join('\n'))),

// ...

function sanitizeUnicode(text: string): string {
  return text.toWellFormed();
}

toWellFormed() replaces lone surrogates with U+FFFD and leaves valid emoji and CJK text alone.

What the review taught me

#

The PR's initial commit had a regex fallback for Node 18 and six tests. Pavel Feldman's review was short: it looked like an agent-generated blob that failed lint; the location was right, but I should assume Node 20 and hand-write the tests. He was right. I dropped the fallback, since toWellFormed() has been in Node since version 20, and cut the tests down to three that match the style of the existing MCP tests: a page with a lone surrogate, a page with valid emoji, and a console.log that prints a lone surrogate. Pavel Feldman merged it on March 14:

The maintainer spotted the generated code at first glance. The short version, written in the style of the project's tests, landed within days.

GitHub MCP Server

#

A create_discussion tool (#1519, open)

#

GitHub's official MCP server could read discussions but not create them. In December 2025 I opened a PR adding a create_discussion tool. It fetches the repository ID over GraphQL and then calls the createDiscussion mutation. If repo is omitted, the discussion is created at the organization level. The codebase moved to a new NewTool() pattern in the meantime, so I rewrote the tool during a rebase. The PR is open. I wrote up the full story in a separate post.

--read-only in HTTP mode (#2200, closed)

#

In #2156, a user ran the server in Docker with http --read-only and still saw write tools like create_branch and create_pull_request. The flag worked in stdio mode but was never passed to the HTTP server's config. My PR added it to ServerConfig and registered a middleware that marks every request context as read-only:

func withGlobalReadonly(cfg *ServerConfig) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if cfg.ReadOnly {
				ctx := ghcontext.WithReadonly(r.Context(), true)
				next.ServeHTTP(w, r.WithContext(ctx))
			} else {
				next.ServeHTTP(w, r)
			}
		})
	}
}

The maintainer, Sam Morrow, replied that this wasn't a bug but an open design decision. In HTTP mode, each user can enable read-only mode with an x-mcp-readonly: true header, the same way GitHub's hosted remote server works. I made the case for a server-level setting: consistency with stdio, clients that can't send custom headers, and the Docker setup from the issue.

Sam then opened his own PR. #2208 treats the CLI flags as an upper bound, and per-request headers can only narrow it. That's a cleaner model than my middleware. I confirmed it fixed the Docker case. #2208 was merged on April 13, and my PR was closed.

My middleware never landed, and the behavior I asked for shipped with #2208. The PR taught me that a bug report is sometimes a design question, and arguing it through is part of the contribution.

LobeHub: a one-line regression fix (#12818, open)

#

On LobeHub's onboarding page, opening the model picker crashed the app with React Error #185. I reported it in #12817. Digging through history, I found the same crash had been fixed in January by #11905, and the fix was lost during the base-ui migration: showInfoTag on ModelItemRender was back to true. My PR restores it:

<ModelItemRender
  {...(option as ModelOption)}
  {...(option as ModelOption).abilities}
  showInfoTag={false}
/>

One maintainer commented that it "seems still buggy". I asked which scenario still failed and noted that the crash was gone in the Vercel preview and locally. There was no reply. Another user had mentioned in the issue that switching models from the top menu crashed too, so my one line may not cover every path. The PR is still open; the issue was closed later.

Around the same time I opened #12805, asking for some of my MCP servers, DevTo-MCP and OmniWire-MCP among them, to be listed in the LobeHub marketplace. It was closed as not planned.

What I took away

#

• Fix the problem where the data is produced, not where the error shows up. That's what got the Unicode PR merged.
• A short diff with hand-written tests gets reviewed faster.
• Ask before calling something a bug. The read-only flag was a design decision.
• Even a one-line fix needs evidence: reproduction steps, before and after screenshots, or a test.

Where to go from here

#

My own MCP servers are DevTo-MCP and OmniWire-MCP. The other PRs from the same weeks are in security and API fixes and SDK and CLI contributions, and there's a Go-focused one in my Keploy contribution. If you want to contribute to the MCP ecosystem yourself, Playwright's tests/mcp folder is a good place to start: the tests are short and adding a new one is easy.

This post covers how I trained the model, how the API works, and, most importantly, what the model does and doesn't know.

What it does and what it doesn't

#

For a single face image, the model returns one of two classes: REAL or AI_GENERATED. The real faces in the training data come from FFHQ and the fake ones from StyleGAN. That has three consequences worth stating up front:

• The model was trained to spot fully synthetic, StyleGAN-style faces. Images from diffusion models such as Stable Diffusion or Midjourney aren't in the training set. The repo description mentions them, but there's no measured accuracy on those generators.
• Face swaps in video, the classic deepfake, are out of scope. The model looks at one still image.
• A classifier's output is a probability. Don't use it as sole evidence for identity verification or fact-checking.

The banner at the top of the repo README names diffusion models next to GANs. The limit above still applies: the only measured results are on StyleGAN faces.

Architecture

#

The card below follows one request: the uploaded file is validated, resized to 224×224 and normalized, passed through the model, and returned as JSON.

The model is loaded once at startup in FastAPI's lifespan handler. If model.pth is missing, the API still starts but /detect returns 503, and /health reports whether the model is loaded.

Dataset

#

I trained on the 140k Real and Fake Faces dataset from Kaggle: 70,000 real faces from FFHQ and 70,000 StyleGAN faces, all 256×256. The provided split is 100,000 training, 20,000 validation and 20,000 test images. With balanced classes, the model can't score well just by leaning towards one class.

The model: transfer learning with MobileNetV2

#

Instead of training a CNN from scratch, I started from MobileNetV2 pretrained on ImageNet, froze the feature extractor, and replaced and trained only the final classifier. At about 3.5 million parameters it runs quickly on a CPU, and the weights file is around 14 MB.

The core of the model setup in training/train.py:

import torch.nn as nn
from torchvision import models
from torchvision.models import MobileNet_V2_Weights

def create_model() -> nn.Module:
    model = models.mobilenet_v2(weights=MobileNet_V2_Weights.IMAGENET1K_V1)

    for param in model.features.parameters():
        param.requires_grad = False  # frozen backbone, only the head trains

    in_features = model.classifier[1].in_features  # 1280
    model.classifier = nn.Sequential(
        nn.Dropout(p=0.3),
        nn.Linear(in_features, 1),  # one logit: 0 = AI, 1 = REAL
    )
    return model

The rest of the training setup:

• BCEWithLogitsLoss with Adam (learning rate 0.001, weight decay 1e-4).
• ReduceLROnPlateau divides the learning rate by 10 after 3 epochs without validation-loss improvement. Early stopping kicks in after 5. At most 15 epochs.
• Inputs are resized to 224×224 and normalized with ImageNet mean and standard deviation. The only augmentation is a random horizontal flip; I removed heavier transforms from the script to keep training fast.
• On Kaggle I used two T4 GPUs with DataParallel, mixed precision (torch.amp) and a batch size of 256. The script detects whether it runs on Kaggle, Colab or locally.

Results

#

The README reports these numbers on the dataset's test split (20,000 images):

Keep in mind that the test set comes from the same distribution as the training set: the same StyleGAN, the same resolution, the same crops. I'd expect accuracy to drop on photos from another generator, or on images that were compressed or resized along the way. Building a separate test set to measure that is on my list.

The API

#

The endpoint that matters is POST /detect. It accepts a JPG, PNG or WEBP file up to 5 MB:

curl -X POST "http://localhost:8000/detect" -F "file=@face.jpg"

{
  "status": "success",
  "result": "AI_GENERATED",
  "confidence": 0.98,
  "probabilities": { "AI_GENERATED": 0.98, "REAL": 0.02 },
  "inference_time_ms": 45.2,
  "image_size": "512x512"
}

The model outputs a single logit. After the sigmoid, the value is the probability of REAL. Anything below 0.5 is returned as AI_GENERATED, and confidence is the probability of whichever class won.

Running it locally

#

git clone https://github.com/furkankoykiran/ai-face-detector.git
cd ai-face-detector
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

The trained weights aren't in the repo. You can download them from the Kaggle model page, or open a GPU notebook on Kaggle, attach the dataset and run training/train.py. According to the README, training on two T4s takes about 43 minutes. Put the resulting model.pth in the project root and start the API:

uvicorn app.main:app --reload --port 8000

Swagger UI is at http://localhost:8000/docs. Serve the web page with a small server rather than opening the file directly, because the API's CORS list includes http://localhost:3000 but not file://:

python -m http.server 3000 --directory static

The quickest way to try the model without installing anything is the demo notebook on Kaggle. It attaches the trained model and the 140k dataset as inputs and runs on two T4 GPUs.

Known rough edges

#

Rereading the repo, I found three things to fix:

• app/model_loader.py still uses the old pretrained=True argument, which torchvision deprecated in 0.13. Since we load our own weights anyway, there's no reason to download the ImageNet weights on every startup.
• Training on two GPUs with DataParallel saves state_dict keys with a module. prefix. The API doesn't strip it, so it can't load such a file.
• requirements.txt pins early-2024 versions (torch 2.1, FastAPI 0.109).

For the first two, the loader should look like this:

import torch
import torch.nn as nn
from torchvision import models

def create_model() -> nn.Module:
    model = models.mobilenet_v2(weights=None)  # weights come from our file
    in_features = model.classifier[1].in_features
    model.classifier = nn.Sequential(nn.Dropout(p=0.3), nn.Linear(in_features, 1))
    return model

def load_model(path: str, device: torch.device) -> nn.Module:
    state = torch.load(path, map_location=device, weights_only=True)
    state = {k.removeprefix("module."): v for k, v in state.items()}
    model = create_model()
    model.load_state_dict(state)
    return model.to(device).eval()

weights_only=True has been the default since PyTorch 2.6. It stops a .pth file from an unknown source from executing code on load, so I prefer to spell it out.

What's next

#

The code is on GitHub, and there's a summary on my portfolio. Next up: fix the rough edges above and build a separate test set of faces from diffusion models. If the model holds up there, it will be fair to widen the claim in the README.

If you're interested in the API side, REST API development with FastAPI goes deeper into Pydantic v2 and async. For preprocessing, see image processing with Pillow and OpenCV, and for shipping the service, containerizing a Python app with Docker.

This post covers that experiment: what the agent did, what went well, and the errors I only noticed later.

The tool: DevTo-MCP

#

DevTo-MCP is my server that turns the Forem API into MCP tools. With it an assistant can search DEV, list my posts and create new ones with create_article. While testing it on February 18 I had created and updated a throwaway post titled "DevTo MCP Test Article [Automated]" on my account. The challenge was the first time I used it for real work.

Project page: DevTo-MCP

The task I gave the agent

#

Without leaving my editor, I gave a Gemini-based agent roughly this instruction:

Research the Built with Google Gemini challenge. Read the DevTo-MCP post on my blog. Write an English article about the process that follows the challenge template. When you're done, publish it on my DEV account.

The agent then:

1. Read the challenge announcement and submission template, which asked for sections like "What I Built with Google Gemini," "Demo" and what you learned.
2. Read my blog post about DevTo-MCP and mapped its technical content onto the template.
3. Wrote the article and added a closing note saying the post had been drafted and published autonomously through DevTo-MCP.
4. Called create_article with published: true.

The article went live on DEV on February 27, 2026, titled "Building DevTo-MCP: Bridging Forem API and AI Assistants with Google Gemini" and tagged devchallenge, geminireflections, gemini and mcp. The whole run took a few minutes.

Here is the whole chain, from one instruction to a published post:

What went well

#

Mechanically, everything worked. The agent's create_article call went through on the first try. It read the template correctly, put the submission line where it belonged and used the challenge's tags.

This kind of chain is where an MCP server earns its keep: research, reading, writing and publishing tied together by one instruction. I stated the goal and the agent planned the steps in between.

What slipped through

#

The DevTo-MCP write-up the agent used as its source made several claims the code doesn't back up. Since the agent built the challenge entry from that write-up, the same errors went into the entry:

• It says the API client reads x-ratelimit-remaining and slows down before hitting the limit. The client doesn't; it only uses the header in error messages.
• It says the npm release used OIDC trusted publishing, that a missing environment: production line caused 404s, and that Gemini spotted the missing line. The workflow in the repo has had that line since its first commit, and publishing uses an npm token.
• The install section uses npx -y devto-mcp. In March I moved the package to @furkankoykiran/devto-mcp, and the unscoped devto-mcp name now belongs to a different project on npm. Anyone running that command installs someone else's package and hands it their DEV API key.

The last one is the serious one. The command was right on the day the agent wrote it; the package name changed later. Code gets updated, but a published post stays as it was.

The agent also framed the article as my development story, with Gemini as a pair programmer at every step. The template invited that framing, and the agent didn't hesitate to draw connections the source didn't contain. Anything published under my name has to be something I can stand behind sentence by sentence, and that entry has sentences I can't.

What I'll do differently

#

I won't let the agent publish. create_article has a published: false option: the agent creates a draft, and I read it in the DEV editor and publish it myself. The minutes saved by automation easily cover a few minutes of reading.

I'll verify the source first. The agent worked from a blog post, so every error in that post carried over. A model that rewrites a flawed source quickly and fluently makes the flaws more convincing.

The server can help too: default create_article to drafts and require an explicit confirmation parameter to publish. Not making a write tool's least reversible side effect its default is a rule I want to follow in every MCP server I design.

Where this leaves me

#

The experiment showed that an agent can do a job end to end over MCP. It also showed that an agent with write access publishes whatever its source says. My next steps are switching DevTo-MCP's default to drafts and adding a correction note with the current install command to the DEV article.

The technical details of the server are in the DevTo-MCP post, and another server from the same series is OmniWire-MCP. The code is on GitHub.

Project page: telegram-wallet-p2p-sdk · Source: GitHub

The project isn't affiliated with Telegram or Wallet. And the API is strictly read-only: you can list ads, but you can't post ads or trade. This is a market data and analytics toolkit, not a trading bot.

What the API looks like

#

There's a single endpoint. You POST to https://p2p.walletbot.me/p2p/integration-api/v1/item/online with an X-API-Key header:

{
  "cryptoCurrency": "USDT",
  "fiatCurrency": "EUR",
  "side": "SELL",
  "page": 1,
  "pageSize": 50
}

The response is {"status": "SUCCESS", "data": [...]}. Each ad carries the price, remaining quantity, min and max order amounts, payment methods, the maker's completed order count and completion rate, merchant level (regular user, merchant, trusted merchant) and whether auto-accept is on. Pages hold at most 50 ads.

You create an API key inside Telegram under Wallet → P2P Market → your profile → API Keys. The key doesn't come from browser DevTools; you create it in that menu.

Why a monorepo

#

All three packages wrap the same API, and their models are coupled. When the API adds a field, the Python model, the TypeScript types and the MCP server should change in the same PR. Across separate repos that sync drifts quickly. The card shows the three packages and where each one is used.

The published packages:

• PyPI: telegram-wallet-p2p
• npm: @furkankoykiran/telegram-wallet-p2p
• npm: @furkankoykiran/telegram-wallet-p2p-mcp

All three live in the repo's packages folder.

As the card shows, the MCP server doesn't depend on the Node SDK; it keeps its own types and HTTP call. That was deliberate: npx downloads a single package, and there's no workspace dependency to complicate publish order. The cost is the same types living in two places.

Why prices are strings

#

The API returns prices, quantities and rates as strings, and both SDKs keep them that way:

export interface OnlineItem {
  id: string;
  price: string;          // price per unit
  lastQuantity: string;   // remaining quantity
  minAmount: string;
  maxAmount: string | null;
  executeRate: string;    // completion rate, 0-1
  payments: string[];
  merchantLevel: MerchantLevel;
  isAutoAccept: boolean;
  // ...
}

Everyone knows 0.1 + 0.2 is 0.30000000000000004 in JavaScript. Convert a price to number once and that error leaks into sums and comparisons. Store strings and do the math with a decimal type.

The Python analytics helpers actually do this; every calculation uses decimal.Decimal. The Node side has an inconsistency: helpers like priceSpread and bestPrice convert prices with parseFloat. That's acceptable for statistics like mean and median, which get rounded to four decimals anyway, but don't use their output for accounting or order sizing. Moving the Node helpers to a decimal library is on my list.

The Node SDK doesn't validate API responses with Zod. It doesn't use Zod at all; the types are plain TypeScript interfaces with no runtime validation. Zod is only in the MCP server, for tool arguments. On the Python side, Pydantic v2 models do validate responses and map camelCase fields to snake_case.

The Node.js SDK

#

The Node SDK has no runtime dependencies. It uses the fetch built into Node since 18:

import { WalletP2PClient, TradeSide, bestPrice, priceSpread } from "@furkankoykiran/telegram-wallet-p2p";

const client = new WalletP2PClient({ apiKey: process.env.WALLET_P2P_API_KEY! });

const { data } = await client.getOnlineItems({
  cryptoCurrency: "USDT",
  fiatCurrency: "EUR",
  side: TradeSide.SELL,
  pageSize: 50,
});

console.log(priceSpread(data));
console.log(bestPrice(data, TradeSide.SELL)?.price);

Top-level await needs an ES module (.mjs, .mts, or "type": "module" in package.json).

The client retries 429 and 5xx responses on its own: 3 attempts by default with exponential backoff of 1, 2 and 4 seconds. Other failures arrive as typed errors: AuthenticationError for a bad key, BadRequestError for an unsupported currency, RateLimitError once retries run out. Requests time out after 30 seconds via AbortController.

The Python SDK

#

The Python SDK is built on aiohttp and used as an async context manager. Scanning several currencies at once is a job for asyncio.gather:

import asyncio
import os

from telegram_wallet_p2p import TradeSide, WalletP2PClient
from telegram_wallet_p2p.analytics import price_spread


async def scan(client: WalletP2PClient, fiat: str):
    resp = await client.get_online_items("USDT", fiat, TradeSide.SELL, page_size=50)
    return fiat, price_spread(resp.data)


async def main() -> None:
    async with WalletP2PClient(api_key=os.environ["WALLET_P2P_API_KEY"]) as client:
        results = await asyncio.gather(*(scan(client, f) for f in ["EUR", "USD", "TRY"]))

    for fiat, stats in results:
        print(fiat, stats)


if __name__ == "__main__":
    asyncio.run(main())

The client shares one aiohttp.ClientSession and closes it when the async with block exits. Opening a session per request wastes the connection pool, so create the client once and reuse it.

This isn't "high-frequency data collection." You're sending a handful of parallel requests and you have to respect the API's rate limit. Polling every minute, or every few minutes, and writing the results to a time-series database is plenty to see how P2P spreads move during the day.

Pagination and rate limits

#

To walk the whole order book at 50 ads per page you request pages in sequence. You don't need your own 429 handling because the client already retries; a short pause between pages keeps you well clear of the limit. Here's the loop:

import { WalletP2PClient, TradeSide, type OnlineItem } from "@furkankoykiran/telegram-wallet-p2p";

const client = new WalletP2PClient({ apiKey: process.env.WALLET_P2P_API_KEY! });
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function fetchAll(crypto: string, fiat: string, side: TradeSide): Promise<OnlineItem[]> {
  const all: OnlineItem[] = [];
  for (let page = 1; ; page++) {
    const { data } = await client.getOnlineItems({
      cryptoCurrency: crypto,
      fiatCurrency: fiat,
      side,
      page,
      pageSize: 50,
    });
    all.push(...data);
    if (data.length < 50) break; // last page
    await sleep(500);
  }
  return all;
}

Don't try to catch 429s with error.message.includes('429'). This SDK's error messages don't include the status code, so that branch never fires; use error instanceof RateLimitError if you need it. Using push instead of rebuilding the array with [...all, ...page] on every page also avoids needless copying on deep books.

The MCP server

#

The MCP server exposes three tools:

• get_p2p_ads lists ads by crypto, fiat and side.
• get_market_summary returns price statistics, payment method and merchant level breakdowns, and the average completion rate.
• get_best_price returns the best-priced ad for a side.

Claude Desktop config:

{
  "mcpServers": {
    "telegram-wallet-p2p": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/telegram-wallet-p2p-mcp"],
      "env": {
        "WALLET_P2P_API_KEY": "your-key"
      }
    }
  }
}

Then you can ask things like "What's the cheapest USDT I can buy with EUR right now?" or "Summarize the TON/USD market. How many sellers are merchants?" The assistant fetches the data and does the filtering itself.

The meaning of side isn't documented consistently across the packages. The MCP tool describes it from the ad maker's perspective, while the analytics docs describe it from the taker's. bestPrice picks the lowest price for BUY and the highest for SELL. Before trusting "best" from these helpers, compare a few ads against what the app shows to confirm which side means what. Pinning down one definition and applying it to all three packages is my next task.

What's next

#

Short term, the two fixes above: one definition of side, and decimal math in the Node helpers. The Python package's __version__ also disagrees with pyproject.toml, which needs fixing.

If Wallet ever adds write access to the API, order creation would be the obvious addition, but no such endpoint exists today and I'm not writing code against an API that isn't there. A short-lived cache for frequently queried pairs is an easy way to stay further under the rate limit.

I cover parallel requests, timeouts and concurrency limits in more depth in my Python asyncio guide. Other MCP servers in this series: freqtrade-mcp and DevTo-MCP.

Project page: DevTo-MCP · Source: GitHub

This post covers how the server is put together, the choices in its API client, a feature I switched off, and a lesson about npm package names.

Why an MCP server for DEV

#

I cross-post some of my writing to DEV. Writing a draft in my editor, pasting it into the browser, typing tags one by one, then going back to the site to check comments got tedious. I wanted to tell my assistant "open this markdown as a draft on DEV" or "list this week's popular TypeScript posts."

MCP has three roles. The host is the app running the assistant, such as Claude Desktop. The MCP client inside the host speaks JSON-RPC 2.0 to a server. DevTo-MCP is the server: it advertises its tools, and when the client calls one it hits the Forem API and returns the result.

Layout and tools

#

src/
├── index.ts            # reads DEVTO_API_KEY, starts over stdio
├── server.ts           # registers the tool groups
├── services/
│   └── api-client.ts   # Forem API client
├── tools/              # articles, comments, users, tags, organizations,
│                       # reading-list, followers
└── types/

The first release shipped 17 tools; 16 are enabled today. For articles there are get_articles, get_article_by_id, create_article, update_article and get_my_articles. The rest are read tools for comments, users, organizations, tags, reading lists and followers. The Forem API has no endpoint for writing comments, so the comment tools are read-only.

Validating inputs with Zod

#

The model generates tool arguments itself, and sometimes gets them wrong. DEV allows at most four tags per article; a model can easily send five. So every tool's parameters are a Zod schema:

server.tool(
  "create_article",
  "Create a new article on DEV Community. Set published to false to save as draft.",
  {
    title: z.string().describe("Title of the article"),
    body_markdown: z.string().optional().describe("Article content in markdown format"),
    published: z.boolean().optional().describe("Whether to publish immediately (false = draft)"),
    tags: z.array(z.string()).max(4).optional().describe("List of tags (max 4)"),
    series: z.string().optional().describe("Article series name"),
    canonical_url: z.string().url().optional().describe("Original URL if cross-posting"),
    description: z.string().optional().describe("Short description for the article"),
    main_image: z.string().url().optional().describe("Main cover image URL"),
    organization_id: z.number().int().optional().describe("Organization ID to publish under"),
  },
  async (params) => { /* ... */ },
);

The SDK turns this into JSON Schema for the model and validates incoming arguments against it. A fifth tag or a malformed canonical_url never reaches the API; the model gets a readable error and usually fixes it on the next try.

API responses don't go through Zod. The client reads response.json() and casts it with as T; there's no runtime check. If Forem returns a field in an unexpected shape, TypeScript won't notice. Since what goes back to the assistant is JSON text anyway, this doesn't crash anything in practice, but the response types are compile-time only.

The API client: timeouts, retries and Retry-After

#

api-client.ts is a bit more than a fetch wrapper:

• Every request is cut off after 30 seconds with AbortSignal.timeout(30_000).
• On 429, 5xx and network errors it retries up to 3 times, waiting 1, 2 and 4 seconds.
• If the server sends Retry-After, it waits that long instead.
• On failure it puts the x-ratelimit-* headers and x-request-id into the error message, so both the assistant and I can see what went wrong.

private getRetryDelay(attempt: number, response?: Response): number {
  const retryAfter = response?.headers.get("retry-after");
  if (retryAfter) {
    const seconds = Number(retryAfter);
    if (!isNaN(seconds) && seconds > 0) return seconds * 1_000;
  }
  return INITIAL_BACKOFF_MS * Math.pow(2, attempt); // 1s, 2s, 4s
}

private isRetryable(status: number): boolean {
  return status === 429 || (status >= 500 && status < 600);
}

The client doesn't watch x-ratelimit-remaining to slow down before the limit. It only reads that header for error messages and reacts to rate limits after a 429.

There's also a risk I should have thought through: the retry loop runs for POST and PUT as well. If create_article succeeds on the server but the response comes back as a 502, the client sends it again and you can end up with two copies of the same draft on DEV. Non-idempotent requests should only be retried when they provably never reached the server, or not at all.

The feature I switched off: reactions

#

The initial release had tools for leaving reactions (likes, unicorns and so on) on articles. During testing they started returning 401 even with a valid API key, and some calls reported success while nothing showed up on the site.

An assistant that says "done" when nothing happened is worse than a missing tool. On February 18 I took the reaction tools out of registration:

// registerReactionTools(server, client); // Disabled due to API 401 issues

The code is still in the repo for anyone who wants to track down the cause.

Drafts and the 404

#

get_article_by_id uses /articles/{id}, which only returns published articles and gives 404 for drafts. The assistant read that as "no such article," even though it existed.

On a 404, the tool now fetches all of the user's own articles, drafts included, from /articles/me/all and looks for the ID there. The flow is on the card, the code below it:

} catch (error: unknown) {
  const is404 =
    typeof error === "object" && error !== null && "status" in error &&
    (error as { status?: number }).status === 404;

  if (is404) {
    try {
      const allArticles = await client.get<Article[]>("/articles/me/all", { per_page: 1000 });
      const article = allArticles.find((a) => a.id === params.id);
      if (article) {
        return { content: [{ type: "text", text: JSON.stringify(article, null, 2) }] };
      }
    } catch (fallbackError) {
      console.error("Fallback lookup failed:", fallbackError);
    }
  }
  // ...
}

Note the console.error. In a stdio server, stdout carries the JSON-RPC messages, and any log line written there corrupts the protocol. Logs belong on stderr.

The fallback misses articles beyond the first 1,000, which is fine for someone with a few dozen posts like me.

Publishing, and a lesson about package names

#

How the workflow evolved

#

The first workflow was manual (workflow_dispatch) with a dry-run option. With v1.0.2 I switched the trigger to published releases:

on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: production
    steps:
      # checkout, setup-node (Node 22), npm ci, lint, typecheck, test, build
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

This workflow doesn't use OIDC trusted publishing. environment: production has been in it since its first committed version, and publishing authenticates with an NPM_TOKEN secret; id-token: write is there for the provenance signature. The npm 10 that ships with Node 22 can't do trusted publishing anyway; that needs npm 11.5.1 or later.

The environment line can still matter. If you define a secret on an environment instead of the repository, a job that doesn't name that environment sees an empty secret. And npm often answers unauthorized publishes with 404 rather than 403, so the error points you nowhere near the cause.

When I merged PR #1 with the reactions and draft changes, I expected a new release to go out on its own. It didn't: the trigger was a release, not a merge, and I hadn't bumped the version in package.json. Those changes shipped in v1.0.3 in March.

Moving to a scoped name

#

In February the package was published unscoped, as devto-mcp. In March I renamed it to @furkankoykiran/devto-mcp so it could also go to GitHub Packages, which requires scoped names.

That had a consequence I didn't expect. The unscoped devto-mcp name now belongs to a different project on npm, with a different maintainer, a different repository, and 0.x releases. The npx -y devto-mcp command in my DEV challenge article now runs that package instead of mine. An MCP server receives your API key through its environment, so a wrong package name here is a security problem.

Two rules came out of it: publish personal packages under a scope from day one and don't rename them later, and update every npx command in docs and posts the moment a package name changes. The latest README commit in the repo does exactly that.

Installing it

#

You need Node.js 18 or later and a DEV API key, which you can create under Settings → Extensions → "DEV Community API Keys". Add this to Claude Desktop's claude_desktop_config.json:

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

The file lives in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. After restarting Claude, try prompts like:

• "Summarize this week's most popular TypeScript articles."
• "Create this markdown file as a draft on my DEV account, tagged mcp and typescript."
• "List the comments on my latest article and pull out the questions that still need an answer."

Next steps

#

On my list: closing the POST retry risk above, moving the tools to the SDK's newer registerTool() API, and finding the cause of the reactions 401. The first real job I gave DevTo-MCP, having an assistant write and publish a challenge entry on DEV, is in the Gemini challenge post. Other servers in this series: OmniWire-MCP and freqtrade-mcp.

This post covers three parts: the per-source circuit breaker that keeps one broken feed from slowing down the rest, the parser that tells formats apart, and the string of failures I hit publishing to npm. I also point out three gaps I found when I reread the code, each in its section.

Project page: OmniWire-MCP · Source: GitHub

What the server exposes

#

It runs over stdio and registers four tools:

• fetch-news pulls items from enabled sources, optionally filtered by keyword or a single source, with a result limit.
• check-health reports each source's circuit state and failure counts.
• refresh-config reloads the source list from remote config.
• reset-source manually resets one source's circuit breaker.

fetch-news fetches all healthy sources in parallel with Promise.allSettled, merges the results, sorts them by date and returns the requested number. One failing source can't spoil the response; with Promise.all, a single rejection would throw away everything.

Sources come from the RSS_FEEDS environment variable. It can be a URL to a JSON file, in which case the server re-reads it every 60 seconds by default and you can add feeds without a restart. It can also be the JSON itself. If it's unset, the server starts with Hacker News, Wired and The Verge.

A circuit breaker per source

#

News sources break all the time. One site drops its RSS feed, another returns 503 for a few minutes, a third hangs without answering. Retrying them on every request is slow and pointless.

So each source gets its own circuit breaker. In the codebase this layer is called Sentinel, and it's the standard three-state pattern shown in the diagram:

In CLOSED, requests go through and failures are counted. When the count hits the threshold (3 by default), the circuit opens and no requests are sent to that source. After the recovery timeout (60 seconds by default) it moves to HALF_OPEN and the source gets another chance: two successes close the circuit, a single failure opens it again.

The method that decides:

public canExecute(): boolean {
  const currentState = this.getState();

  if (currentState === CircuitState.CLOSED) return true;
  if (currentState === CircuitState.HALF_OPEN) return true;

  if (this.shouldAttemptRecovery()) {
    this.transitionTo(CircuitState.HALF_OPEN);
    return true;
  }
  return false;
}

fetch-news filters out open circuits with canRequest() before sending anything. If 5 of 20 sources are down, the assistant gets the other 15 without waiting on timeouts. Each request also has a 10-second timeout, so a source that never answers counts as a failure instead of hanging forever.

There's a gap here. The comment says "allow one test request" in HALF_OPEN, but the code returns true for every request in that state. If several fetch-news calls arrive at once, they all hit the half-open source. On a single-user stdio server that rarely matters, but the correct behavior is to track the in-flight probe with a flag and reject the others until it resolves.

Detecting the content type

#

Sources come in every shape: RSS 2.0, Atom, JSON APIs, and HTML for sites without a feed. Each source config has a type field that defaults to auto, and in that case the parser guesses:

public detectContentType(content: string, contentTypeHeader?: string): ContentType {
  if (contentTypeHeader) {
    const lower = contentTypeHeader.toLowerCase();
    if (lower.includes('rss') || lower.includes('atom')) return ContentType.RSS;
    if (lower.includes('json')) return ContentType.JSON;
    if (lower.includes('html')) return ContentType.HTML;
    if (lower.includes('xml')) {
      return content.includes('<feed') ? ContentType.ATOM : ContentType.RSS;
    }
  }

  const trimmed = content.trim();
  if (trimmed.startsWith('<?xml') || trimmed.startsWith('<rss') || trimmed.startsWith('<feed')) {
    return trimmed.includes('<feed') ? ContentType.ATOM : ContentType.RSS;
  }
  if (trimmed.startsWith('[') || trimmed.startsWith('{')) return ContentType.JSON;
  if (trimmed.toLowerCase().startsWith('<!doctype') || trimmed.toLowerCase().startsWith('<html')) {
    return ContentType.HTML;
  }

  return ContentType.UNKNOWN;
}

This code misclassifies servers that send XML as text/html. The header is checked first, and any header containing html is classified as HTML without looking at the body. Sniffing only kicks in when the header is missing or unrecognized, like application/octet-stream or text/plain.

The fix is to reverse the order: look at the first bytes of the body first and fall back to the header only when the body is ambiguous. The first bytes of a body reliably show its format, while headers are sometimes wrong. Until then, setting type: "rss" in the source config works around it.

One Zod schema for every item

#

All adapters produce the same shape:

export const NewsItemSchema = z.object({
  id: z.string(),
  title: z.string(),
  link: z.string().url(),
  description: z.string().optional(),
  content: z.string().optional(),
  author: z.string().optional(),
  publishedAt: z.date().optional(),
  categories: z.array(z.string()).default([]),
});

export type NewsItem = z.infer<typeof NewsItemSchema>;

With z.infer I don't write the TypeScript type separately, so the schema and the type can't drift apart.

The schema doesn't catch malformed items at runtime, though. The adapters only use it for the type and never call parse on what they produce, so an item with an invalid link still reaches the assistant. The fix is to run adapter output through the schema and drop what fails:

const items = candidates.flatMap((candidate) => {
  const parsed = NewsItemSchema.safeParse(candidate);
  if (!parsed.success) {
    logger.warn(`Dropped invalid item from ${source.id}: ${parsed.error.message}`);
    return [];
  }
  return [parsed.data];
});

Source configuration, on the other hand, really is validated with Zod. Malformed JSON in RSS_FEEDS doesn't crash the server; it logs the error and falls back to the default sources.

Repository hygiene

#

It's a small project, but I set the repo up so other people could contribute. main is protected by an active ruleset, and changes go in through PRs. There's a CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, and issue and PR templates. CI runs tests and lint, CodeQL scans for security issues, and stale.yml labels issues and PRs after 30 days of inactivity and closes them 5 days later.

Adding all of that on day one can feel like overkill. It's also the stuff nobody gets around to adding later, and the first thing a newcomer looks for.

Publishing to npm: four failed runs

#

The goal was simple: create a release on GitHub, and a workflow runs the tests, builds, and publishes to npm. In practice I had one failed run before the first successful publish, and three more when I added GitHub Packages. The workflow history shows all of it:

A missing environment: production line wasn't the problem; this workflow never had one. Here's what actually happened.

v1.0.2 failed, v1.0.3 worked

#

package.json had "provenance": true. npm provenance records which workflow built the package, signed, and to do that it needs an OIDC token from GitHub Actions. The workflow didn't grant that permission. On top of that, files only shipped dist, but nothing ran the build before publishing, so the package would have gone out empty. The fix:

permissions:
  contents: read
  id-token: write

# in the publish-npm job
      - run: npm ci
      - run: npm run build
      - run: npm publish   # provenance still came from package.json here
        env:
          NODE_AUTH_TOKEN: ${{ secrets.npm_token }}

v1.0.4 and v1.0.5: npm passed, GitHub Packages failed

#

In March I added a second job to also publish to GitHub Packages. Because "provenance": true lived in publishConfig, it applied to both registries, and provenance is only supported on npmjs.com. In v1.0.6 I removed it from package.json and passed --provenance only in the npm job, and both publishes went through.

Everything in publishConfig applies to every registry the package is published to. Keep registry-specific behavior in command-line flags.

What I'd do today

#

Starting fresh today, I'd drop the token entirely. npm trusted publishing uses the GitHub Actions OIDC token directly and adds provenance automatically. You link the package to the repo and workflow file on npmjs.com, grant id-token: write, and use npm CLI 11.5.1 or later. The npm 10 that ships with Node 20 doesn't support it, so either move to Node 24 or run npm install -g npm@latest in the job. Then there's no NPM_TOKEN in the repo to expire or leak.

Installing it

#

Node.js 18 or later is enough. For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "omniwire": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/omniwire-mcp"],
      "env": {
        "RSS_FEEDS": "https://example.com/my-feeds.json"
      }
    }
  }
}

Note the scoped package name. An unscoped npx omniwire-mcp doesn't work, because no package by that name exists. Leave out RSS_FEEDS to start with the three default sources.

There's no published Docker image; build it from the repo's Dockerfile:

git clone https://github.com/furkankoykiran/OmniWire-MCP.git
cd OmniWire-MCP
docker build -t omniwire-mcp .
docker run -i --rm -e RSS_FEEDS="https://example.com/my-feeds.json" omniwire-mcp

Keep -i: the server talks over stdio and exits when stdin closes.

Next steps

#

First the three fixes above: a single probe in HALF_OPEN, sniffing the body before trusting the header, and validating items against the Zod schema. After that I want to move tool definitions from server.tool() to registerTool(), since the MCP TypeScript SDK is deprecating the old API, and change the Dockerfile's npm ci --only=production to npm ci --omit=dev. Longer term, writing items into a vector store would allow semantic questions like "what came out about X last month?"

Other servers in this series: DevTo-MCP for the DEV Community API, and freqtrade-mcp for asking a trading bot questions through Claude. I also wrote about running CI on my own machine in the self-hosted runner post.

Try the app · Source code · Project page

This post walks through how it works, the 3D card flip that ate most of my time, and two bugs I found when I reread the code.

Why build my own

#

Duolingo feels too gamified to me and doesn't focus on the words I pick. Most of Quizlet's useful features are behind a paywall. Anki's scheduling is excellent, but the interface is dated and desktop-first. I wanted my own decks, a clean UI that opens in a browser, and a proper review algorithm underneath.

I wrote it on the night of February 5, 2026, in a session of roughly two hours. All 25 commits in the repo are from that night, and some of the bugs below come straight from that pace.

Stack and architecture

#

• React 19 and TypeScript, built with Vite 7.
• Tailwind CSS 3 for a dark, glassy UI.
• Framer Motion 12 for animation.
• Supabase for the PostgreSQL database and email/password auth, password reset included.
• react-i18next for English and Turkish, picked from the browser language.
• React Router 7, deployed to GitHub Pages by a GitHub Actions workflow.

There's no backend of my own; the browser talks to Supabase directly. The data model is two tables: decks, and cards, which holds each card's front, back and review state.

GitHub Pages doesn't support SPA routing, so the workflow generates a 404.html and the router uses /Memoryze as its basename. Opening a deep link like /Memoryze/dashboard then loads the app instead of a 404.

SM-2: when cards come back

#

SM-2 is SuperMemo's algorithm from the late 1980s, and Anki's default scheduler is based on it. It tracks three numbers per card: how many times in a row you got it right (repetition), an ease factor (ef) and the interval in days (interval). The card below shows what a grade does, and the Memoryze code follows it:

export const calculateSM2 = ({ q, repetition, ef, interval }: SM2Input): SM2Output => {
  let newRepetition = repetition;
  let newInterval = interval;

  if (q >= 3) {
    if (repetition === 0) newInterval = 1;
    else if (repetition === 1) newInterval = 6;
    else newInterval = Math.round(interval * ef);
    newRepetition += 1;
  } else {
    newRepetition = 0;
    newInterval = 1;
  }

  // EF' = EF + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02)), floor of 1.3
  let newEf = ef + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02));
  if (newEf < 1.3) newEf = 1.3;

  const nextReviewDate = new Date();
  nextReviewDate.setDate(nextReviewDate.getDate() + newInterval);

  return { repetition: newRepetition, ef: newEf, interval: newInterval, nextReviewDate };
};