Markdown, HTML, and MCP
Markdown is the editable content source. It is plain text, works in Git, and can be read by agents with access to this repository. It does not automatically make an agent discover or follow the manual: link it from the consuming project's instructions or explicitly include it in a task.
HTML is the human-facing view. The build reads BRAND-MANUAL.md, this file, and tokens.css to generate the pages in site/. Edit the sources and rebuild; do not independently edit generated HTML.
MCP is an optional access layer. An MCP server could serve the same Markdown and tokens to compatible clients across projects. It would not replace either the files or the visual preview. Resources expose information; tools provide callable operations such as searching guidance. See the official MCP server concepts.
Use the files now
Give an agent access to this repository, then point it to:
BRAND-MANUAL.mdfor brand decisions, component patterns, and source references.tokens.cssfor exact reusable color and font definitions.assets/for the existing logo variants and reference imagery.
In a consuming project's AGENTS.md, use an instruction such as:
Before changing branding or UI, read the Digital Agency brand manual
in the agreed agency-brand-manual checkout. Follow BRAND-MANUAL.md
and tokens.css, and record any intentional product-specific exception.
Resolve that checkout path for the project's environment. For reproducible releases, record the manual's Git commit or use a pinned checkout; pulling a newer revision should be a deliberate update.
Proposed MCP interface
The following is a design for a future server, not a currently installed integration.
| Capability | Proposed interface | Source |
|---|---|---|
| Whole manual | Resource brand://manual | BRAND-MANUAL.md |
| Topic guidance | Resource template brand://sections/{slug} | Sections from the same Markdown |
| CSS tokens | Resource brand://tokens | tokens.css |
| Read a topic | Tool get_brand_guidelines({ section }) | Exact section content and version |
| Find guidance | Tool search_brand_manual({ query }) | Matching headings and passages |
| Token values | Tool get_brand_tokens() | Parsed token names and values |
| Asset index | Tool list_brand_assets() | Known assets, roles, and paths |
Return the source filename, section, manual version, and repository revision with results so an agent can identify the guidance it used. Begin with read-only access and a fixed set of documents and assets. A database, embedding service, or model API is unnecessary for this small manual; straightforward topic lookup and text search are enough.
What building it requires
- A small TypeScript server using an official MCP SDK, with input schemas for the tools above. Use a supported runtime for the chosen SDK and verify its compatibility. Follow the official server quickstart.
- A content loader that reads the existing Markdown, token definitions, and known asset index. Reuse the section parser in
scripts/content.tsrather than creating a separate copy of the manual. - A transport: stdio for a local process launched by a client, or Streamable HTTP for a hosted service. See the MCP transport documentation.
- Client configuration that registers the server. Codex supports local stdio and Streamable HTTP servers; its official MCP guide documents command and URL configuration.
- Verification with a real MCP client: initialization, resource discovery, topic reads, search, token output, unknown inputs, and content revision changes.
A local stdio version needs the repository checkout, the server runtime, SDK dependencies, and a configured client. It does not require hosting. A remote version additionally needs a reachable HTTPS service, a deployment process that updates its content revision, and authentication if the manual should be private.
For stdio, write diagnostic logs to stderr; stdout is reserved for protocol messages. Validate section names against the known section list and resolve only known assets, rather than accepting arbitrary filesystem paths.
Suggested sequence
Keep Markdown as the source and use the generated HTML to review the design now. Add a local read-only MCP server when several projects or agent clients need reliable discovery and retrieval. Move that server to HTTPS if team members need shared remote access. Content remains in this repository throughout.
The preview builder and HTTP preview server in this repository are not MCP servers. No MCP SDK, endpoint, or client registration is included in this version.