This gist is meant to be copied into an AI coding agent — Pi, Claude Code, Cursor, etc. — together with a book URL or file. The agent should be able to build a useful book-powered MCP server, an AI-agent skill, or both.
It is not the Book Power source code and not a description of Book Power internals. It is a compact public build spec so other people can create compatible artifacts, publish them, and submit them to the catalog at bookpower.org.
A good book-powered artifact does not recreate the book. It makes the book's methods usable inside an AI workflow: frameworks, checklists, workflows, questions, examples, principles, warnings, and source-backed guidance.
You are building a book-powered AI artifact.
Input:
Book source: {URL, local file, or directory}
Artifact: {mcp | skill | both}; optional advanced output: {command}
Target user/work: {who will use it and what they need to do}
Known license/permission: {public domain, CC license, author/publisher permission, private-use only, or unknown}
Hosting target: {local stdio | npm package | Railway | other remote HTTP | none}
Output directory: ./book-powered-{slug}
Goal:
Build a practical MCP server and/or AI-agent skill that helps an assistant apply the book's methods while doing real work. Do not create a chapter dump or generic summary.
Rights rules:
Only publish what the user has the right to publish. Public-domain, CC0, CC BY, CC BY-SA, and CC BY-NC-SA sources can usually produce public artifacts if attribution and license terms are preserved. NoDerivatives licenses, unknown licenses, and ordinary copyrighted books should default to private unless the user has permission. Keep source citations for extracted guidance. Do not impersonate the author or claim endorsement.
Build steps:
1. Ingest the book from the provided source. If extraction is poor, say so and suggest a better extractor/OCR path.
2. Decide the book's extraction discipline: prescriptive, descriptive, dialectical, or procedural. Do not force rules onto a book that is only describing patterns.
3. Identify the practical method layer: frameworks, checklists, workflows, diagnostic questions, principles, examples, warnings, and short essential quotes.
4. Create a structured dataset using the TypeScript contract below.
5. Generate the requested artifact using the file layout below. Start generic, then specialize tool names and workflows to the book's actual use cases.
6. Add a README with source, rights, install instructions, examples, hosting notes, and catalog-submission notes.
7. Run a smoke test. Fix obvious build or runtime errors.
8. Stop and report files created, how to run them, and any rights/citation concerns.
For an MCP server:
book-powered-{slug}/
package.json
tsconfig.json
README.md
src/
data.ts
index.ts
For a skill:
book-powered-{slug}-skill/
SKILL.md
references/
book-info.md
frameworks.md
workflows.md
principles.md
If building both, generate both directories from the same structured extraction.
The source can be a URL, local file, or directory of chapters. Common inputs: HTML, PDF, EPUB, DOCX, PPTX, Markdown, and plain text.
For clean HTML/Markdown/text, local extraction is usually enough. For difficult PDFs, scans, tables, or complex layouts, the agent may need a better extractor or OCR service such as Datalab or an equivalent. Those services can require API keys and may take time. The agent should report extraction quality before building the artifact.
Do not silently build from a broken extraction. Bad extraction creates bad tools.
Before extracting methods, decide how the book argues:
prescriptive — rules, principles, checklists, strong defaults, anti-patterns
descriptive — patterns, history, cases, analysis, ethnography
dialectical — tensions between positions; unresolved tradeoffs matter
procedural — steps, recipes, triggers, branching decisions, exit conditions
This is a guardrail against hallucination. A descriptive book should not become a fake checklist of MUSTs. A procedural book should preserve sequence and decision points. A dialectical book should preserve tensions instead of flattening them into simple advice.
A generic MCP can expose search_book, get_framework, and get_workflow. A better book-powered MCP adapts to the book's domain.
Examples: a facilitation book might need suggest_activity; a research book might need get_interview_questions; a governance book might need get_failure_mode; a strategy book might need choose_framework; an OSS book might need audit_project.
Start with the shared data contract, but name tools around the work practitioners actually do.
This is the quality bar. The same book can produce a weak artifact or a useful one — the difference is specialization and citations, not volume.
Weak (a chapter dump — do not do this):
get_chapter("communications") -> returns 4,000 words of the Communications chapter
That just relocates the book. The model still has to do all the work, and you've likely redistributed copyrighted text.
Good (a specialized, cited tool): Producing Open Source Software (Karl Fogel) is a methodology book about running healthy OSS projects. Its method layer is a project-health audit across ten areas. Extract it as a Framework, then expose an audit_project tool.
src/data.ts (one populated entry):
export const FRAMEWORKS: Framework[] = [
{
id: "oss-health-audit",
name: "OSS Project Health Audit",
summary:
"Ten areas that determine whether an open-source project can attract and keep contributors.",
whenToUse: [
"evaluating a new or inherited OSS project",
"before a public launch or a push for outside contributors",
"diagnosing why a project gets users but not contributors",
],
stepsOrFields: [
"Identity & presentation - clear name, one-line description, obvious purpose",
"Documentation - README, CONTRIBUTING, install/build that actually works",
"Contributor experience - low-friction first patch, visible 'good first issues'",
"Technical infrastructure - version control, bug tracker, public archives",
"Versioning & releases - predictable scheme, release-early/often, changelog",
"Licensing & legal - explicit OSI license, copyright clarity, CLA stance",
"Governance - stated decision model (benevolent dictator vs. consensus)",
"Communication - public by default, 'conspicuous' so newcomers can follow",
"Automation & maintenance - CI, tests, reproducible builds",
"Health signals - recent activity, multiple committers, responsive maintainers",
],
pitfalls: [
"A missing CONTRIBUTING guide silently filters out the contributors you want.",
"Private decisions (DMs, side channels) make the project illegible to newcomers.",
"Marking something 'done' when it's only half-present - use a partial state.",
],
tags: ["oss", "governance", "community", "maintenance"],
citations: [
{ source: "Producing Open Source Software", chapter: "Technical Infrastructure", url: "https://producingoss.com/" },
{ source: "Producing Open Source Software", chapter: "Social and Political Infrastructure", url: "https://producingoss.com/" },
{ source: "Producing Open Source Software", chapter: "Communications", url: "https://producingoss.com/" },
],
},
];Specialized tool, on top of the generic ones:
audit_project(signals) -> for each of the ten areas: pass / partial / fail,
the single highest-leverage fix, and a citation
A real call returns something the client can act on, not paraphrase:
contributor experience FAIL No CONTRIBUTING.md and no labeled starter issues.
Fix: add CONTRIBUTING with a 5-minute first-patch path.
- Producing OSS, "Social and Political Infrastructure"
licensing & legal PARTIAL LICENSE present but no copyright/CLA stance stated.
Fix: state the contribution license in CONTRIBUTING.
- Producing OSS, "Licenses, Copyrights, and Patents"
Note what makes this good: tool names map to the work (audit_project, not get_chapter), every output is cited, and data.ts holds the method, never the book's full text.
The agent should create src/data.ts for the MCP server, and should use the same shape to write the skill reference files.
export type Citation = {
source: string;
chapter?: string;
section?: string;
page?: string;
url?: string;
};
export type BookInfo = {
title: string;
author: string;
source: string;
license: string;
attribution: string;
summary: string;
rightsNote: string;
};
export type Concept = {
id: string;
name: string;
summary: string;
whenUseful: string[];
tags: string[];
citations: Citation[];
};
export type Framework = {
id: string;
name: string;
summary: string;
whenToUse: string[];
stepsOrFields: string[];
pitfalls?: string[];
tags: string[];
citations: Citation[];
};
export type Workflow = {
id: string;
name: string;
summary: string;
trigger: string;
steps: string[];
outputs: string[];
tags: string[];
citations: Citation[];
};
export type QuestionSet = {
id: string;
name: string;
purpose: string;
questions: string[];
tags: string[];
citations: Citation[];
};
export const BOOK_INFO: BookInfo = { /* filled by agent */ };
export const CONCEPTS: Concept[] = [];
export const FRAMEWORKS: Framework[] = [];
export const WORKFLOWS: Workflow[] = [];
export const QUESTION_SETS: QuestionSet[] = [];Keep entries concise. Do not put the whole book into data.ts. If the source license does not allow redistribution, use summaries and citations instead of long excerpts.
There are two valid ways to make the book useful to an MCP client. Start with structured retrieval unless you have a clear reason to add embeddings.
Default: structured, no embeddings. Extract the book's method layer into typed data: frameworks, workflows, principles, question sets, examples, warnings, and citations. Search can be deterministic over names, summaries, tags, steps, and citation fields. This needs no vector database, no runtime LLM, and no embedding API key. It is often the best fit for methodology books because users usually need the right tool, checklist, or next step — not a semantically similar paragraph.
Optional: embeddings / semantic search. Add embeddings when the book is large, essayistic, passage-heavy, or when users need fuzzy retrieval across the full text. This can improve recall, but it adds cost, API keys, processing time, storage, and more moving parts. If embeddings are used, keep them as a build-time index or optional module; the MCP server should still expose practical, cited tools rather than become only a vector-search wrapper.
If rights are restricted, do not put copyrighted full-text chunks into a public vector index. Store only what the license or permission allows.
Use TypeScript and @modelcontextprotocol/sdk. Support stdio first. Do not call an LLM inside the server; the server exposes structured book knowledge and the client model reasons with it.
Recommended tools:
get_book_info
search_book
list_frameworks
get_framework
list_workflows
get_workflow
list_question_sets
get_question_set
get_principles
suggest_next_step
The exact tools should match the book. A facilitation book may need suggest_activity; a research book may need get_interview_questions; a governance book may need get_design_pattern or get_failure_mode.
search_book can be simple deterministic search over names, summaries, tags, and steps. suggest_next_step can be deterministic matching over tags and descriptions. The point is reliability, citations, and practical retrieval — not an embedded chatbot.
Minimal package.json:
{
"name": "book-powered-{slug}-mcp",
"version": "0.1.0",
"type": "module",
"bin": {
"book-powered-{slug}-mcp": "./dist/index.js"
},
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.29.0"
},
"devDependencies": {
"@types/node": "latest",
"typescript": "^6.0.0"
}
}The README should show how to build it and how to add it to Claude Desktop or another MCP client with a local stdio command.
Example local Claude Desktop config:
{
"mcpServers": {
"book-powered-{slug}": {
"command": "node",
"args": ["/absolute/path/book-powered-{slug}/dist/index.js"]
}
}
}Not every MCP server needs hosting. Choose the smallest deployment surface that matches the rights and audience.
Local stdio. The simplest default. The user runs the server locally through Claude Desktop, Claude Code, Cursor, or another MCP client. This is best for private books, prototypes, and artifacts that should not be publicly reachable. No web server is required.
npm / package distribution. Publish the server as a package so users can run it with npx or install it locally. This still uses local stdio, but distribution is easier. Only do this for content you can redistribute.
Remote HTTP MCP server. Host the server when users should connect by URL, when you want zero local setup, or when access should be centrally managed. Use Streamable HTTP transport where supported. Dual transport — stdio for local use plus HTTP for hosted use — is preferred when practical. Add a /health endpoint, read PORT from the environment, and add Bearer-token auth for private or restricted content.
Railway. Railway is a good default for Book Power-hosted servers and a future Book Power Railway template would make this one-click: GitHub repo in, Node service out, PORT set automatically, /health check, optional MCP_AUTH_TOKEN, and a public or private MCP URL. But Railway should be an option, not a requirement. The same server shape should also run on Render, Fly.io, Cloud Run, a VPS, or any Node host.
No hosting for skills. A skill is just files installed into an agent environment. It does not need a server unless it calls a separate MCP or API.
For public open-license books, a public remote MCP can be fine. For copyrighted or permission-limited books, prefer local stdio or a remote server with authentication. Never expose restricted source-derived content at an unauthenticated public URL.
If the user asks for Railway deployment, generate these extra files or notes:
railway.json or Railway service settings
HTTP transport in addition to stdio
/health route
PORT environment support
optional MCP_AUTH_TOKEN Bearer auth
README section: Railway deploy and environment variables
SKILL.md should teach an AI assistant when and how to use the book-derived material. It should not pretend to be the author.
Use this structure:
# {Book-derived skill name}
## When to use this skill
Use this skill when the user wants to apply methods from {BOOK_TITLE} to {TARGET_WORK}.
## Workflow
1. Clarify the user's real situation and desired output.
2. Select the relevant framework, workflow, principle, or question set from `references/`.
3. Ask only for missing inputs needed to apply it.
4. Produce a practical artifact: audit, plan, checklist, interview guide, workshop agenda, decision memo, critique, or next-step recommendation.
5. Cite the relevant book-derived reference.
6. Separate source-backed guidance from general reasoning.
## Guardrails
Do not impersonate the author. Do not invent source-backed rules. Do not quote long passages unless rights allow it. Say when the book does not cover the user's case.
## References
Load only what is needed:
- `references/book-info.md`
- `references/frameworks.md`
- `references/workflows.md`
- `references/principles.md`Reference files should be compact and cited. They are working notes for the agent, not a replacement for the book.
Every generated artifact should include a README with:
What this is
What it helps practitioners do
Source book, author, edition, and URL/file source
License/rights and attribution
Install instructions
Hosting/deployment instructions, if applicable
Example prompts or use cases
Limitations and non-endorsement note
How to submit to bookpower.org
Recommended non-endorsement note:
This tool is not affiliated with or endorsed by the author or publisher unless explicitly stated. It is a source-backed aid for applying ideas from the book, not a replacement for reading the book.
For an MCP server, the agent should run:
npm install
npm run build
node dist/index.jsThen test at least get_book_info and one retrieval tool through an MCP client or a small local script. If a full client test is not available, the agent should at minimum verify that the server starts without crashing and that TypeScript compiles.
For a skill, the agent should simulate one realistic user request and verify that the skill selects a relevant reference and produces a practical, cited output.
So the catalog can ingest your artifact without hand-parsing a comment, include a book-power.json at the root of the generated artifact:
{
"manifestVersion": "1",
"title": "Producing Open Source Software",
"author": "Karl Fogel",
"edition": "2nd",
"source": "https://producingoss.com/",
"artifact": "mcp",
"slug": "producing-oss",
"visibility": "public",
"license": "CC BY-SA 4.0",
"rightsStatus": "open-license",
"attribution": "Based on Producing Open Source Software by Karl Fogel (CC BY-SA).",
"install": {
"type": "stdio",
"command": "npx book-powered-producing-oss-mcp"
},
"domain": ["open source", "governance", "community"],
"helps": "Audit an OSS project's health and prioritize the highest-leverage fixes.",
"endorsed": false
}Field notes:
artifact mcp | skill | both
visibility public | private
rightsStatus public-domain | open-license | permission-granted | private-only | unknown
install.type stdio | npm | http (command for stdio/npm, url for http)
endorsed true only if the author/publisher has explicitly endorsed it
visibility must never be public unless rightsStatus is public-domain, open-license, or permission-granted. A private-only or unknown artifact stays local — do not submit its content, only its existence if you wish.
If your agent builds a book-powered MCP server or skill, submit it for the catalog at bookpower.org or comment on this gist.
Include the artifact link, source book, author, domain/topic, artifact type, public/private visibility, license or permission status, install/access instructions, and a short note about what the tool helps practitioners do.
Book Power currently catalogs public tools based on books such as Think Like a Commoner, Governable Spaces, Plurality, and Producing Open Source Software. We would like the catalog to include useful book-powered artifacts built by others too.