techwriter-mcp is an MCP-based document writing server that creates, edits, and reviews software documents using factual input from a coding agent.
Create documents: Generate various types (plans, RFCs, design docs, architecture docs, READMEs, guides, explanations, ADRs) by supplying structured facts such as context, decisions, tradeoffs, and code evidence; the server handles prose and structure.
Edit documents: Submit factual corrections (not replacement prose) to make the smallest coherent change while preserving the original voice and untouched sections.
Review documents: Receive editorial findings on structure, clarity, missing motivation/tradeoffs, or prose issues, returned with locations and without rewriting; a clean bill of health is possible.
Support PRs and issues: The first line of content is treated as the title, suitable for tools like gh.
Customizable voice: Configure the writing style via a .techwriter-mcp/ project directory with model choice, house style instructions, example documents, and counterexamples.
Fact-check workflow: Designed for agents to investigate a repository, pass verified facts to create, then fact-check and send corrections via edit, ensuring accuracy.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@docs-mcp Write a design doc for the authentication module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Moved. Development continues in paraspace-dev/writer-mcps, a marketplace of writer MCP servers. Install from there:
/plugin marketplace add paraspace-dev/writer-mcps
/plugin install techwriter@writer-mcpsThe npm package techwriter-mcp is unchanged and published from the new repo.
Write repository documents from verified codebase facts. Your coding agent investigates the repository, this server sends those facts to a separate model that writes the document, and the agent fact-checks the result before sending corrections back.
/plugin marketplace add paraspace-dev/techwriter-mcp
/plugin install techwriter-mcp@techwriter-mcpClaude Code prompts once for an OpenAI API key and stores it in the OS keychain.
The plugin registers the techwriter MCP server, a skill that keeps the agent in the
facts-in role, and a command to set up project writing configuration:
/techwriter-mcp:techwriter-initRelated MCP server: QwikVault MCP
The agent calls create for a new document, then checks the result against the
repository. If it finds an error, it calls edit with the corrected facts
rather than rewriting the prose itself.
Use review when you want editorial findings instead of a rewrite. It returns
findings with locations, or reports that the document has no significant
editorial problems.
The fact-check matters. Wrong facts produce a well-written wrong document.
techwriter-mcp writes plans, RFCs, design and architecture docs, READMEs,
guides, explanations, ADRs, pull request descriptions, and issues. For PRs and
issues, the first line of the document is the title as a # heading; the
agent strips it and passes it to gh separately.
The server is the npm package techwriter-mcp. Run it as npx -y techwriter-mcp@latest
with OPENAI_API_KEY in its environment.
For Claude Code without the plugin, add the server to .mcp.json:
{
"mcpServers": {
"techwriter": {
"command": "npx",
"args": ["-y", "techwriter-mcp@latest"]
}
}
}For Codex, add the server to ~/.codex/config.toml:
[mcp_servers.techwriter]
command = "npx"
args = ["-y", "techwriter-mcp@latest"]Configuration is optional. Without .techwriter-mcp/, the server uses its editorial
brief and a default model.
Add examples and writing rules when you want the document to sound like your project:
.techwriter-mcp/
config.toml model choice, voice corpus globs
instructions.md your house style, in your words
voice/
examples/ documents that sound the way you want
avoid/ counterexamples of the style you keep deleting[model]
model = "gpt-5.6-terra"
[voice]
include = ["docs/**/*.md", "README.md"]
exclude = ["docs/generated/**"]Files in voice/ and files matched by include become the voice corpus. A few
strong examples usually teach the model more than a long instructions file.
If your existing documentation is AI-written, adding it to include teaches the
model that same voice. Pre-AI READMEs and posts make better examples. AI
originals recovered from git history can go in voice/avoid/.
The corpus is capped at max_kb, which defaults to 256 KB. The server reports
files it drops for the budget. The corpus is sent with every request and uses
the provider's prompt cache, so it is nearly free after the first call of a
session. Set TECHWRITER_MCP_DEBUG=1 to print input, cached, and output token counts
to stderr.
Write a software document (plan, RFC, design doc, README, guide, ADR) from facts you supply. Investigate the repository first, then pass what you learned as structured material. Do not draft prose yourself and do not paste a draft as material; a separate writing model decides structure and wording. When it returns, fact-check the document against the repository and send corrections through the edit tool as facts.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Kind of document to write | |
| notes | No | Any other factual material that fits no field above | |
| context | No | Background facts from your investigation, as prose or notes | |
| purpose | Yes | What this document must accomplish for its reader | |
| audience | No | Who reads this and what they already know | |
| decisions | No | Decisions already made, with their reasons if known | |
| tradeoffs | No | Known costs of the chosen approach | |
| constraints | No | Hard constraints the document must respect | |
| code_evidence | No | File paths, signatures, or snippets the document may cite | |
| open_questions | No | What remains genuinely unresolved | |
| current_behavior | No | How the system behaves today | |
| proposed_behavior | No | How it should behave after the change |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that a separate writing model handles structure/wording and that a fact-check loop with the edit tool follows. However, it does not clarify whether the tool writes to a file or returns content, nor does it mention side effects or permissions, leaving ambiguity in the output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of four purposeful sentences, each conveying essential workflow instructions. It is slightly verbose but every sentence earns its place, covering purpose, prerequisite, constraint, and follow-up step without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters and no output schema, the description explains the high-level workflow and constraints well. However, it fails to describe the exact return value or delivery mechanism of the document, which is a significant gap for a 'create' tool. The missing output detail leaves the agent uncertain about what to do with the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a baseline of 3 applies. The description adds meaningful semantics by instructing the agent to supply 'facts' and 'structured material' and explicitly prohibiting pasting a draft, which directly clarifies how parameters like context and notes should be populated. This goes beyond the terse schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool writes a software document (plan, RFC, design doc, README, guide, ADR) from supplied facts, giving a specific verb and resource. It also distinguishes from the sibling edit tool by specifying that corrections are sent through edit, making its unique role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: investigate the repository first and pass structured material, while also giving when-not-to-use instructions: do not draft prose yourself or paste a draft. It also points to the edit tool as the alternative for corrections, naming the sibling explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revise an existing document with the smallest coherent change. State what is factually wrong or what must change, as facts rather than replacement prose. The document's voice and untouched text are preserved.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Kind of document, if known | |
| changes | Yes | What must change, stated as facts (what is wrong, what is now true), not as replacement prose | |
| document | Yes | The current document text, verbatim |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that edits will be the smallest coherent change, the document's voice is preserved, and untouched text is kept intact. This goes beyond the schema by describing the tool's conservative editing philosophy and the expected form of user input.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: the first states the core action and constraint, the second instructs on the form of changes, and the third clarifies preservation behavior. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no output schema, the description covers inputs and behavioral constraints well. The only gap is that it does not explicitly state the return format (e.g., the revised full document), but the action 'revise' implies the output is the updated document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics to the 'changes' parameter by requiring facts rather than replacement prose, and to 'document' by implying it must be verbatim current text. This helps the agent phrase inputs correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Revise an existing document' with the qualifier 'smallest coherent change.' This clearly distinguishes it from the sibling tools 'create' and 'review' by targeting modification of existing content rather than generation or assessment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: editing existing documents and requesting changes as facts rather than prose. It does not explicitly name alternatives or state when not to use the tool, but the 'existing document' phrasing and focus on minimal change imply when this tool is appropriate versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get editorial findings on a document: where it inventories instead of explains, structure that is not helping, missing motivation or tradeoffs, prose that reads like serialized code. Returns findings with locations, never a rewrite; "no significant editorial problems" is a possible outcome.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Kind of document, if known | |
| concerns | No | Specific things you want the review to weigh | |
| document | Yes | The document text to review, verbatim |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the non-mutating behavior ('never a rewrite'), the output form ('findings with locations'), and a possible null result ('no significant editorial problems'). It doesn't cover potential input limits but is transparent about core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences. The first sentence front-loads the purpose and details what findings address; the second covers output format, constraints, and outcome expectations. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description partially explains the return value ('findings with locations' and the 'no significant editorial problems' possibility). It lacks a detailed findings structure, but for a review tool this is adequate to guide an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter already has a clear description in the schema. The tool description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Get editorial findings on a document') and enumerates concrete finding categories (inventories, structure, missing motivation, serialized prose). It also clearly distinguishes itself from the 'edit' sibling by stating 'never a rewrite'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly sets the context: use this tool for editorial feedback on a document. It provides a when-not ('never a rewrite') and a possible outcome, but it does not explicitly name when to prefer this over 'create' or 'edit'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0createeditreviewEach tool has a distinct role: create produces a new document, edit modifies an existing one, and review provides editorial feedback. There is no overlap in purpose or action.
All tool names are single, lowercase verbs (create, edit, review), following a simple and predictable pattern. The naming style is uniform across the set.
Three tools form a tight, focused set for document lifecycle management. The scope is small but complete, and each tool serves a necessary function.
The set covers the core document workflow: creation, revision, and critique. There are no obvious dead ends, and the tools complement each other to support a complete editing cycle.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Research-backed linting + generation for agent context files (CLAUDE.md, AGENTS.md, Cursor rules).
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Production-readiness for your AI coding agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/paraspace-dev/techwriter-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
