# IDEA: a blog of your own with admin, API and MCP, built with Claude A description and a ready-made prompt for building a blog like **verkstad_**: fast, pre-rendered and search-engine friendly for readers, with its own admin panel, an API and an MCP server so that Claude can write posts directly. Copy the prompt at the bottom, adjust what is in [brackets] and give it to Claude Code in an empty directory. ## The idea in brief - **Public pages are plain HTML** from the server, not a JavaScript app. They load instantly, work without JavaScript and get indexed without fuss. - **The admin is a separate app** (React) that only you see, at an address you choose. - **One API** is used by the admin, by scripts with an API key and by the MCP server. Every rule (validation, slugs, tags, conflict protection) lives in one place. - **The MCP server** lets Claude read the writing guide, create drafts, upload images and attach files. It only publishes when you ask it to. - **No external dependencies in the browser:** fonts and everything else are served from your own server. No CDN, no Google Fonts, no tracking. - **Two languages:** Swedish at the root, English under /en/, with its own slugs, hreflang links and translations written by Claude on request. ## What you need - A design. We made ours in Claude Design and got a handoff folder with an HTML prototype and a README with colours, typography and every screen. A sketch or an existing site to start from works too. - A server with PHP 8.3 and MariaDB/MySQL, or the stack you prefer. - Docker locally, so that the development environment looks like production. ## Decisions that turned out to matter 1. **The same directory layout locally as in production.** The blog lives in a sub-directory (`/verkstad/`) of a larger site. Code that assumes it owns "/" only breaks in production – unless it runs in a sub-directory locally too. 2. **Secrets outside the docroot.** The database password and the PHP code live in `private/verkstad/`. The web only reaches `public/verkstad/`. 3. **Finished HTML + a file cache.** Every page is saved as a file and served without a database query. The cache is emptied on every change, whether it comes from the admin, the API or MCP. 4. **One markdown dialect, two identical parsers** (PHP and TypeScript), tested against the same examples. The editor's preview is then exactly the published page. 5. **Drafts save themselves, published posts don't.** Changes to a published post only appear when you press Update. 6. **Conflict protection.** Every change carries the version it started from. If someone else (another tab, or Claude via MCP) got there first, the answer is 409 instead of a silent overwrite. 7. **Tests in a real browser.** A bug that crashed all navigation in the admin (`window.scrollTo` returns a Promise in newer browsers) didn't show up in ordinary tests. Test with the same behaviour your readers' browsers have. 8. **An issue tracker from day one.** We used Linear: what is built and verified, what is waiting for someone to try it, and what is waiting for a decision. It keeps the work understandable across many sessions. ## The prompt ``` Build a personal blog with an admin panel, an API and an MCP server. Stack: PHP 8.3 + MariaDB with no framework and no PHP dependencies, Apache with .htaccess, local development in Docker. Admin in React 18 + Vite + TypeScript. Design: see [the design/ directory — an HTML prototype and a README with design tokens, typography and every screen]. Recreate it as exactly as possible, in light and dark themes. No rounded corners, no shadows [or: your own design rule]. Public site: - Pre-rendered HTML from PHP templates, works without JavaScript. - Pages: home, archive (tag filter, pagination), post, about, RSS page, 404, 500 (the 500 page must work with the database down). - SEO: title, meta description, canonical, Open Graph, JSON-LD, sitemap.xml, RSS 2.0 (all posts and per tag), real status codes. - Whole pages cached as files, the cache emptied on every change. - Images with srcset (400/800/1600 px). No requests to other hosts: self-host the fonts. - The blog lives in the sub-directory [/blog/] of a larger site. Run it that way locally too. Code and storage live outside the docroot: /[site]/public/[blog]/ and /[site]/private/[blog]/{app,storage}/. - A setting to close the site to visitors (503, only the logo shows) while a logged-in admin sees it as usual. - [Optional] Two languages: [Swedish] at the root, [English] under /en/, each post with its own slug per language, hreflang links and a language switcher. Admin (at an address you choose, not /admin): - Login with "remember me", CSRF protection and a lock against guessing. - Posts: list, editor with a markdown toolbar and a preview that uses the same parser as the site, autosaved drafts, conflict protection. - Media: upload, alt text, where each image is used. Uploads live in a directory per post and follow the post if its slug changes. - Files attached per post (zip, md, pdf and so on), always as a download. - Tags, settings, and API keys (read / read + write) shown only once. API: /api/v1/ with the same rules for the admin session and for API keys. All business logic in a repository layer that the API and MCP share. MCP server: Streamable HTTP in the same PHP app, stateless, authenticated with an API key. Tools: writing guide, list/get/create/update/publish/delete posts, upload image, attach file[, save translation]. New posts become drafts. Way of working: - Plan first and ask about whatever is a real decision. - Keep one issue per change [in Linear / GitHub Issues], with what was measured. - "Done" means tested: smoke test (curl), API test, markdown parity and a browser test (Playwright) of the admin. Run the tests in the same directory layout as production. - No passwords in versioned files. ``` ## What it became Just under 80 source files: about 3,600 lines of PHP and 2,400 lines of TypeScript and CSS for the admin. No PHP dependencies. Public pages of about 95 kB, scoring 100 in Lighthouse's four categories. Four test suites with around 140 checks in total. The post this file belongs to was written and uploaded by Claude through the blog's own MCP server.