Building with AI assistants

PyWeb is designed to be easy for AI coding tools to write correctly: one file per app, plain Python, and a compiler that rejects mistakes with a line number instead of failing at runtime. Three things help assistants get it right:

1. an MCP server (pyweb mcp) that gives any MCP-capable assistant tools to scaffold, check, inspect, render and test apps;
2. AGENTS.md / CLAUDE.md written into every new project, so agents follow PyWeb's rules even without MCP;
3. llms.txt on the docs site for tools that read documentation.

#The MCP server

The tools below are those of pyweb-stack 0.4.1 (pip install -U pyweb-stack; older versions have fewer: pyweb_routes, pyweb_packages and the task prompts arrived in 0.4.1, pyweb_screenshot and pyweb_test in 0.3.0). Install PyWeb, then register the server with your assistant. It talks over stdio and has no dependencies beyond PyWeb itself.

Claude Code

claude mcp add pyweb -- pyweb mcp

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf, VS Code and other MCP clients use the same shape:

{
  "mcpServers": {
    "pyweb": { "command": "pyweb", "args": ["mcp"] }
  }
}

If pyweb isn't on the assistant's PATH (for example, it lives in a virtual environment), use the full path to the executable, or "command": "python", "args": ["-m", "pyweb.cli", "mcp"] with that environment's Python.

Paths given to the tools are relative to the directory the server starts in, which is normally your project.

#Tools

The server also exposes the guide and every template as resources (pyweb://guide, pyweb://templates/<name>) and three prompts: build_pyweb_app (scaffold → edit → check → verify), add_ai_feature (a streaming AI feature with Stop and Markdown in an existing app) and make_data_live (switch pages to live queries).

#What a session looks like

1. The assistant reads pyweb_guide.
2. It scaffolds with pyweb_new_app (for example template="blog").
3. It edits app.pyweb and calls pyweb_check after each change. An error comes back as {"line": 8, "message": "'sqlite3' only exists on the server ...", "hint": "Move that logic into an @server function and call it from the handler."}.
4. It confirms the result with pyweb_render (each page) and pyweb_call (each server function), and looks at the page with pyweb_screenshot, clicking and typing through the flow it built.
5. It adds tests to test_app.py and runs them with pyweb_test.
6. You run pyweb dev app.pyweb and try it.

pyweb_render, pyweb_call, pyweb_screenshot and pyweb_test run your app's code, as pyweb dev or pytest would, and pyweb_packages writes files and downloads packages. Assistants generally ask before calling them.

#AGENTS.md and CLAUDE.md

pyweb new myapp --template todo writes:

myapp/
  app.pyweb
  test_app.py    a starter test (pyweb.testing.TestClient); run with pytest
  AGENTS.md      the PyWeb rules and workflow for coding agents
  CLAUDE.md      "@AGENTS.md" (Claude Code imports it)
  static/app.css
  .gitignore

AGENTS.md is read by most coding agents (Codex, Cursor, Aider, Jules, …) and CLAUDE.md by Claude Code. They contain the same guide the MCP server serves, plus the commands to check and run the app.

#llms.txt

The docs site publishes:

• llms.txt: an index of the documentation with one-line summaries;
• llms-full.txt: the AI guide followed by every docs page, in one file.

Point a chat assistant at llms-full.txt when it can't run tools.

#Tips for prompting

• Say "use PyWeb" and mention that the app is a single app.pyweb file.
• Ask the assistant to run pyweb check (or pyweb_check) after every edit and to fix errors by line number.
• For anything touching a database, files, secrets or third-party APIs, ask for an @server function; handlers run in the browser.
• Ask for pyweb inspect output when you want to know what data reaches the browser.
• Name the feature you want: "a layout with a nav", "make this list live", "stream the answer with a Stop button", "add chart.js". The guide has a section for each, so the assistant uses the built-in way instead of writing polling or fetch code by hand.