SEO Page Checker

This MCP server fetches any public web page. It answers two SEO questions: what does its SEO foundation look like? and how readable is its prose?

What is MCP? MCP ("Model Context Protocol") is a standard way for an AI assistant to use tools. A "server" like this one publishes tools and answers requests to run them. Claude Code connects to this server's URL and sees two tools. It can run either one on any web page you ask about.

This repository is written to be read by someone who is not a software engineer. You can read it from start to finish in an afternoon. Every file starts with a short "what this file is" note in plain English. Every decision in the code is explained where it happens.

---

What this server does

Tool	What it answers
inspect_page(url)	A snapshot of the page's on-page SEO foundation: Title, meta description, canonical URL, Open Graph tags, robots meta, heading outline (H1–H6), and image-alt coverage.
check_readability(url)	Every sentence that is too long (more than 20 words) and every paragraph with too many sentences (more than 5), each located, quoted, and measured.

Both tools fetch the live page over the internet, so they work on any public URL.

What's in the repo

api/mcp.ts             The whole MCP server. What Claude Code talks to.
lib/fetch.ts           Fetches a web page, politely and safely.
lib/analyze.ts         Runs both tools against one page's HTML.
lib/headSnapshot.ts    The inspect_page answer (the SEO snapshot).
lib/prose.ts           Finds the real prose of a page (paragraphs, not menus).
lib/finders.ts         The two readability checks.
lib/segmentation.ts    Splits text into sentences (carefully).
lib/head.ts            Reads the <title> and <meta> of a page.
lib/dom.ts, nodeDom.ts The "browser" the checks read pages with.
lib/*.test.ts          The tests, one next to each file they test.
api/mcp.test.ts        The "whole server answers" test (talks to api/mcp.ts itself).
vercel.json            The platform's settings (the function's time budget).

That is the whole thing. The server is one file (api/mcp.ts); it does not sit inside a web framework. Vercel sees the file in its api/ folder and turns it into a live internet endpoint. Everything else in the repo either helps that one file do its job (lib/) or proves it works (the tests).

Read the code in this order

1. api/mcp.ts — start here. It is the entry point: what a client sees, the two tools, and the request flow from "give me a URL" to "here is your answer".

2. lib/fetch.ts — how a page is fetched, and how failures are answered kindly instead of with an error.

3. lib/analyze.ts — the one place that runs both tools against fetched HTML.

4. lib/headSnapshot.ts — the inspect_page answer, built up from small helpers.

5. lib/prose.ts — what counts as prose (and what does not), and how a page is split into paragraphs.

6. lib/segmentation.ts — how a paragraph is split into sentences without stumbling on "Dr." or "e.g."

7. lib/finders.ts — the two readability checks themselves, and their limits.

8. lib/head.ts, lib/dom.ts, lib/nodeDom.ts — the tiny helpers everything above leans on.

Each file's header explains why the file exists before any code runs.

Run it locally

You need Node.js 20 or newer.

npm install
npm test        # the quickest way to know everything works
npm run dev     # run the server locally, via the Vercel CLI (asks you to log in)

The local server is then at http://localhost:3000/api/mcp. (The tests are the no-login way to run the code; they exercise every piece of it with pretend pages.)

Try it in Claude Code

Connect Claude Code to a running copy:

claude mcp add --transport http seo-page-checker http://localhost:3000/api/mcp

Then in the conversation, ask for either check on any public page:

Run check_readability on https://example.com

Deploy it (free, on Vercel)

This server is built to deploy with zero configuration:

1. Push this repository to your GitHub account.

2. Go to vercel.com and sign up free, then Add New → Project → Import this GitHub repo. Vercel recognises the api/ folder on its own — leave every setting at its default and click Deploy.

3. Vercel gives your server a public URL, something like https://seo-page-checker.vercel.app.

4. Point Claude Code at the live URL:

   claude mcp add --transport http seo-page-checker https://seo-page-checker.vercel.app/api/mcp
   

Every time you push to GitHub, Vercel redeploys automatically. The checks in .github/workflows/ci.yml run first, so a broken change never reaches the live server.

How we know it works

The tests sit next to the code they test (a file named lib/finders.test.ts tests lib/finders.ts). Each one feeds the code a small pretend page and checks the answer. The test command npm test runs them all, and npm run typecheck runs the type checker.

GitHub runs both on every push. There is no "build" step. Vercel compiles the one function itself when it deploys, so the tests and type check are all CI needs.

One test is different: api/mcp.test.ts talks to the actual server file, the way a real client would. It swaps the internet for a pretend page. It is how we know the whole thing answers before it is ever deployed.

The tests never touch the internet — they use pretend pages, so they are fast and dependable.

This repo also checks its own words. The wiki and this README are read by the same readability tool that powers check_readability. Right now every page passes. Run npm run docs:check any time after you edit, and you will see if your changes still pass too.

What it does not do

• It reads the whole page. The analysis walks everything the page contains — menus and footers included — not just the main article. A fancier version would find just the article; this one keeps it simple on purpose. It also means a page with a very long sentence in its navigation will mention it.
• It only reads what is public. No logins, no page source editing, no screenshots.
• It is not the full audit. Your employer might have a full SEO audit product; this is deliberately just two of its building blocks, kept small enough to read.

Other paths

Vercel is our choice because the whole server fits in one readable file. There is also a one-command Cloudflare template for MCP servers. It is even less work to get running — a fine do-it-yourself path if you want to experiment.

---

This is a teaching project. Its two tools are the sentence-length and sentences-per-paragraph finders. It also makes a head/meta snapshot — real, working, and deliberately small.