# OpenDocs - MCP-Enabled Documentation Platform

> Canonical public documentation, clipping, ingestion, source attribution, auto-tagging, search, formatting, submission, metadata, and AI-readable knowledge layer for the PlatPhormNews web mesh.

## Overview

OpenDocs is the PlatPhorm Docs knowledge engine for humans and agents. It provides:
- **Full MCP Protocol Support** - Tools, resources, prompts for AI agents
- **Public-Safe Clipping** - Preview public web pages, platform posts, Reddit URLs, Google Drive/Docs public links, Dropbox links, images, Markdown, HTML, and pasted text
- **Source Attribution** - Preserve canonical source links, domains, public authors/dates where available, and attribution blocks
- **Explainable Scoring** - Source confidence, freshness, completeness, extraction quality, uniqueness, safety, and agent-readiness scores with evidence
- **Deterministic Auto-Tagging** - Suggest tags/categories from source platform, domain, title, headings, and keywords
- **Auto-Generated SEO** - OG tags, Twitter cards, JSON-LD structured data
- **Public Draft UX** - Redacted session data and browser-local drafts for non-sensitive public submissions
- **Emoji Support** - Unicode emojis and shortcodes throughout
- **Public Ingestion Preview** - Public URL/feed/file/GitHub/Drive/Dropbox/Reddit previews without login
- **Protected Publishing** - Persist canonical documents, private reports, private connector imports, and admin review actions only with PLATPHORM_API_KEY

## Live Inventory

- Published documents: 0
- Submissions: 0
- Unique sources: 0
- Categories: 0
- Tags: 0
- Storage mode: degraded
- MCP tools: 53
- MCP resources: 23
- MCP prompts: 16

## Quick Start

### MCP Connection
```json
{
  "mcpServers": {
    "opendocs": {
      "url": "https://docs.platphormnews.com/api/mcp"
    }
  }
}
```

### REST API
```bash
# List documents
curl https://docs.platphormnews.com/api/v1/documents

# Search
curl "https://docs.platphormnews.com/api/v1/search?q=getting+started"

# Submit content
curl -X POST https://docs.platphormnews.com/api/v1/submissions \
  -H "Content-Type: application/json" \
  -d '{"source_url":"https://example.com","title":"My Doc","content":"# Hello"}'

# Preview a public clip
curl -X POST https://docs.platphormnews.com/api/v1/clip/preview \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/public-guide"}'

# Protected document creation
curl -X POST https://docs.platphormnews.com/api/v1/documents \
  -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Protected Doc","content":"# Hello","status":"draft"}'
```

## MCP Tools (53 Registered)

- `get_docs_info` - Get OpenDocs service purpose, public/protected policy, route standard, and inventory counts.
- `list_documents` - List published docs with filtering, search, and pagination. Returns title, slug, emoji summary, reading time.
- `get_document` - Get a single document by slug, including full Markdown content and metadata.
- `create_document` - Create a new document. Returns the created document with slug and generated SEO metadata.
- `update_document` - Update an existing document by slug. Only provided fields are updated.
- `delete_document` - Soft-delete a document by slug.
- `search` - Full-text search across all documents using PostgreSQL tsvector.
- `search_documents` - Search published documents with public-safe full-text search and degraded empty state when persistence is unavailable.
- `list_categories` - List all document categories with document counts.
- `list_sources` - List public source attribution domains from published documents.
- `get_related_docs` - Get documents related to a specific document by slug based on category and tags.
- `submit_content` - Submit external content for review and potential publication.
- `preview_ingest_url` - Preview a public URL ingestion run with attribution, scores, duplicate state, and trace id. Does not persist content.
- `ingest_url_public_submission` - Create a public-safe submission from a URL ingestion preview. Does not publish a protected document.
- `validate_source` - Validate that a public source URL passes source policy and SSRF checks.
- `extract_metadata` - Extract public metadata and attribution from a public URL, pasted Markdown, HTML, or text.
- `score_content` - Run deterministic explainable scoring on provided public-safe content.
- `detect_duplicates` - Check canonical/source URL and content excerpt duplicate signals against published documents.
- `get_integration_status` - Return the public OpenDocs integration matrix and degraded/protected reasons.
- `get_demo_handoff_matrix` - Return the public demo handoff matrix for OpenDocs, Evals, MCP, the root network graph, Sandbox, AgentUI, and Spec.
- `get_agent_policy` - Return the public agent, crawler, robots, trust, and JA4 redaction policy.
- `get_health` - Return public-safe OpenDocs health, route, discovery, and persistence status.
- `get_info` - Alias for get_docs_info.
- `ingest_url` - Automatically fetch and ingest content from a URL.
- `clip_preview` - Build a public-safe clipping preview with cleaned Markdown, attribution, tag suggestions, metadata, and trace link. Does not persist content.
- `clip_commit` - Commit a clipped preview as a pending public submission. Protected document persistence is handled by REST with PLATPHORM_API_KEY.
- `clip_platform_post` - Preview a public PlatPhormNews platform post clip.
- `clip_reddit` - Preview a public Reddit post or comment URL without Reddit auth, returning degraded status if unavailable.
- `clip_google_drive` - Preview a public Google Drive or Google Docs link without bypassing permissions.
- `clip_dropbox` - Preview a public Dropbox shared link with bounded download conversion.
- `clip_image` - Preview a public image URL with MIME/size validation, manual alt text, attribution, and OCR degraded status.
- `clip_paste` - Clean pasted text, Markdown, or HTML into attributed Markdown without network fetches.
- `clean_ingested_content` - Clean HTML or text into normalized Markdown with clutter removal.
- `generate_source_attribution` - Generate a source attribution block from a public URL or pasted content.
- `suggest_tags` - Return deterministic tag and category suggestions for a URL or content preview.
- `get_emoji` - Get a descriptive emoji summary for a given text.
- `add_emoji_to_doc` - Generate and add an emoji summary to an existing document.
- `bulk_import` - Import multiple documents at once.
- `regenerate_seo` - Regenerate SEO metadata (og_title, og_description) for all documents.
- `generate_optimization` - Generate SEO optimization suggestions for a document.
- `export_docs` - Export documents matching criteria in a specific format.
- `get_stats` - Get overall documentation platform statistics.
- `trigger_webhook` - Trigger a test webhook event.
- `list_integrations` - List all configured external integrations.
- `call_integration` - Call a specific external integration endpoint.
- `parse_markdown` - Parse Markdown content and return HTML with table of contents
- `generate_share_links` - Generate social sharing links for a document
- `search_docs` - Alias for document search using full-text search across published docs.
- `list_tags` - List public tags used by published documentation.
- `list_project_docs` - List documentation specific to an external project (e.g., GitHub repo)
- `get_project_doc` - Get a specific documentation file from an external project
- `trigger_automation` - Trigger an automation workflow via Claws
- `get_automation_status` - Get status of an automation workflow via Claws

## MCP Resources

- `project-docs://{slug}` - Access documentation for specific projects
- `docs://index` - Index of all published documentation pages
- `docs://categories` - All documentation categories
- `docs://recent` - Recently published documentation
- `docs://popular` - Most viewed documentation
- `docs://tags` - All unique tags used in documentation
- `docs://sources` - Public source attribution inventory
- `docs://submissions` - Public-safe submission status summary
- `docs://ingestion-runs` - Public-safe ingestion run status contract and degraded storage state
- `docs://clips` - Public clipping capabilities and preview contract
- `docs://stats` - Overall statistics for the documentation platform
- `docs://sitemap` - XML sitemap representation of all docs
- `docs://llms` - AI-friendly representation of all documentation
- `docs://openapi` - OpenAPI contract for public and protected Docs APIs
- `docs://integrations` - OpenDocs integration matrix and protected/degraded connector status
- `docs://demo-handoffs` - Public demo handoff matrix for Evals, MCP, network graph, Sandbox, AgentUI, and Spec
- `docs://reports` - Report publishing target contract for PlatPhorm tools
- `docs://trust-policy` - Public/protected boundary and clipping trust policy
- `agent-policy://summary` - Agent and crawler access policy summary
- `agent-policy://platforms` - Supported agent platform policy records without invented crawler names
- `agent-policy://robots` - Robots policy allow/disallow summary
- `agent-policy://ai-policy` - AI access and attribution policy
- `agent-policy://trust-policy` - Full public/protected trust policy

## MCP Prompts

- `explain_doc` - Explain a documentation page in simple terms
- `summarize_category` - Summarize all documents in a category
- `compare_docs` - Compare two documentation pages
- `generate_faq` - Generate FAQ from document content
- `translate_doc` - Translate document to another language
- `improve_seo` - Suggest SEO improvements for a document
- `improve_attribution` - Review and improve source attribution without inventing missing source data
- `create_ingestion_plan` - Create an OpenDocs ingestion plan with source policy, scoring, dedupe, review, and protected publish steps
- `create_report_from_tool_output` - Turn public-safe tool output into an attributed Docs report plan
- `create_docs_publish_plan` - Plan protected publishing of reviewed Docs content
- `human_machine_docs_handoff` - Create a handoff between human reviewers and agent-readable documentation workflows
- `prepare_opendocs_demo_handoff` - Prepare a demo-ready OpenDocs handoff script across Evals, MCP, network graph, Sandbox, AgentUI, and Spec
- `clean_ingested_content` - Prompt for cleaning clipped content into attributed Markdown
- `clip_public_source` - Prompt for clipping and attributing a public source
- `create_source_attribution` - Prompt for source attribution review
- `suggest_document_tags` - Prompt for deterministic/manual tag review

## API Endpoints

### Documents
- `GET /api/v1/documents` - List (search, filter, paginate)
- `POST /api/v1/documents` - Create (PLATPHORM_API_KEY)
- `GET /api/v1/documents/{slug}` - Get document
- `PUT /api/v1/documents/{slug}` - Update (PLATPHORM_API_KEY)
- `DELETE /api/v1/documents/{slug}` - Delete (PLATPHORM_API_KEY)

### Submissions
- `POST /api/v1/submissions` - Submit public-safe content; auto-approves and returns a public document URL by default
- `GET /api/v1/submissions` - Public redacted status counts; full rows require PLATPHORM_API_KEY
- `GET /api/v1/submissions/latest` - Latest public-safe submissions
- `GET /api/v1/submissions/failures` - Protected redacted failure log for improving the ingest engine (PLATPHORM_API_KEY)
- `GET /api/v1/submissions/diagnostics` - Protected redacted submission improvement signals (PLATPHORM_API_KEY)
- `POST /api/v1/submissions/diagnostics` - Protected dry-run or retry-publish for stuck submissions (PLATPHORM_API_KEY)
- `POST /api/v1/submissions/{id}/approve` - Protected review action
- `POST /api/v1/submissions/{id}/reject` - Protected review action
- `POST /api/v1/submissions/{id}/publish` - Protected publish action
- `POST /api/v1/submissions/{id}/publish` - Protected publish route alias

### Ingestion
- `POST /api/v1/ingest/url` - Public-safe URL ingestion preview
- `POST /api/v1/ingest/batch` - Bounded public-safe batch previews
- `POST /api/v1/ingest/feed` - RSS/Atom preview
- `POST /api/v1/ingest/file` - Markdown/HTML/text preview
- `POST /api/v1/ingest/github` - Public GitHub URL preview
- `POST /api/v1/ingest/google-drive` - Public Drive/Docs preview
- `POST /api/v1/ingest/dropbox` - Public Dropbox preview
- `POST /api/v1/ingest/reddit` - Public Reddit preview
- `POST /api/v1/ingest/podcast` - Public feed preview or degraded transcript status
- `POST /api/v1/ingest/report` - Protected tool report import; degrades if no worker is configured
- `POST /api/v1/ingest` - Durable protected URL ingestion (PLATPHORM_API_KEY)

### Clipping
- `POST /api/v1/clip/preview` - Public-safe clipping preview
- `POST /api/v1/clip/paste` - Clean pasted text, Markdown, or HTML
- `POST /api/v1/clip/platform-post` - Preview public PlatPhormNews posts
- `POST /api/v1/clip/reddit` - Preview public Reddit URLs or degrade honestly
- `POST /api/v1/clip/google-drive` - Preview public Google Drive/Docs links or degrade honestly
- `POST /api/v1/clip/dropbox` - Preview public Dropbox shared links or degrade honestly
- `POST /api/v1/clip/image` - Preview public image URLs with OCR/alt-text degraded state
- `POST /api/v1/clip/commit` - Submit cleaned clip for review; `mode=document` requires PLATPHORM_API_KEY

### Search & Categories
- `GET /api/v1/search?q={query}` - Full-text search
- `GET /api/v1/categories` - List categories
- `GET /api/v1/tags` - List tags
- `GET /api/v1/sources` - List public source attribution inventory

### Attribution, Scoring, and Policy
- `POST /api/v1/attribution/extract` - Build source attribution from public input
- `POST /api/v1/scoring/score` - Deterministic explainable scoring for provided content
- `POST /api/v1/dedupe/check` - Duplicate signal check
- `POST /api/v1/classify` - Deterministic category suggestion
- `POST /api/v1/tags/suggest` - Deterministic tag suggestion
- `GET /api/v1/agent-policy` - Agent/AI access policy
- `GET /api/v1/integrations/status` - Integration matrix
- `GET /api/v1/integrations/handoffs` - Demo handoff matrix for Evals, MCP, PlatPhorm network graph, Sandbox, AgentUI, and Spec; `?check=live` runs bounded read-only checks

### Session & Fingerprinting
- `GET /api/session` - Get/create session
- `POST /api/session` - Save drafts, preferences

### OG Image Generation
- `GET /api/og?title=...&emoji=...` - Generate share image

## Auto-Generated Features

Every document automatically gets:
- OG title, description, image
- Twitter card meta tags
- JSON-LD structured data
- Canonical URL
- Reading time & word count
- Emoji summary
- Keywords extraction
- Social share links

## Authentication

Protected endpoints accept the shared platform key only:
```
Authorization: Bearer $PLATPHORM_API_KEY
```

Public read-only routes do not require authentication. Mutating, durable ingestion, review, sync, reporting, webhook, score regeneration, and admin actions require `PLATPHORM_API_KEY`.
Public preview scoring and source validation are read-only and do not persist documents. Protected regeneration, durable publishing, private connector access, and review decisions require `PLATPHORM_API_KEY`.

## Trace and JA4 Policy

Docs operations propagate W3C trace context and safe PlatPhorm trace headers. `x-vercel-ja4-digest` may be captured only for protected correlation after hashing/redaction. Raw JA4 digest values are never exposed in UI, RSS, sitemap, llms files, OpenAPI examples, logs, or public traces.

## Related Resources

- [Full LLM Context](https://docs.platphormnews.com/llms-full.txt) - Complete doc index
- [LLM Index JSON](https://docs.platphormnews.com/llms-index.json) - Machine-readable
- [API Docs](https://docs.platphormnews.com/docs/api) - Interactive reference
- [MCP Guide](https://docs.platphormnews.com/docs/mcp) - MCP integration

## External Integrations

- Emoji MCP: https://emoji.platphormnews.com/api/mcp
- OpenContent, Podcasts, Evals, BrowserOps, Sandbox, Spec, WebhookLab, Monitor, Trace, AgentUI, Claws, Phorm, Fingerprint, MCP Gateway, API Hub, Catalog, and platphormctl are represented in the public integration matrix.
- Demo handoffs: https://docs.platphormnews.com/api/v1/integrations/handoffs and MCP `get_demo_handoff_matrix`
- Connectors without credentials or durable workers are labeled degraded instead of counted as active imports.

---
OpenDocs v2.0.0 | MCP Protocol 2024-11-05