MCP Phase 1 — Completion Report

Branch feat/mcp-phase1 is ready to merge into develop. This document captures everything built, every decision made, known issues discovered, and what comes next.

What We Built

1. MCP Documentation Server

A thin MCP server wrapping llms-full.txt via mcpdoc. Spawns as a subprocess over stdio, exposing two tools to Claude Code:

list_doc_sources — returns the llms-full.txt URL
fetch_docs(url) — fetches and returns documentation content

Config (.mcp.json):

{
  "onesource-docs": {
    "type": "stdio",
    "command": "uvx",
    "args": ["--from", "mcpdoc", "mcpdoc",
             "--urls", "OneSourceDocs:https://docs.onesource.io/llms-full.txt",
             "--follow-redirects"]
  }
}

2. Claude Code Docs Skill Plugin

A complete skill plugin at onesource-ai-tools/onesource-claude/plugins/onesource-docs/ with 11 content files (~15K tokens total):

File	Purpose	~Tokens
`SKILL.md`	Entry point — quick reference, auth, common pitfalls	3,000
`docs/api-reference.md`	All 12 root queries with filters and ordering	3,000
`docs/schema-concepts.md`	Pagination, polymorphism, filters, enums	2,000
`docs/authentication.md`	Endpoints, API keys, 6 supported chains	1,000
`examples/basic-queries.md`	One complete example per root query	2,000
`examples/integration-patterns.md`	JS (fetch, Axios, Apollo), Python, curl	1,500
`examples/multi-step-workflows.md`	Wallet analysis, whale tracking, NFT collections	1,000
`troubleshooting/common-errors.md`	401, nulls, wrong query shapes, pagination	1,000
`troubleshooting/deprecated-queries.md`	Tombstones — NFT confusion (prominent), old filters, removed queries	800

3. LLM Discoverability Infrastructure

docusaurus-plugin-llms added to the Docusaurus build:

Generates llms.txt (index with links) and llms-full.txt (full content, ~330K chars)
Config: pathTransformation: { ignorePaths: ["docs"] } strips /docs/ prefix for correct URLs

LLM meta tags added to docusaurus.config.js:

<meta name="llms:website">, llms:description, llms:instructions
<script type="text/llms.txt"> inline instructions
<link rel="alternate"> pointing to /llms.txt and /llms-full.txt

4. Content Generation Pipeline

Scripts in scripts/generate-skill/ that auto-generate skill content from the GraphQL schema:

schema-parser.ts — parses GraphQL introspection
content-generator.ts — generates api-reference.md, schema-concepts.md, basic-queries.md
Handlebars templates for remaining files

Run with npm run generate-skill to regenerate from latest schema.

5. 55-Question Test Suite & Scoring Infrastructure

Full test harness in scripts/ai-readability-test/:

55 questions across 6 categories (Core API, Query Generation, Type Usage, Integration, Chain-Specific, Troubleshooting)
4 test modes: run (readability), discovery, mcp-sim, mcp-live
4 model targets: DeepSeek, Gemini Flash, GPT-4o, Claude
Automated scoring, checkpoint comparison, and report generation

6. Marketplace Registration

Plugin registered in onesource-ai-tools/onesource-claude/.claude-plugin/marketplace.json. Installable via /plugin install onesource-docs@onesource-marketplace.

Key Decisions

Decision 1: Separate Plugins, One Marketplace

Choice: onesource-docs (docs team) and onesource-api (backend team, future) as independent plugins.

Why: Different teams, different release cadences. Each MCP tool costs 400-500 tokens in context — users who only need docs shouldn't pay the token overhead for API execution tools. Research showed tool-count problems degrade LLM accuracy above 50 tools.

Alternative rejected: Monolithic MCP server combining all tools. Too tightly coupled.

Decision 2: Skill + MCP Hybrid

Choice: Skill provides structured knowledge in-context (~15K tokens). MCP server supplements with live fetching on demand.

Why: Test data shows 96% accuracy with docs-in-context vs lower rates when Claude must discover docs on its own. GPT-4o only has 20% discovery rate for llms.txt — the skill eliminates this bottleneck entirely.

Decision 3: NFT Tombstone as Top Priority

Choice: NFT lookup confusion gets first-position callout in both SKILL.md and deprecated-queries.md.

Why: Universal failure — every model in every test generates nft() or getNFT() instead of the correct query shape. Training data bias is strong enough to need redundant, prominent correction.

Decision 4: ~15K Token Budget

Choice: Half the Mach10 skill's footprint (~30K tokens).

Why: Both skills coexist in context. Combined ~45K is already substantial. Keeping docs skill lean leaves room for conversation context.

Decision 5: mcpdoc as MCP Server

Choice: Use the open-source mcpdoc package rather than building a custom MCP server.

Why: Thin connector pattern — all knowledge lives in the skill, the MCP server just serves raw docs on demand. No custom logic needed.

Test Results

Readability Tests (Completed)

Checkpoint	Accuracy	Notes
Baseline (raw llms-full.txt)	89%	Models interpret docs with no guidance
Post-Content (improved docs)	93%	Better doc structure and examples
Post-Plugin-Docs (with skill)	96%	Target achieved

Discovery Tests (Completed)

Model	Accuracy	Discovery Rate	Avg Tokens
DeepSeek	99-100%	100%	72K
Gemini Flash	97-100%	91%	—
GPT-4o	92-97%	20%	16K
Claude Opus 4.5	83%	88%	Partial (16/55)

MCP Tests (Not Yet Run)

Code is complete for both mcp-sim and mcp-live. Blocked on: needing a deployed build with correct URLs (see Known Issues below).

Known Issues Discovered

Issue 1: llms.txt URLs 404 on Deployed Site (Critical for MCP testing)

Problem: The deployed llms.txt and llms-full.txt contain URLs with /docs/ prefix (e.g., https://docs.onesource.io/docs/onesource-web3-api-reference/queries/nft). These all return 404. The correct URLs have no /docs/ prefix (e.g., https://docs.onesource.io/onesource-web3-api-reference/queries/nft).

Root cause: The docusaurus-plugin-llms runs in postBuild() and writes to build/, overwriting any static/llms.txt. The deployed build was made before the pathTransformation: { ignorePaths: ["docs"] } config was added.

Fix: Merge this branch and rebuild/deploy the site. The plugin will regenerate both files with correct URLs. The manually-maintained static/llms.txt and static/llms-full.txt can be deleted since the plugin always overwrites them.

Impact: MCP fetch_docs calls that follow links from llms.txt will fail until this is deployed. The MCP server itself works (it serves llms-full.txt directly), but Claude following links within that content will hit 404s.

Issue 2: llms-full.txt Too Large for LLM Context

Problem: llms-full.txt is 330K characters — exceeds maximum allowed tokens when fetched via MCP. Claude Code saves it to a temp file and must read it in chunks.

Impact: Not a blocker — this is the expected behavior for full-content files. Claude can search/grep the saved file. The llms.txt index file works fine and is the intended entry point for navigation.

Issue 3: Query 2.1 Universal Failure (NFT Lookup)

Problem: All models generate nft() or getNFT() instead of the correct query. Training data bias.

Mitigation implemented: Prominent tombstone in deprecated-queries.md (first entry) and SKILL.md Common Pitfalls. Needs validation that this actually fixes it — part of next-step testing.

Issue 4: GPT-4o Discovery Weakness

Problem: Only 20% discovery rate for llms.txt. Model doesn't proactively look for standardized AI documentation files.

Mitigation implemented: The skill eliminates discovery entirely (docs are in-context). MCP server also eliminates it (tools are pre-configured). Only affects bare-URL scenarios.

Issue 5: static/llms.txt Redundancy

Problem: Both static/llms.txt and the docusaurus-plugin-llms produce llms.txt. The plugin's postBuild() output always overwrites the static copy. Keeping both creates confusion about which version is live.

Recommendation: Delete static/llms.txt and static/llms-full.txt after merge. Let the plugin be the single source of truth.

Files Changed

New Files (26+)

# MCP Server Config
.mcp.json

# Plan
docs/plans/2026-03-11-feat-onesource-docs-skill-plan.md

# Guides
docs/guides/ai-editor-setup.md

# Plugin (11 content files)
onesource-ai-tools/onesource-claude/plugins/onesource-docs/
  .claude-plugin/plugin.json
  .mcp.json
  README.md
  skills/onesource-docs/SKILL.md
  skills/onesource-docs/docs/api-reference.md
  skills/onesource-docs/docs/schema-concepts.md
  skills/onesource-docs/docs/authentication.md
  skills/onesource-docs/examples/basic-queries.md
  skills/onesource-docs/examples/integration-patterns.md
  skills/onesource-docs/examples/multi-step-workflows.md
  skills/onesource-docs/troubleshooting/common-errors.md
  skills/onesource-docs/troubleshooting/deprecated-queries.md

# Test Infrastructure
scripts/ai-readability-test/LLM-DISCOVERABILITY-REPORT.md
scripts/ai-readability-test/src/index.ts
scripts/ai-readability-test/src/mcp-live.ts
scripts/ai-readability-test/src/mcp-sim.ts

# Content Generation
scripts/generate-skill/index.ts
scripts/generate-skill/schema-parser.ts
scripts/generate-skill/content-generator.ts
scripts/generate-skill/templates/*.hbs

Modified Files

docusaurus.config.js    — LLM meta tags + docusaurus-plugin-llms config
.gitignore              — Added /onesource-ai-tools/ exclusion
static/llms.txt         — URL fixes (will be overwritten by plugin at build)
static/llms-full.txt    — URL fixes (will be overwritten by plugin at build)

Next Steps

Immediate (Merge & Deploy)

Merge feat/mcp-phase1 into develop — all code is complete
Rebuild and deploy the docs site — this fixes the 404 issue (URLs in generated llms.txt will drop the /docs/ prefix)
Verify post-deploy: fetch https://docs.onesource.io/llms.txt and confirm URLs resolve (no /docs/ prefix, no 404s)

Testing (Post-Deploy)

Run MCP-sim tests — validates simulated MCP tool flow works end-to-end

cd scripts/ai-readability-test
npx tsx src/index.ts mcp-sim -m deepseek-coder --quick

Run MCP-live tests — validates real MCP server over stdio
```
npx tsx src/index.ts mcp-live -m deepseek-coder --quick
```
Validate Query 2.1 fix — confirm NFT tombstone actually corrects model behavior with skill in context
Complete Claude Opus 4.5 test run — currently only partial (16/55 questions)
Fill in mcp-phase1-validation.md TBD fields with real test data

Cleanup (Post-Testing)

Delete static/llms.txt and static/llms-full.txt — redundant since the plugin generates them at build time
Review .gitignore for /onesource-ai-tools/ — plugin files should probably be committed for version control

Phase 2 (Future Development)

Build onesource-api plugin (backend team) — live GraphQL execution via MCP tools
Add semantic search tool (search_docs) to the MCP server for targeted lookups instead of full-file fetching
Add query-specific tools (get_query_reference, get_type_definition) for precise schema lookups
Publish to distribution channels:
- Official MCP Registry (server.json)
- npm as @onesource/docs-skill
- Community directories (Smithery, Glama)
Content sync automation — auto-regenerate skill content when llms-full.txt changes (CI pipeline)

Metrics Summary

Metric	Target	Actual	Status
Skill token budget	15K or less	~15K	Met
SKILL.md entry point	3K tokens or less	~3K	Met
Test accuracy (with skill)	96%+	96%	Met
Root queries documented	12	12	Met
Integration languages	4+	5 (JS fetch, Axios, Apollo, Python, curl)	Met
MCP-live tests	Pass	Not yet run	Pending deploy
Query 2.1 NFT fix	Pass	Tombstone written, not yet validated	Pending test

What We Built​

1. MCP Documentation Server​

2. Claude Code Docs Skill Plugin​

3. LLM Discoverability Infrastructure​

4. Content Generation Pipeline​

5. 55-Question Test Suite & Scoring Infrastructure​

6. Marketplace Registration​

Key Decisions​

Decision 1: Separate Plugins, One Marketplace​

Decision 2: Skill + MCP Hybrid​

Decision 3: NFT Tombstone as Top Priority​

Decision 4: ~15K Token Budget​

Decision 5: mcpdoc as MCP Server​

Test Results​

Readability Tests (Completed)​

Discovery Tests (Completed)​

MCP Tests (Not Yet Run)​

Known Issues Discovered​

Issue 1: llms.txt URLs 404 on Deployed Site (Critical for MCP testing)​

Issue 2: llms-full.txt Too Large for LLM Context​

Issue 3: Query 2.1 Universal Failure (NFT Lookup)​

Issue 4: GPT-4o Discovery Weakness​

Issue 5: static/llms.txt Redundancy​

Files Changed​

New Files (26+)​

Modified Files​

Next Steps​

Immediate (Merge & Deploy)​

Testing (Post-Deploy)​

Cleanup (Post-Testing)​

Phase 2 (Future Development)​

Metrics Summary​