Moxie Docs

Official12 toolsLive

by Jackalope-Dev · TypeScript

Living docs and MCP context for GitHub repos — conventions, gaps, and source-cited pages on merge.

io.github.Jackalope-Dev/moxie-docs MCP Server

The Moxie Docs MCP server provides living docs and context for GitHub repositories, focusing on conventions, gaps, and source-cited pages related to merge decisions. It exposes a model context protocol to align agent behavior with repository documentation and MCP conventions.

🛠️ Key Features

Living docs and MCP context for GitHub repos
Conventions, gaps, and source-cited pages on merge
Tooling integration with MCP, agent skills, and CLI wiring
Repository-level model context to guide automated decisions
Lightweight, publish-ready readme excerpts and docs

🚀 Use Cases

Generate and maintain MCP context for code reviews and merges
Surface source-cited pages and conventions to agents
Enable consistent agent behavior across repositories
Quickly onboard new teams with MCP-driven docs

⚡ Developer Benefits

Clear MCP context model for repository learning
Reusable tools and CLI (moxie-docs) to wire MCP with repos
Easy integration into CI/CD for documentation-driven decisions
Open structure for extending conventions and gaps

⚠️ Limitations

Focuses on MCP context and docs; may not cover all repository toolchains
Dependent on repository-provided readme excerpts and source citations
Readme excerpt quality varies by repo; may require normalization

Topics

aiai-skillsai-toolsdocumentationmcp

Captured live from the server via tools/list.

moxie.get_conventions

Get the coding conventions Moxie inferred for the repository. Read-only; no side effects. Returns a Markdown list grouped by category (e.g. testing, structure, docs, review); each convention has a title, summary, confidence score, agent guidance, and the source file paths that evidence it. Use this for the general rules to follow; when you already know the files you're about to edit, prefer moxie.get_doc_impact for conventions scoped to those paths.

Parameters2

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
category	string	optional	Optional category filter, such as testing, structure, docs, or review.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "category": {
      "type": "string",
      "description": "Optional category filter, such as testing, structure, docs, or review."
    }
  }
}

moxie.search_docs

Keyword and semantic search across the connected repository's generated docs, conventions, documentation gaps, AI-context notes, and indexed code. Read-only; no side effects. Returns ranked matches in Markdown grouped into Documentation and Code sections, each with a title, snippet, and source paths. Use for open-ended lookups when you don't know which category holds the answer; when you do, the specific getters (get_conventions, get_doc_gaps, get_documentation_opportunities) are more direct. Omitting query returns recent context instead.

Parameters3

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
query	string	optional	Search phrase or topic. Omit to return recent context for the repository.
limit	number	optional	Maximum matches to return (1-20, default 8).

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "query": {
      "type": "string",
      "description": "Search phrase or topic. Omit to return recent context for the repository."
    },
    "limit": {
      "type": "number",
      "description": "Maximum matches to return (1-20, default 8)."
    }
  }
}

moxie.list_docs

List the repository's generated documentation as a browsable table of contents - every doc page, not a query-filtered subset. Read-only; no side effects. Returns Markdown grouped by section, each entry with its title, slug, repository path, and source paths, plus the total count and a pagination cursor so you can tell whether more pages remain (no silent truncation). Use this to see what docs already exist before adding one (so you don't duplicate) or to find the slug to pass to propose_doc_update; when you are hunting for a specific topic, search_docs is more direct.

Parameters4

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
section	string	optional	Optional section/collection filter (case-insensitive substring), e.g. "Backend" or "Billing". Omit to list every section.
limit	number	optional	Maximum docs to return (1-200, default 50).
offset	number	optional	Number of docs to skip for pagination (default 0). Use the cursor in the response to fetch the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "section": {
      "type": "string",
      "description": "Optional section/collection filter (case-insensitive substring), e.g. \"Backend\" or \"Billing\". Omit to list every section."
    },
    "limit": {
      "type": "number",
      "description": "Maximum docs to return (1-200, default 50)."
    },
    "offset": {
      "type": "number",
      "description": "Number of docs to skip for pagination (default 0). Use the cursor in the response to fetch the next page."
    }
  }
}

moxie.get_doc_gaps

List the unresolved documentation gaps Moxie found - areas of the codebase that lack docs. Read-only; no side effects. Returns a Markdown list, each gap with a title, severity, summary, and suggested file paths. This is gaps only; for the full prioritized work queue that also includes drift repairs and PR-template work, use get_documentation_opportunities, and to scope gaps to files you're about to edit use get_doc_impact.

Parameters2

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
severity	string	optional	Optional severity filter: high, medium, low, or info.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "severity": {
      "type": "string",
      "description": "Optional severity filter: high, medium, low, or info."
    }
  }
}

moxie.get_documentation_opportunities

List the actionable documentation updates Moxie recommends as a prioritized queue: missing docs, drift repairs, and PR-template work. Read-only; no side effects. Returns a Markdown list, each opportunity with a title, kind (documentation_gap | documentation_drift | pr_template), severity, summary, suggested action, estimated files changed, and source paths. Use this to pick the next doc task; it is the superset of get_doc_gaps (which lists gaps only).

Parameters3

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
kind	string	optional	Optional kind filter: documentation_gap, documentation_drift, or pr_template.
severity	string	optional	Optional severity filter: high, medium, low, or info.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "kind": {
      "type": "string",
      "description": "Optional kind filter: documentation_gap, documentation_drift, or pr_template."
    },
    "severity": {
      "type": "string",
      "description": "Optional severity filter: high, medium, low, or info."
    }
  }
}

moxie.get_documentation_patterns

Get Moxie's summary of how THIS repository organizes and maintains documentation - where docs live relative to code and how they are kept current. Read-only; no side effects. Returns a Markdown list of pattern entries, each with a title, explanation, and source citations. Use this to decide WHERE a new doc should go before calling propose_doc_update; for the list of WHICH docs need work, use get_documentation_opportunities instead.

Parameters1

repository

string

optional

The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    }
  }
}

moxie.get_ai_context

Get the compact briefing an agent should read before editing this repository: index status, verified commands, agent tips, top conventions, open documentation gaps, and queued documentation opportunities. Read-only; no side effects. Returns a single Markdown document. Call this first at the start of a task; once you know which files you'll change, follow up with get_doc_impact for path-scoped guidance.

Parameters1

repository

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    }
  }
}

moxie.get_doc_impact

Given the file paths an agent is about to change (and optionally a subset being deleted), return the conventions, documentation gaps, and existing/related docs whose evidence overlaps those paths, plus a net-new/undocumented analysis and any removal candidates. Read-only; no side effects. Returns a Markdown report. Call this BEFORE writing code so doc updates land in the same PR; then use propose_doc_update to write a doc, or propose_doc_removal for an orphaned one.

Parameters3

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
changedPaths	array	required	Repository-relative file paths the agent intends to modify (e.g., apps/web/src/app/api/billing/webhook/route.ts).
deletedPaths	array	optional	Subset of paths that are being DELETED. Moxie flags any doc whose every cited source path is in this list as a removal candidate for moxie.propose_doc_removal.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "changedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Repository-relative file paths the agent intends to modify (e.g., apps/web/src/app/api/billing/webhook/route.ts)."
    },
    "deletedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Subset of paths that are being DELETED. Moxie flags any doc whose every cited source path is in this list as a removal candidate for moxie.propose_doc_removal."
    }
  },
  "required": [
    "changedPaths"
  ]
}

moxie.get_api_context

Given file paths an agent is about to touch, return structured context for any API endpoints they map to: method, path, request/response schema, and known consumers/features. Read-only; no side effects. Call this before editing API route or schema code, alongside get_doc_impact.

Parameters2

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
paths	array	optional	Repository-relative file paths to inspect for API endpoint context.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Repository-relative file paths to inspect for API endpoint context."
    }
  }
}

moxie.review_change

Self-review a change you are about to commit BEFORE opening the PR. Pass the proposed new state of each changed file (and any deleted paths); Moxie returns a severity-ranked list of violations to fix: convention breaches, docs your change makes factually false, net-new API/surface added without docs, and doc references broken by deletions. Read-only; no side effects and no writes. Returns a Markdown verdict (clean | warnings | must-fix) with each finding's location, fix, and - for doc issues - the slug to pass to propose_doc_update. Call this as the final step of the edit flow, then fix findings and re-run.

Parameters3

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
changedFiles	array	required	The files your change adds or modifies, in their PROPOSED new state. Provide newContent (the full new file text) for each; you may also/instead provide patch (a unified diff). Max 20 files per call.
deletedPaths	array	optional	Repository-relative paths your change DELETES, so Moxie can flag docs whose references break.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "changedFiles": {
      "type": "array",
      "description": "The files your change adds or modifies, in their PROPOSED new state. Provide newContent (the full new file text) for each; you may also/instead provide patch (a unified diff). Max 20 files per call.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Repository-relative path, e.g. apps/web/src/app/api/foo/route.ts."
          },
          "newContent": {
            "type": "string",
            "description": "The full new contents of the file after your change."
          },
          "patch": {
            "type": "string",
            "description": "Optional unified diff for the file (used if newContent is omitted)."
          },
          "status": {
            "type": "string",
            "description": "Either \"added\" or \"modified\"."
          }
        },
        "required": [
          "path"
        ]
      }
    },
    "deletedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Repository-relative paths your change DELETES, so Moxie can flag docs whose references break."
    }
  },
  "required": [
    "changedFiles"
  ]
}

moxie.propose_doc_update

Propose a documentation file to add or update as part of YOUR current change. Records a new proposal each call (not idempotent) and does NOT modify your repository or open a PR - Moxie resolves the target path and returns the path + Markdown for YOU to write into your working branch, so the docs land in the SAME PR as the code. Returns the resolved target path and the content to write. Provide either targetPath or baseSlug.

Parameters7

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
title	string	required	Short human title for the documentation update.
markdown	string	required	The documentation content (Markdown) to write to the target file.
targetPath	string	optional	Repository-relative path to write the doc to (e.g., docs/billing.md). Omit to resolve from baseSlug.
baseSlug	string	optional	Slug of an existing generated doc to update instead of supplying targetPath.
sourcePaths	array	optional	Code paths this doc documents, for provenance.
reason	string	optional	Why this doc is being added or changed.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "title": {
      "type": "string",
      "description": "Short human title for the documentation update."
    },
    "markdown": {
      "type": "string",
      "description": "The documentation content (Markdown) to write to the target file."
    },
    "targetPath": {
      "type": "string",
      "description": "Repository-relative path to write the doc to (e.g., docs/billing.md). Omit to resolve from baseSlug."
    },
    "baseSlug": {
      "type": "string",
      "description": "Slug of an existing generated doc to update instead of supplying targetPath."
    },
    "sourcePaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Code paths this doc documents, for provenance."
    },
    "reason": {
      "type": "string",
      "description": "Why this doc is being added or changed."
    }
  },
  "required": [
    "title",
    "markdown"
  ]
}

moxie.propose_doc_removal

Propose deleting a Moxie-tracked documentation file that your change makes irrelevant, as part of YOUR current change. Moxie validates the path and returns it for you to delete in your working branch; Moxie itself does not delete files or open a PR - the deletion happens in your branch, so it lands in the SAME PR as the code. Returns the resolved path to delete. Provide either slug or targetPath.

Parameters5

repository	string	optional	The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer.
slug	string	optional	Slug of the existing generated doc to remove.
targetPath	string	optional	Repository-relative path of the doc to remove (must be a Moxie-tracked doc). Use instead of slug.
removedSourcePaths	array	optional	Code paths being deleted that made this doc irrelevant, for provenance.
reason	string	optional	Why this doc is no longer relevant.

Raw schema

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "The target repository as \"owner/name\" (e.g. \"acme/app\"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer."
    },
    "slug": {
      "type": "string",
      "description": "Slug of the existing generated doc to remove."
    },
    "targetPath": {
      "type": "string",
      "description": "Repository-relative path of the doc to remove (must be a Moxie-tracked doc). Use instead of slug."
    },
    "removedSourcePaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Code paths being deleted that made this doc irrelevant, for provenance."
    },
    "reason": {
      "type": "string",
      "description": "Why this doc is no longer relevant."
    }
  }
}

README.md18 KBView on GitHub

Visit Moxie Docs

Moxie Docs — MCP & Agent Tools

Smithery LobeHub Marketplace Moxie-Docs-MCP MCP server

The Moxie Docs Model Context Protocol (MCP) server, the agent skills Moxie installs into your repository, and the moxie-docs CLI that wires it all up — npx moxie-docs setup.

This repo is also the open-source home of the moxie-docs npm package: a setup CLI plus the MCP interface (tool catalog, prompts, server metadata, and skill renderers) you can import. The hosted server, indexing pipeline, and your generated docs stay in the private Moxie service.

Moxie Docs indexes a connected GitHub repository and keeps its documentation alive — generating docs, discovering conventions, tracking documentation gaps and drift, and opening pull requests that keep docs in sync with code. The MCP server exposes that living context to coding agents (Claude Code, Cursor, VS Code, Codex, and any MCP-capable client) so they ground their work in how your repository actually does things — and keep the docs current as they change code.

Website / dashboard: https://moxiedocs.com
Human docs for the MCP server: https://moxiedocs.com/mcp
MCP endpoint: https://moxiedocs.com/api/mcp

This repository is documentation and distribution assets only. The hosted server, indexing pipeline, and your repositories' documentation are not stored here.

Quick start
CLI
The MCP server
Claude plugin
Skills
- The moxie-docs skill
- What Moxie installs into your repository
Use as a library
Find the server
Discovery endpoints
License

Quick start

The fastest path — from your repository's directory:

bash

npx moxie-docs setup

This signs you in (OAuth in your browser), writes the MCP config for your editor, installs the moxie-docs skill + AGENTS.md guidance, and verifies the connection. After that, your agent reads live context with moxie.get_ai_context before editing and proposes doc updates that land in the same PR.

Prefer to do it by hand? Connect a repository at https://moxiedocs.com, then add the server to your agent with a config block.

CLI

The moxie-docs CLI (Node ≥ 18, zero runtime dependencies) sets up and manages the connection. Run it with npx moxie-docs <command> or install it globally (npm i -g moxie-docs).

Command	What it does
`moxie-docs setup`	End-to-end: sign in, configure your MCP client, install the skill + `AGENTS.md` block, and smoke-test.
`moxie-docs login`	Sign in via the browser (OAuth 2.1 + PKCE) and store credentials in `~/.moxie-docs/`.
`moxie-docs status`	Show your scope, connected repositories, and available tool count.
`moxie-docs config <client>`	Write the `moxie-docs` server entry into a client config (`claude-code`, `cursor`, or `vscode`).
`moxie-docs install-skill`	Install the `moxie-docs` skill and `AGENTS.md` guidance into the current repo.
`moxie-docs logout`	Remove stored credentials.

Useful flags: --client <name>, --token <dashboard-token>, --repo owner/name, --no-browser, --yes.

How authentication is written. By default setup/config write a URL-only server entry and let your editor perform its own OAuth sign-in on first use — so nothing in your committed config expires. The CLI's own browser sign-in (used for status and the setup smoke-test) stores a short-lived token plus a refresh token under ~/.moxie-docs/ (file mode 0600); it is never written into a client config. If you'd rather pin a static Authorization header, pass a long-lived dashboard token with --token and the CLI writes that instead. The CLI never logs token values, and it refuses to overwrite a client config it can't safely parse rather than discarding your other MCP servers.

The MCP server

Connection


Transport	Streamable HTTP MCP
Endpoint	`https://moxiedocs.com/api/mcp`
Protocol version	`2025-06-18`
Repository selection	Tools accept an optional `repository` argument (`owner/name`, e.g. `acme/app`). It is required only when a token serves multiple repositories and no single default applies. Matching is case-insensitive.

All write tools are proposals — Moxie returns the file path and content for you (the agent) to write into your own branch. Moxie never edits your repository directly through MCP, and never merges. Reads return compact, citation-backed context rather than raw code dumps.

Authentication

Bearer token (available today). Create a token in the dashboard and send it as a header:

code

Authorization: Bearer <MOXIE_TOKEN>

Moxie stores only the token hash (plus an encrypted copy so you can reveal it), a prefix, scope, and a last-used timestamp. You can reveal, rotate, or revoke tokens from the dashboard at any time.

OAuth 2.1 sign-in (for clients that support it). MCP clients that implement the OAuth authorization flow can connect by signing in through the browser instead of pasting a token — the client discovers the server's OAuth metadata, registers itself dynamically (RFC 7591), and obtains a token via the authorization-code + PKCE flow. Discovery documents:

Protected resource metadata: https://moxiedocs.com/.well-known/oauth-protected-resource
Authorization server metadata: https://moxiedocs.com/.well-known/oauth-authorization-server

Both authentication paths resolve to the same token model, so either works with the same tools. Connected applications can be reviewed and revoked from the dashboard.

Client configuration

Most agents accept a remote MCP server with a URL and headers. Replace <MOXIE_TOKEN> with a token from the dashboard.

Claude Code — .mcp.json (or claude mcp add):

json

{
  "mcpServers": {
    "moxie-docs": {
      "url": "https://moxiedocs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <MOXIE_TOKEN>"
      }
    }
  }
}

Cursor — .cursor/mcp.json:

json

{
  "mcpServers": {
    "moxie-docs": {
      "url": "https://moxiedocs.com/api/mcp",
      "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" }
    }
  }
}

VS Code — .vscode/mcp.json:

json

{
  "servers": {
    "moxie-docs": {
      "type": "http",
      "url": "https://moxiedocs.com/api/mcp",
      "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" }
    }
  }
}

Keep tokens out of source control. Reference an environment variable where your client supports it, or paste the token only into local, untracked config.

Tools

moxie.get_ai_context: Compact pre-edit briefing: repo status, verified commands, top conventions, open gaps, team notes. Read this first.
moxie.get_doc_impact: Given the paths you're about to change (and any you're deleting), returns the conventions, gaps, and existing docs whose evidence overlaps them.
moxie.get_api_context: Given paths you're about to touch, returns structured context for any API endpoints they map to: method, path, schema, and known consumers.
moxie.review_change: Self-review a change before opening the PR; returns a severity-ranked list of convention breaches, stale docs, undocumented surface, and broken references.
moxie.get_conventions: Discovered coding conventions, grouped by category, with confidence scores, agent guidance, and source-file citations.
moxie.search_docs: Semantic + keyword search over generated docs, conventions, gaps, and AI context.
moxie.get_doc_gaps: Unresolved documentation gaps with severity and the paths they concern.
moxie.get_documentation_opportunities: Recommended doc work: missing docs, drift repairs, and PR templates.
moxie.get_documentation_patterns: How the repository organizes and maintains its docs (where new docs belong).
moxie.list_docs: Paginated, section-grouped table of contents of every generated doc.
moxie.propose_doc_update: Add or update a doc as part of your current change; returns target path + Markdown to write into branch.
moxie.propose_doc_removal: Remove a Moxie-tracked doc your change makes obsolete; returns path to delete in branch.

Tool	Purpose
`moxie.get_ai_context`	Compact pre-edit briefing: repo status, verified commands, top conventions, open gaps, team notes. Read this first.
`moxie.get_doc_impact`	Given the paths you're about to change (and any you're deleting), returns the conventions, gaps, and existing docs whose evidence overlaps them - and flags net-new/undocumented surfaces.
`moxie.get_api_context`	Given paths you're about to touch, returns structured context for any API endpoints they map to: method, path, schema, and known consumers/features.
`moxie.review_change`	Self-review a change before opening the PR; returns a severity-ranked verdict (clean / warnings / must-fix) covering convention breaches, stale docs, undocumented surface, and broken references.
`moxie.get_conventions`	Discovered coding conventions, grouped by category, with confidence scores, agent guidance, and source-file citations.
`moxie.search_docs`	Semantic + keyword search over generated docs, conventions, gaps, and AI context.
`moxie.get_doc_gaps`	Unresolved documentation gaps with severity and the paths they concern.
`moxie.get_documentation_opportunities`	Recommended doc work: missing docs, drift repairs, and PR templates.
`moxie.get_documentation_patterns`	How the repository organizes and maintains its docs (where new docs belong).
`moxie.list_docs`	Paginated, section-grouped table of contents of every generated doc.
`moxie.propose_doc_update`	Add or update a doc as part of your current change; returns the target path + Markdown to write into your branch.
`moxie.propose_doc_removal`	Remove a Moxie-tracked doc your change makes obsolete; returns the path to delete in your branch.

Prompts

The server also exposes MCP prompts that script the common workflows:

Prompt	Purpose
`document-this-change`	Runs the doc-impact check on your changed paths and walks you through proposing the doc updates so they land in the same PR.
`fix-stale-docs`	Finds the repository's open documentation gaps and drift opportunities and repairs them through Moxie.
`review-before-finalize`	Runs Moxie's guardrail over your diff before you open the PR to catch convention breaches, stale docs, undocumented surface, and broken references.

Claude plugin

For Claude Code and Claude Cowork, this repository doubles as a plugin marketplace — a one-command way to add the Moxie Docs connector and skill together. The plugin bundles:

the moxie-docs MCP server (the remote endpoint above), wired up so your client runs its own OAuth sign-in on first use — no token to paste or commit; and
the moxie-docs skill, so the edit-then-document workflow is available the moment the plugin is installed.

Install it from inside Claude Code (or Cowork):

code

/plugin marketplace add Jackalope-Dev/Moxie-Docs-MCP
/plugin install moxie-docs@moxie-docs

The first command registers this repo as a marketplace; the second installs the moxie-docs plugin from it. On first use of a Moxie tool, your client opens the browser to sign in, then the tools and prompts above are available. Update later with /plugin marketplace update moxie-docs, and remove with /plugin uninstall moxie-docs@moxie-docs.

Prefer a static token, or a client without plugin support? Use the client configuration blocks or the CLI instead — the plugin, the CLI, and a hand-written config all resolve to the same server and the same auth model.

The plugin's manifest lives in .claude-plugin/ and its server entry in .mcp.json.

Skills

Agent Skills are small, triggered instruction files that teach an agent when and how to use a capability. Moxie publishes one skill, moxie-docs, that wires an agent into the edit-then-document workflow.

The `moxie-docs` skill

The canonical skill lives in this repo at skills/moxie-docs/SKILL.md and is also served from the website (with a published SHA-256 digest) at:

code

https://moxiedocs.com/.well-known/agent-skills/moxie-docs/SKILL.md

It tells an agent to read live context before editing (get_ai_context, get_doc_impact), follow the repository's real conventions and verified commands, and propose doc updates/removals that ship in the same PR as the code change — never inventing filler docs.

What Moxie installs into your repository

When Moxie connects a repository it opens one "Add Moxie agent guidance" PR that adds three self-healing, deterministic files (regenerated only when they drift or the repo is renamed — never churning on every index):

File	Purpose
`AGENTS.md`	A short, always-on pointer block (between `<!-- moxie-docs:start -->` / `<!-- moxie-docs:end -->` markers) telling any agent to use the MCP server and the `moxie-docs` skill. Human-added content outside the markers is preserved. See `templates/AGENTS.md`.
`.claude/skills/moxie-docs/SKILL.md`	The repo-specific `moxie-docs` skill for Claude Code.
`.agents/skills/moxie-docs/SKILL.md`	The same skill for `.agents`-aware clients.

The installed skill is the repo-specific variant of skills/moxie-docs/SKILL.md: identical workflow, with your owner/name baked in so multi-repo tokens target the right repository. Everything Moxie writes is deterministic and contains no volatile data — live conventions and commands always come from the MCP server, not the committed file.

Cursor Rules

Moxie Docs publishes native Cursor rule files (.mdc) for Cursor AI Agent mode. The canonical rule lives in this repository at rules/moxie-docs.mdc and can be added to your repository under .cursor/rules/moxie-docs.mdc or imported via cursor.directory.

Use as a library

The package also exports the open-source MCP interface — the backend-independent contract — so you can build tooling against Moxie without depending on the private server. It carries no secrets and no server logic.

import {
  moxieMcpTools,            // the tool catalog (names, descriptions, input schemas, annotations)
  moxieMcpPrompts,          // the document-this-change / fix-stale-docs prompt descriptors
  moxieMcpServerInfo,       // { name, version }
  moxieMcpProtocolVersion,  // "2025-06-18"
  moxieMcpCapabilities,
  buildMoxieMcpServerCard,  // full /.well-known/mcp/server-card.json document
  moxieMcpServerCard,       // canonical server card (tools + prompts included)
  moxieMcpPublicMethods,    // ["initialize", "tools/list", "prompts/list"]
  renderSkillMarkdown,      // ({ repository }) => the moxie-docs SKILL.md for a repo
  renderAgentsGuidanceBlock,// ({ repository }) => the AGENTS.md guidance block
  moxieDocsSkillMarkdown,   // the canonical published skill, as a string
  MOXIE_MCP_ENDPOINT,       // "https://moxiedocs.com/api/mcp"
  MOXIE_SITE_URL,
} from "moxie-docs";

What it does not include: the tool handlers, the indexing/doc-generation pipeline, AI/vector-search, the database layer, or token storage — those remain in the hosted Moxie service.

Find the server

Moxie Docs is listed for MCP clients and directories under these names:

Where	Identifier / link
Official MCP Registry	`io.github.Jackalope-Dev/moxie-docs` — search for `moxie-docs`
Smithery	smithery.ai/servers/jackalope-digital/moxie-docs (badge above)
Glama	glama.ai/mcp/servers/Jackalope-Dev/Moxie-Docs-MCP
LobeHub Marketplace	lobehub.com/mcp/jackalope-dev-moxie-docs-mcp
npm CLI	`moxie-docs` — `npx moxie-docs setup`

Machine-readable registry metadata for the hosted endpoint is in server.json in this repo.

Discovery endpoints

Moxie publishes a small machine-discoverable surface so agents and crawlers can find the server:

Endpoint	What it serves
`/.well-known/mcp/server-card.json`	MCP server card: `serverInfo`, protocol version, transport, capabilities, full `tools`/`prompts` catalogs, and `publicMethods` (unauthenticated listing).
`/.well-known/api-catalog`	RFC 9727 catalog linking to the server card and human docs.
`/.well-known/agent-skills/index.json`	Agent Skills discovery index (skills + SHA-256 digests).
`/.well-known/agent-skills/moxie-docs/SKILL.md`	The published `moxie-docs` skill.
`/.well-known/oauth-protected-resource`	OAuth protected-resource metadata (RFC 9728).
`/.well-known/oauth-authorization-server`	OAuth authorization-server metadata (RFC 8414).

License

MIT © Jackalope Dev. The contents of this repository (documentation, skill files, and templates) are open source. The hosted Moxie Docs service, indexing pipeline, and generated documentation are not part of this repository.

Install

Tools (12)

moxie.get_conventionsmoxie.search_docsmoxie.list_docsmoxie.get_doc_gapsmoxie.get_documentation_opportunitiesmoxie.get_documentation_patternsmoxie.get_ai_contextmoxie.get_doc_impact

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://moxiedocs.com/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "moxie-docs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://moxiedocs.com/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.Jackalope-Dev/moxie-docs MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

moxie.get_conventions

moxie.search_docs

moxie.list_docs

moxie.get_doc_gaps

moxie.get_documentation_opportunities

moxie.get_documentation_patterns

moxie.get_ai_context

moxie.get_doc_impact

moxie.get_api_context

moxie.review_change

moxie.propose_doc_update

moxie.propose_doc_removal

Moxie Docs — MCP & Agent Tools

Contents

Quick start

CLI

The MCP server

Connection

Authentication

Client configuration

Tools

Prompts

Claude plugin

Skills

The moxie-docs skill

What Moxie installs into your repository

Cursor Rules

Use as a library

Find the server

Discovery endpoints

License

Install

Remote endpoint

The `moxie-docs` skill