This is page 3 of 29. Use http://codebase.md/tosin2013/documcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .dockerignore
├── .eslintignore
├── .eslintrc.json
├── .github
│ ├── agents
│ │ ├── documcp-ast.md
│ │ ├── documcp-deploy.md
│ │ ├── documcp-memory.md
│ │ ├── documcp-test.md
│ │ └── documcp-tool.md
│ ├── copilot-instructions.md
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── automated-changelog.md
│ │ ├── bug_report.md
│ │ ├── bug_report.yml
│ │ ├── documentation_issue.md
│ │ ├── feature_request.md
│ │ ├── feature_request.yml
│ │ ├── npm-publishing-fix.md
│ │ └── release_improvements.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── auto-merge.yml
│ ├── ci.yml
│ ├── codeql.yml
│ ├── dependency-review.yml
│ ├── deploy-docs.yml
│ ├── README.md
│ ├── release-drafter.yml
│ └── release.yml
├── .gitignore
├── .husky
│ ├── commit-msg
│ └── pre-commit
├── .linkcheck.config.json
├── .markdown-link-check.json
├── .nvmrc
├── .pre-commit-config.yaml
├── .versionrc.json
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── commitlint.config.js
├── CONTRIBUTING.md
├── docker-compose.docs.yml
├── Dockerfile.docs
├── docs
│ ├── .docusaurus
│ │ ├── docusaurus-plugin-content-docs
│ │ │ └── default
│ │ │ └── __mdx-loader-dependency.json
│ │ └── docusaurus-plugin-content-pages
│ │ └── default
│ │ └── __plugin.json
│ ├── adrs
│ │ ├── 001-mcp-server-architecture.md
│ │ ├── 002-repository-analysis-engine.md
│ │ ├── 003-static-site-generator-recommendation-engine.md
│ │ ├── 004-diataxis-framework-integration.md
│ │ ├── 005-github-pages-deployment-automation.md
│ │ ├── 006-mcp-tools-api-design.md
│ │ ├── 007-mcp-prompts-and-resources-integration.md
│ │ ├── 008-intelligent-content-population-engine.md
│ │ ├── 009-content-accuracy-validation-framework.md
│ │ ├── 010-mcp-resource-pattern-redesign.md
│ │ └── README.md
│ ├── api
│ │ ├── .nojekyll
│ │ ├── assets
│ │ │ ├── hierarchy.js
│ │ │ ├── highlight.css
│ │ │ ├── icons.js
│ │ │ ├── icons.svg
│ │ │ ├── main.js
│ │ │ ├── navigation.js
│ │ │ ├── search.js
│ │ │ └── style.css
│ │ ├── hierarchy.html
│ │ ├── index.html
│ │ ├── modules.html
│ │ └── variables
│ │ └── TOOLS.html
│ ├── assets
│ │ └── logo.svg
│ ├── development
│ │ └── MCP_INSPECTOR_TESTING.md
│ ├── docusaurus.config.js
│ ├── explanation
│ │ ├── architecture.md
│ │ └── index.md
│ ├── guides
│ │ ├── link-validation.md
│ │ ├── playwright-integration.md
│ │ └── playwright-testing-workflow.md
│ ├── how-to
│ │ ├── analytics-setup.md
│ │ ├── custom-domains.md
│ │ ├── documentation-freshness-tracking.md
│ │ ├── github-pages-deployment.md
│ │ ├── index.md
│ │ ├── local-testing.md
│ │ ├── performance-optimization.md
│ │ ├── prompting-guide.md
│ │ ├── repository-analysis.md
│ │ ├── seo-optimization.md
│ │ ├── site-monitoring.md
│ │ ├── troubleshooting.md
│ │ └── usage-examples.md
│ ├── index.md
│ ├── knowledge-graph.md
│ ├── package-lock.json
│ ├── package.json
│ ├── phase-2-intelligence.md
│ ├── reference
│ │ ├── api-overview.md
│ │ ├── cli.md
│ │ ├── configuration.md
│ │ ├── deploy-pages.md
│ │ ├── index.md
│ │ ├── mcp-tools.md
│ │ └── prompt-templates.md
│ ├── research
│ │ ├── cross-domain-integration
│ │ │ └── README.md
│ │ ├── domain-1-mcp-architecture
│ │ │ ├── index.md
│ │ │ └── mcp-performance-research.md
│ │ ├── domain-2-repository-analysis
│ │ │ └── README.md
│ │ ├── domain-3-ssg-recommendation
│ │ │ ├── index.md
│ │ │ └── ssg-performance-analysis.md
│ │ ├── domain-4-diataxis-integration
│ │ │ └── README.md
│ │ ├── domain-5-github-deployment
│ │ │ ├── github-pages-security-analysis.md
│ │ │ └── index.md
│ │ ├── domain-6-api-design
│ │ │ └── README.md
│ │ ├── README.md
│ │ ├── research-integration-summary-2025-01-14.md
│ │ ├── research-progress-template.md
│ │ └── research-questions-2025-01-14.md
│ ├── robots.txt
│ ├── sidebars.js
│ ├── sitemap.xml
│ ├── src
│ │ └── css
│ │ └── custom.css
│ └── tutorials
│ ├── development-setup.md
│ ├── environment-setup.md
│ ├── first-deployment.md
│ ├── getting-started.md
│ ├── index.md
│ ├── memory-workflows.md
│ └── user-onboarding.md
├── jest.config.js
├── LICENSE
├── Makefile
├── MCP_PHASE2_IMPLEMENTATION.md
├── mcp-config-example.json
├── mcp.json
├── package-lock.json
├── package.json
├── README.md
├── release.sh
├── scripts
│ └── check-package-structure.cjs
├── SECURITY.md
├── setup-precommit.sh
├── src
│ ├── benchmarks
│ │ └── performance.ts
│ ├── index.ts
│ ├── memory
│ │ ├── contextual-retrieval.ts
│ │ ├── deployment-analytics.ts
│ │ ├── enhanced-manager.ts
│ │ ├── export-import.ts
│ │ ├── freshness-kg-integration.ts
│ │ ├── index.ts
│ │ ├── integration.ts
│ │ ├── kg-code-integration.ts
│ │ ├── kg-health.ts
│ │ ├── kg-integration.ts
│ │ ├── kg-link-validator.ts
│ │ ├── kg-storage.ts
│ │ ├── knowledge-graph.ts
│ │ ├── learning.ts
│ │ ├── manager.ts
│ │ ├── multi-agent-sharing.ts
│ │ ├── pruning.ts
│ │ ├── schemas.ts
│ │ ├── storage.ts
│ │ ├── temporal-analysis.ts
│ │ ├── user-preferences.ts
│ │ └── visualization.ts
│ ├── prompts
│ │ └── technical-writer-prompts.ts
│ ├── scripts
│ │ └── benchmark.ts
│ ├── templates
│ │ └── playwright
│ │ ├── accessibility.spec.template.ts
│ │ ├── Dockerfile.template
│ │ ├── docs-e2e.workflow.template.yml
│ │ ├── link-validation.spec.template.ts
│ │ └── playwright.config.template.ts
│ ├── tools
│ │ ├── analyze-deployments.ts
│ │ ├── analyze-readme.ts
│ │ ├── analyze-repository.ts
│ │ ├── check-documentation-links.ts
│ │ ├── deploy-pages.ts
│ │ ├── detect-gaps.ts
│ │ ├── evaluate-readme-health.ts
│ │ ├── generate-config.ts
│ │ ├── generate-contextual-content.ts
│ │ ├── generate-llm-context.ts
│ │ ├── generate-readme-template.ts
│ │ ├── generate-technical-writer-prompts.ts
│ │ ├── kg-health-check.ts
│ │ ├── manage-preferences.ts
│ │ ├── manage-sitemap.ts
│ │ ├── optimize-readme.ts
│ │ ├── populate-content.ts
│ │ ├── readme-best-practices.ts
│ │ ├── recommend-ssg.ts
│ │ ├── setup-playwright-tests.ts
│ │ ├── setup-structure.ts
│ │ ├── sync-code-to-docs.ts
│ │ ├── test-local-deployment.ts
│ │ ├── track-documentation-freshness.ts
│ │ ├── update-existing-documentation.ts
│ │ ├── validate-content.ts
│ │ ├── validate-documentation-freshness.ts
│ │ ├── validate-readme-checklist.ts
│ │ └── verify-deployment.ts
│ ├── types
│ │ └── api.ts
│ ├── utils
│ │ ├── ast-analyzer.ts
│ │ ├── code-scanner.ts
│ │ ├── content-extractor.ts
│ │ ├── drift-detector.ts
│ │ ├── freshness-tracker.ts
│ │ ├── language-parsers-simple.ts
│ │ ├── permission-checker.ts
│ │ └── sitemap-generator.ts
│ └── workflows
│ └── documentation-workflow.ts
├── test-docs-local.sh
├── tests
│ ├── api
│ │ └── mcp-responses.test.ts
│ ├── benchmarks
│ │ └── performance.test.ts
│ ├── edge-cases
│ │ └── error-handling.test.ts
│ ├── functional
│ │ └── tools.test.ts
│ ├── integration
│ │ ├── kg-documentation-workflow.test.ts
│ │ ├── knowledge-graph-workflow.test.ts
│ │ ├── mcp-readme-tools.test.ts
│ │ ├── memory-mcp-tools.test.ts
│ │ ├── readme-technical-writer.test.ts
│ │ └── workflow.test.ts
│ ├── memory
│ │ ├── contextual-retrieval.test.ts
│ │ ├── enhanced-manager.test.ts
│ │ ├── export-import.test.ts
│ │ ├── freshness-kg-integration.test.ts
│ │ ├── kg-code-integration.test.ts
│ │ ├── kg-health.test.ts
│ │ ├── kg-link-validator.test.ts
│ │ ├── kg-storage-validation.test.ts
│ │ ├── kg-storage.test.ts
│ │ ├── knowledge-graph-enhanced.test.ts
│ │ ├── knowledge-graph.test.ts
│ │ ├── learning.test.ts
│ │ ├── manager-advanced.test.ts
│ │ ├── manager.test.ts
│ │ ├── mcp-resource-integration.test.ts
│ │ ├── mcp-tool-persistence.test.ts
│ │ ├── schemas.test.ts
│ │ ├── storage.test.ts
│ │ ├── temporal-analysis.test.ts
│ │ └── user-preferences.test.ts
│ ├── performance
│ │ ├── memory-load-testing.test.ts
│ │ └── memory-stress-testing.test.ts
│ ├── prompts
│ │ ├── guided-workflow-prompts.test.ts
│ │ └── technical-writer-prompts.test.ts
│ ├── server.test.ts
│ ├── setup.ts
│ ├── tools
│ │ ├── all-tools.test.ts
│ │ ├── analyze-coverage.test.ts
│ │ ├── analyze-deployments.test.ts
│ │ ├── analyze-readme.test.ts
│ │ ├── analyze-repository.test.ts
│ │ ├── check-documentation-links.test.ts
│ │ ├── deploy-pages-kg-retrieval.test.ts
│ │ ├── deploy-pages-tracking.test.ts
│ │ ├── deploy-pages.test.ts
│ │ ├── detect-gaps.test.ts
│ │ ├── evaluate-readme-health.test.ts
│ │ ├── generate-contextual-content.test.ts
│ │ ├── generate-llm-context.test.ts
│ │ ├── generate-readme-template.test.ts
│ │ ├── generate-technical-writer-prompts.test.ts
│ │ ├── kg-health-check.test.ts
│ │ ├── manage-sitemap.test.ts
│ │ ├── optimize-readme.test.ts
│ │ ├── readme-best-practices.test.ts
│ │ ├── recommend-ssg-historical.test.ts
│ │ ├── recommend-ssg-preferences.test.ts
│ │ ├── recommend-ssg.test.ts
│ │ ├── simple-coverage.test.ts
│ │ ├── sync-code-to-docs.test.ts
│ │ ├── test-local-deployment.test.ts
│ │ ├── tool-error-handling.test.ts
│ │ ├── track-documentation-freshness.test.ts
│ │ ├── validate-content.test.ts
│ │ ├── validate-documentation-freshness.test.ts
│ │ └── validate-readme-checklist.test.ts
│ ├── types
│ │ └── type-safety.test.ts
│ └── utils
│ ├── ast-analyzer.test.ts
│ ├── content-extractor.test.ts
│ ├── drift-detector.test.ts
│ ├── freshness-tracker.test.ts
│ └── sitemap-generator.test.ts
├── tsconfig.json
└── typedoc.json
```
# Files
--------------------------------------------------------------------------------
/docs/tutorials/getting-started.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | id: getting-started
3 | title: Getting Started with DocuMCP
4 | sidebar_label: Getting Started
5 | documcp:
6 | last_updated: "2025-11-20T00:46:21.972Z"
7 | last_validated: "2025-11-20T00:46:21.972Z"
8 | auto_updated: false
9 | update_frequency: monthly
10 | ---
11 |
12 | # Getting Started with DocuMCP
13 |
14 | This tutorial will guide you through setting up and using DocuMCP's intelligent documentation deployment system with memory-enhanced capabilities.
15 |
16 | ## Prerequisites
17 |
18 | Before you begin, ensure you have:
19 |
20 | - Node.js 20.0.0 or higher installed
21 | - Access to a GitHub repository
22 | - Claude Desktop, Cursor, or another MCP-compatible client
23 | - Basic familiarity with documentation workflows
24 |
25 | ## 🎯 Pro Tip: Reference LLM_CONTEXT.md
26 |
27 | When using DocuMCP through an AI assistant, **always reference the LLM_CONTEXT.md file** for comprehensive tool context:
28 |
29 | ```
30 | @LLM_CONTEXT.md help me set up documentation for my TypeScript project
31 | ```
32 |
33 | The `LLM_CONTEXT.md` file is auto-generated and contains:
34 |
35 | - All 45 tool descriptions and parameters
36 | - Usage examples and workflows
37 | - Memory system documentation
38 | - Phase 3 code-to-docs sync features
39 |
40 | **Location**: `/LLM_CONTEXT.md` (in project root)
41 |
42 | This ensures your AI assistant has complete context and can provide optimal recommendations.
43 |
44 | ## Step 1: Initial Repository Analysis
45 |
46 | Start by analyzing your repository to understand its characteristics and documentation needs:
47 |
48 | ```json
49 | {
50 | "path": "/path/to/your/project",
51 | "depth": "standard"
52 | }
53 | ```
54 |
55 | This will analyze your project and return:
56 |
57 | - **Project structure**: File counts, languages used, and organization
58 | - **Dependencies**: Production and development packages detected
59 | - **Documentation status**: Existing docs, README, contributing guidelines
60 | - **Smart recommendations**: Primary language, project type, team size estimates
61 | - **Unique analysis ID**: For use in subsequent steps
62 |
63 | Example response snippet:
64 |
65 | ```json
66 | {
67 | "id": "analysis_abc123xyz",
68 | "structure": {
69 | "totalFiles": 150,
70 | "languages": { ".ts": 45, ".js": 12, ".md": 8 },
71 | "hasTests": true,
72 | "hasCI": true
73 | },
74 | "dependencies": {
75 | "ecosystem": "javascript",
76 | "packages": ["react", "typescript"]
77 | },
78 | "recommendations": {
79 | "primaryLanguage": "typescript",
80 | "projectType": "library"
81 | }
82 | }
83 | ```
84 |
85 | ## Step 2: Memory-Enhanced SSG Recommendation
86 |
87 | Next, get intelligent recommendations powered by DocuMCP's memory system:
88 |
89 | ```json
90 | {
91 | "analysisId": "analysis_abc123xyz",
92 | "preferences": {
93 | "ecosystem": "javascript",
94 | "priority": "features"
95 | }
96 | }
97 | ```
98 |
99 | The memory system leverages patterns from 130+ previous projects to provide:
100 |
101 | - **Confidence-scored recommendations** (e.g., Docusaurus with 85% confidence)
102 | - **Historical success data** (69% deployment success rate insights)
103 | - **Pattern-based insights** (Hugo most common with 98 projects, but Docusaurus optimal for TypeScript)
104 | - **Similar project examples** to learn from successful configurations
105 |
106 | Example recommendation response:
107 |
108 | ```json
109 | {
110 | "recommended": "docusaurus",
111 | "confidence": 0.85,
112 | "reasoning": [
113 | "JavaScript/TypeScript ecosystem detected",
114 | "Modern React-based framework aligns with project stack",
115 | "Strong community support and active development"
116 | ],
117 | "alternatives": [
118 | {
119 | "name": "MkDocs",
120 | "score": 0.75,
121 | "pros": ["Simple setup", "Great themes"],
122 | "cons": ["Limited React component support"]
123 | }
124 | ]
125 | }
126 | ```
127 |
128 | ## Step 3: Configuration Generation
129 |
130 | Generate optimized configuration files for your chosen SSG:
131 |
132 | ```javascript
133 | // Generate Docusaurus configuration
134 | {
135 | "ssg": "docusaurus",
136 | "projectName": "Your Project",
137 | "projectDescription": "Your project description",
138 | "outputPath": "/path/to/your/repository"
139 | }
140 | ```
141 |
142 | ## Step 4: Diataxis Structure Setup
143 |
144 | Create a professional documentation structure following the Diataxis framework:
145 |
146 | ```javascript
147 | // Setup documentation structure
148 | {
149 | "path": "/path/to/your/repository/docs",
150 | "ssg": "docusaurus",
151 | "includeExamples": true
152 | }
153 | ```
154 |
155 | This creates four optimized sections following the Diataxis framework:
156 |
157 | - **Tutorials**: Learning-oriented guides for skill acquisition (study context)
158 | - **How-to Guides**: Problem-solving guides for specific tasks (work context)
159 | - **Reference**: Information-oriented content for lookup and verification (information context)
160 | - **Explanation**: Understanding-oriented content for context and background (understanding context)
161 |
162 | ## Step 5: GitHub Pages Deployment
163 |
164 | Set up automated deployment with security best practices:
165 |
166 | ```javascript
167 | // Deploy to GitHub Pages
168 | {
169 | "repository": "/path/to/your/repository",
170 | "ssg": "docusaurus",
171 | "branch": "gh-pages"
172 | }
173 | ```
174 |
175 | This generates:
176 |
177 | - GitHub Actions workflow with OIDC authentication
178 | - Minimal security permissions (pages:write, id-token:write only)
179 | - Automated build and deployment pipeline
180 |
181 | ## Step 6: Memory System Exploration
182 |
183 | Explore DocuMCP's advanced memory capabilities:
184 |
185 | ```javascript
186 | // Get learning statistics
187 | {
188 | "includeDetails": true
189 | }
190 |
191 | // Recall similar projects
192 | {
193 | "query": "typescript documentation",
194 | "type": "recommendation",
195 | "limit": 5
196 | }
197 | ```
198 |
199 | The memory system provides:
200 |
201 | - **Pattern Recognition**: Most successful SSG choices for your project type
202 | - **Historical Insights**: Success rates and common issues
203 | - **Smart Recommendations**: Enhanced suggestions based on similar projects
204 |
205 | ## Verification
206 |
207 | Verify your setup with these checks:
208 |
209 | 1. **Documentation Structure**: Confirm all Diataxis directories are created
210 | 2. **Configuration Files**: Check generated config files are valid
211 | 3. **GitHub Actions**: Verify workflow file in `.github/workflows/`
212 | 4. **Memory Insights**: Review recommendations and confidence scores
213 |
214 | ## Summary
215 |
216 | In this tutorial, you learned how to:
217 |
218 | - **Analyze repositories** with comprehensive project profiling
219 | - **Get intelligent SSG recommendations** using memory-enhanced insights
220 | - **Generate optimized configurations** for your chosen static site generator
221 | - **Create Diataxis-compliant structures** for professional documentation
222 | - **Set up automated GitHub Pages deployment** with security best practices
223 | - **Leverage the memory system** for enhanced recommendations and insights
224 |
225 | ## Next Steps
226 |
227 | - Explore [Memory-Enhanced Workflows](./memory-workflows.md)
228 | - Read [How-To Guides](../how-to/) for specific tasks
229 | - Check the [API Reference](../reference/) for complete tool documentation
230 | - Learn about [Diataxis Framework](../explanation/) principles
231 |
```
--------------------------------------------------------------------------------
/tests/memory/contextual-retrieval.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Basic unit tests for Contextual Memory Retrieval System
3 | * Tests basic context-aware memory retrieval capabilities
4 | * Part of Issue #55 - Advanced Memory Components Unit Tests
5 | */
6 |
7 | import { promises as fs } from "fs";
8 | import path from "path";
9 | import os from "os";
10 | import { MemoryManager } from "../../src/memory/manager.js";
11 | import ContextualRetrievalSystem, {
12 | RetrievalContext,
13 | } from "../../src/memory/contextual-retrieval.js";
14 |
15 | describe("ContextualRetrievalSystem", () => {
16 | let tempDir: string;
17 | let memoryManager: MemoryManager;
18 | let knowledgeGraph: any;
19 | let contextualRetrieval: ContextualRetrievalSystem;
20 |
21 | beforeEach(async () => {
22 | // Create unique temp directory for each test
23 | tempDir = path.join(
24 | os.tmpdir(),
25 | `contextual-retrieval-test-${Date.now()}-${Math.random()
26 | .toString(36)
27 | .substr(2, 9)}`,
28 | );
29 | await fs.mkdir(tempDir, { recursive: true });
30 |
31 | memoryManager = new MemoryManager(tempDir);
32 | await memoryManager.initialize();
33 |
34 | // Create a mock knowledge graph for testing
35 | knowledgeGraph = {
36 | findRelatedNodes: jest.fn().mockResolvedValue([]),
37 | getConnectionStrength: jest.fn().mockResolvedValue(0.5),
38 | query: jest.fn().mockReturnValue({ nodes: [], edges: [] }),
39 | };
40 |
41 | contextualRetrieval = new ContextualRetrievalSystem(
42 | memoryManager,
43 | knowledgeGraph,
44 | );
45 | });
46 |
47 | afterEach(async () => {
48 | // Cleanup temp directory
49 | try {
50 | await fs.rm(tempDir, { recursive: true, force: true });
51 | } catch (error) {
52 | // Ignore cleanup errors
53 | }
54 | });
55 |
56 | describe("Initialization and Configuration", () => {
57 | test("should create ContextualRetrievalSystem instance", () => {
58 | expect(contextualRetrieval).toBeInstanceOf(ContextualRetrievalSystem);
59 | });
60 |
61 | test("should have memory manager and knowledge graph dependencies", () => {
62 | expect(contextualRetrieval).toBeDefined();
63 | // Basic integration test - system should be created with dependencies
64 | });
65 | });
66 |
67 | describe("Basic Contextual Retrieval", () => {
68 | beforeEach(async () => {
69 | // Set up test memories for retrieval tests
70 | await memoryManager.remember("analysis", {
71 | projectPath: "/test/typescript-project",
72 | language: "typescript",
73 | framework: "react",
74 | outcome: "success",
75 | recommendation: "Use TypeScript for better type safety",
76 | });
77 |
78 | await memoryManager.remember("deployment", {
79 | projectPath: "/test/node-project",
80 | language: "javascript",
81 | framework: "express",
82 | outcome: "success",
83 | recommendation: "Deploy with Docker for consistency",
84 | });
85 |
86 | await memoryManager.remember("recommendation", {
87 | projectPath: "/test/python-project",
88 | language: "python",
89 | framework: "django",
90 | outcome: "failure",
91 | recommendation: "Check Python version compatibility",
92 | });
93 | });
94 |
95 | test("should retrieve contextual matches based on project context", async () => {
96 | const retrievalContext: RetrievalContext = {
97 | currentProject: {
98 | path: "/test/typescript-project",
99 | language: "typescript",
100 | framework: "react",
101 | },
102 | userIntent: {
103 | action: "analyze",
104 | urgency: "medium",
105 | experience: "intermediate",
106 | },
107 | temporalContext: {
108 | recency: "recent",
109 | },
110 | };
111 |
112 | const result = await contextualRetrieval.retrieve(
113 | "typescript react documentation",
114 | retrievalContext,
115 | );
116 |
117 | expect(result).toBeDefined();
118 | expect(result.matches).toBeDefined();
119 | expect(Array.isArray(result.matches)).toBe(true);
120 |
121 | // Basic structure validation
122 | if (result.matches.length > 0) {
123 | const match = result.matches[0];
124 | expect(match).toHaveProperty("memory");
125 | expect(match).toHaveProperty("relevanceScore");
126 | expect(typeof match.relevanceScore).toBe("number");
127 | }
128 | });
129 |
130 | test("should handle different user intents", async () => {
131 | const troubleshootContext: RetrievalContext = {
132 | userIntent: {
133 | action: "troubleshoot",
134 | urgency: "high",
135 | experience: "novice",
136 | },
137 | };
138 |
139 | const recommendContext: RetrievalContext = {
140 | userIntent: {
141 | action: "recommend",
142 | urgency: "low",
143 | experience: "expert",
144 | },
145 | };
146 |
147 | const troubleshootResult = await contextualRetrieval.retrieve(
148 | "deployment failed",
149 | troubleshootContext,
150 | );
151 | const recommendResult = await contextualRetrieval.retrieve(
152 | "best practices",
153 | recommendContext,
154 | );
155 |
156 | expect(troubleshootResult).toBeDefined();
157 | expect(recommendResult).toBeDefined();
158 | expect(Array.isArray(troubleshootResult.matches)).toBe(true);
159 | expect(Array.isArray(recommendResult.matches)).toBe(true);
160 | });
161 |
162 | test("should consider temporal context for relevance", async () => {
163 | const recentContext: RetrievalContext = {
164 | temporalContext: {
165 | recency: "recent",
166 | },
167 | };
168 |
169 | const historicalContext: RetrievalContext = {
170 | temporalContext: {
171 | recency: "historical",
172 | },
173 | };
174 |
175 | const recentResult = await contextualRetrieval.retrieve(
176 | "recent activity",
177 | recentContext,
178 | );
179 | const historicalResult = await contextualRetrieval.retrieve(
180 | "historical data",
181 | historicalContext,
182 | );
183 |
184 | expect(recentResult).toBeDefined();
185 | expect(historicalResult).toBeDefined();
186 | expect(Array.isArray(recentResult.matches)).toBe(true);
187 | expect(Array.isArray(historicalResult.matches)).toBe(true);
188 | });
189 | });
190 |
191 | describe("Error Handling and Edge Cases", () => {
192 | test("should handle empty query gracefully", async () => {
193 | const context: RetrievalContext = {
194 | userIntent: {
195 | action: "analyze",
196 | urgency: "medium",
197 | experience: "intermediate",
198 | },
199 | };
200 |
201 | const result = await contextualRetrieval.retrieve("", context);
202 |
203 | expect(result).toBeDefined();
204 | expect(result.matches).toBeDefined();
205 | expect(Array.isArray(result.matches)).toBe(true);
206 | });
207 |
208 | test("should handle minimal context", async () => {
209 | const minimalContext: RetrievalContext = {};
210 |
211 | const result = await contextualRetrieval.retrieve(
212 | "test query",
213 | minimalContext,
214 | );
215 |
216 | expect(result).toBeDefined();
217 | expect(result.matches).toBeDefined();
218 | expect(Array.isArray(result.matches)).toBe(true);
219 | });
220 | });
221 | });
222 |
```
--------------------------------------------------------------------------------
/docs/guides/playwright-integration.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.948Z"
4 | last_validated: "2025-11-20T00:46:21.948Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Playwright Integration Guide
10 |
11 | ## Overview
12 |
13 | DocuMCP can generate a complete Playwright E2E testing setup for your documentation site, including:
14 |
15 | - Playwright configuration
16 | - Link validation tests
17 | - Accessibility tests (WCAG 2.1 AA)
18 | - Docker/Podman containerization
19 | - GitHub Actions CI/CD workflow
20 |
21 | **Important**: Playwright is NOT a dependency of DocuMCP itself. Instead, DocuMCP **generates** the Playwright setup for your documentation site.
22 |
23 | ## Quick Start
24 |
25 | ### Generate Playwright Setup
26 |
27 | Use the `setup_playwright_tests` tool to generate all necessary files:
28 |
29 | ```typescript
30 | {
31 | tool: "setup_playwright_tests",
32 | arguments: {
33 | repositoryPath: "./my-docs-site",
34 | ssg: "docusaurus",
35 | projectName: "My Documentation",
36 | mainBranch: "main",
37 | includeAccessibilityTests: true,
38 | includeDockerfile: true,
39 | includeGitHubActions: true
40 | }
41 | }
42 | ```
43 |
44 | ### What Gets Generated
45 |
46 | ```
47 | my-docs-site/
48 | ├── playwright.config.ts # Playwright configuration
49 | ├── Dockerfile.playwright # Multi-stage Docker build
50 | ├── .github/workflows/
51 | │ └── docs-e2e-tests.yml # CI/CD workflow
52 | ├── tests/e2e/
53 | │ ├── link-validation.spec.ts # Link tests
54 | │ └── accessibility.spec.ts # A11y tests
55 | ├── package.json # Updated with Playwright deps
56 | └── .gitignore # Updated with test artifacts
57 | ```
58 |
59 | ## Generated Files Explained
60 |
61 | ### 1. Playwright Config (`playwright.config.ts`)
62 |
63 | ```typescript
64 | export default defineConfig({
65 | testDir: "./tests/e2e",
66 | timeout: 30 * 1000,
67 | use: {
68 | baseURL: process.env.BASE_URL || "http://localhost:3000",
69 | },
70 | projects: [{ name: "chromium" }, { name: "firefox" }, { name: "webkit" }],
71 | });
72 | ```
73 |
74 | ### 2. Link Validation Tests
75 |
76 | - ✅ Internal navigation links
77 | - ✅ External link HTTP status
78 | - ✅ Anchor/hash links
79 | - ✅ 404 detection
80 |
81 | ### 3. Accessibility Tests
82 |
83 | - ✅ WCAG 2.1 AA compliance (axe-core)
84 | - ✅ Keyboard navigation
85 | - ✅ Image alt text
86 | - ✅ Color contrast
87 |
88 | ### 4. Docker Multi-Stage Build
89 |
90 | ```dockerfile
91 | # Build docs
92 | FROM node:20-alpine AS builder
93 | RUN npm run build
94 |
95 | # Run tests
96 | FROM mcr.microsoft.com/playwright:v1.55.1 AS tester
97 | RUN npx playwright test
98 |
99 | # Serve production
100 | FROM nginx:alpine AS server
101 | COPY build /usr/share/nginx/html
102 | ```
103 |
104 | ### 5. GitHub Actions Workflow
105 |
106 | Automated testing on every push/PR:
107 |
108 | 1. **Build** → Compile documentation
109 | 2. **Test** → Run Playwright in container (chromium, firefox, webkit)
110 | 3. **Deploy** → Push to GitHub Pages (if tests pass)
111 | 4. **Verify** → Test live production site
112 |
113 | ## Usage After Generation
114 |
115 | ### Local Testing
116 |
117 | ```bash
118 | # Install dependencies (in YOUR docs site, not DocuMCP)
119 | cd my-docs-site
120 | npm install
121 |
122 | # Install Playwright browsers
123 | npx playwright install
124 |
125 | # Run tests
126 | npm run test:e2e
127 |
128 | # Run tests in UI mode
129 | npm run test:e2e:ui
130 |
131 | # View test report
132 | npm run test:e2e:report
133 | ```
134 |
135 | ### Docker Testing
136 |
137 | ```bash
138 | # Build test container
139 | docker build -t my-docs-test -f Dockerfile.playwright .
140 |
141 | # Run tests in container
142 | docker run --rm my-docs-test
143 |
144 | # Or with Podman
145 | podman build -t my-docs-test -f Dockerfile.playwright .
146 | podman run --rm my-docs-test
147 | ```
148 |
149 | ### CI/CD Integration
150 |
151 | Push to trigger GitHub Actions:
152 |
153 | ```bash
154 | git add .
155 | git commit -m "Add Playwright E2E tests"
156 | git push origin main
157 | ```
158 |
159 | Workflow will automatically:
160 |
161 | - Build docs
162 | - Run E2E tests across browsers
163 | - Deploy to GitHub Pages (if all tests pass)
164 | - Test production site after deployment
165 |
166 | ## Customization
167 |
168 | ### Add More Tests
169 |
170 | Create new test files in `tests/e2e/`:
171 |
172 | ```typescript
173 | // tests/e2e/navigation.spec.ts
174 | import { test, expect } from "@playwright/test";
175 |
176 | test("breadcrumbs should work", async ({ page }) => {
177 | await page.goto("/docs/some-page");
178 | const breadcrumbs = page.locator('[aria-label="breadcrumb"]');
179 | await expect(breadcrumbs).toBeVisible();
180 | });
181 | ```
182 |
183 | ### Modify Configuration
184 |
185 | Edit `playwright.config.ts`:
186 |
187 | ```typescript
188 | export default defineConfig({
189 | // Increase timeout for slow networks
190 | timeout: 60 * 1000,
191 |
192 | // Add mobile viewports
193 | projects: [
194 | { name: "chromium" },
195 | { name: "Mobile Chrome", use: devices["Pixel 5"] },
196 | ],
197 | });
198 | ```
199 |
200 | ## SSG-Specific Configuration
201 |
202 | DocuMCP automatically configures for your SSG:
203 |
204 | | SSG | Build Command | Build Dir | Port |
205 | | ---------- | -------------------------- | --------- | ---- |
206 | | Jekyll | `bundle exec jekyll build` | `_site` | 4000 |
207 | | Hugo | `hugo` | `public` | 1313 |
208 | | Docusaurus | `npm run build` | `build` | 3000 |
209 | | MkDocs | `mkdocs build` | `site` | 8000 |
210 | | Eleventy | `npx @11ty/eleventy` | `_site` | 8080 |
211 |
212 | ## Knowledge Graph Integration
213 |
214 | Test results are tracked in DocuMCP's Knowledge Graph:
215 |
216 | ```typescript
217 | {
218 | type: "deployment_validation",
219 | properties: {
220 | playwrightResults: {
221 | totalTests: 25,
222 | passed: 24,
223 | failed: 1,
224 | browsers: ["chromium", "firefox", "webkit"],
225 | linksChecked: 127,
226 | brokenLinks: 0,
227 | accessibilityScore: 98,
228 | }
229 | }
230 | }
231 | ```
232 |
233 | ## Troubleshooting
234 |
235 | ### Tests Fail on External Links
236 |
237 | External link validation can fail due to:
238 |
239 | - Network timeouts
240 | - Rate limiting
241 | - CORS issues
242 |
243 | **Solution**: Tests only check first 10 external links. Increase timeout in config.
244 |
245 | ### Container Build Fails
246 |
247 | **Issue**: Docker build fails on dependency installation
248 |
249 | **Solution**: Check SSG-specific dependencies in package.json
250 |
251 | ### CI/CD Workflow Times Out
252 |
253 | **Issue**: GitHub Actions workflow exceeds time limit
254 |
255 | **Solution**: Run only chromium in CI, full matrix locally:
256 |
257 | ```yaml
258 | # .github/workflows/docs-e2e-tests.yml
259 | strategy:
260 | matrix:
261 | browser: [chromium] # Only chromium in CI
262 | ```
263 |
264 | ## Best Practices
265 |
266 | 1. **Run tests before pushing** - `npm run test:e2e`
267 | 2. **Use Docker locally** - Same environment as CI
268 | 3. **Update baselines** - When changing UI intentionally
269 | 4. **Monitor CI reports** - Check artifacts for failures
270 | 5. **Test production** - Workflow tests live site automatically
271 |
272 | ## Example Workflow
273 |
274 | ```bash
275 | # 1. User analyzes their documentation repo with DocuMCP
276 | documcp analyze_repository --path ./my-docs
277 |
278 | # 2. User generates Playwright setup
279 | documcp setup_playwright_tests \
280 | --repositoryPath ./my-docs \
281 | --ssg docusaurus \
282 | --projectName "My Docs"
283 |
284 | # 3. User installs dependencies (in THEIR repo)
285 | cd my-docs
286 | npm install
287 | npx playwright install
288 |
289 | # 4. User runs tests locally
290 | npm run test:e2e
291 |
292 | # 5. User pushes to GitHub
293 | git push origin main
294 |
295 | # 6. GitHub Actions runs tests automatically
296 | # 7. If tests pass, deploys to GitHub Pages
297 | # 8. Tests production site
298 | ```
299 |
300 | ## Resources
301 |
302 | - [Playwright Documentation](https://playwright.dev/)
303 | - [Complete Workflow Guide](./playwright-testing-workflow.md)
304 | - [Link Validation Integration](./link-validation.md)
305 | - [Axe Accessibility Testing](https://github.com/dequelabs/axe-core)
306 |
```
--------------------------------------------------------------------------------
/tests/integration/mcp-readme-tools.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { promises as fs } from "fs";
2 | import { join } from "path";
3 |
4 | describe("MCP Integration Tests", () => {
5 | let tempDir: string;
6 |
7 | beforeEach(async () => {
8 | tempDir = join(process.cwd(), "test-mcp-integration-temp");
9 | await fs.mkdir(tempDir, { recursive: true });
10 | });
11 |
12 | afterEach(async () => {
13 | try {
14 | await fs.rm(tempDir, { recursive: true, force: true });
15 | } catch (error) {
16 | // Ignore cleanup errors
17 | }
18 | });
19 |
20 | describe("Tool Registration", () => {
21 | test("should include evaluate_readme_health in tools list", async () => {
22 | // This test verifies that the README health tool is properly registered
23 | // Since we can't directly access the server instance, we'll test the tool functions directly
24 | // but verify they match the expected MCP interface
25 |
26 | const { evaluateReadmeHealth } = await import(
27 | "../../src/tools/evaluate-readme-health.js"
28 | );
29 |
30 | // Test with valid parameters that match the MCP schema
31 | const readmePath = join(tempDir, "README.md");
32 | await fs.writeFile(readmePath, "# Test Project\n\nBasic README content.");
33 |
34 | const result = await evaluateReadmeHealth({
35 | readme_path: readmePath,
36 | project_type: "community_library", // Valid enum value from schema
37 | });
38 |
39 | expect(result.content).toBeDefined();
40 | expect(result.isError).toBe(false);
41 | });
42 |
43 | test("should include readme_best_practices in tools list", async () => {
44 | const { readmeBestPractices } = await import(
45 | "../../src/tools/readme-best-practices.js"
46 | );
47 |
48 | const readmePath = join(tempDir, "README.md");
49 | await fs.writeFile(
50 | readmePath,
51 | "# Test Library\n\nLibrary documentation.",
52 | );
53 |
54 | const result = await readmeBestPractices({
55 | readme_path: readmePath,
56 | project_type: "library", // Valid enum value from schema
57 | });
58 |
59 | expect(result.success).toBe(true);
60 | expect(result.data).toBeDefined();
61 | });
62 | });
63 |
64 | describe("Parameter Validation", () => {
65 | test("evaluate_readme_health should handle invalid project_type", async () => {
66 | const { evaluateReadmeHealth } = await import(
67 | "../../src/tools/evaluate-readme-health.js"
68 | );
69 |
70 | const readmePath = join(tempDir, "README.md");
71 | await fs.writeFile(readmePath, "# Test");
72 |
73 | const result = await evaluateReadmeHealth({
74 | readme_path: readmePath,
75 | project_type: "invalid_type" as any,
76 | });
77 |
78 | expect(result.isError).toBe(true);
79 | });
80 |
81 | test("readme_best_practices should handle invalid project_type", async () => {
82 | const { readmeBestPractices } = await import(
83 | "../../src/tools/readme-best-practices.js"
84 | );
85 |
86 | const readmePath = join(tempDir, "README.md");
87 | await fs.writeFile(readmePath, "# Test");
88 |
89 | const result = await readmeBestPractices({
90 | readme_path: readmePath,
91 | project_type: "invalid_type" as any,
92 | });
93 |
94 | expect(result.success).toBe(false);
95 | expect(result.error).toBeDefined();
96 | });
97 |
98 | test("evaluate_readme_health should handle missing file", async () => {
99 | const { evaluateReadmeHealth } = await import(
100 | "../../src/tools/evaluate-readme-health.js"
101 | );
102 |
103 | const result = await evaluateReadmeHealth({
104 | readme_path: join(tempDir, "nonexistent.md"),
105 | });
106 |
107 | expect(result.isError).toBe(true);
108 | });
109 |
110 | test("readme_best_practices should handle missing file without template", async () => {
111 | const { readmeBestPractices } = await import(
112 | "../../src/tools/readme-best-practices.js"
113 | );
114 |
115 | const result = await readmeBestPractices({
116 | readme_path: join(tempDir, "nonexistent.md"),
117 | generate_template: false,
118 | });
119 |
120 | expect(result.success).toBe(false);
121 | expect(result.error?.code).toBe("README_NOT_FOUND");
122 | });
123 | });
124 |
125 | describe("Response Format Consistency", () => {
126 | test("evaluate_readme_health should return MCP-formatted response", async () => {
127 | const { evaluateReadmeHealth } = await import(
128 | "../../src/tools/evaluate-readme-health.js"
129 | );
130 |
131 | const readmePath = join(tempDir, "README.md");
132 | await fs.writeFile(
133 | readmePath,
134 | "# Complete Project\n\n## Description\nDetailed description.",
135 | );
136 |
137 | const result = await evaluateReadmeHealth({
138 | readme_path: readmePath,
139 | });
140 |
141 | // Should be already formatted for MCP
142 | expect(result.content).toBeDefined();
143 | expect(Array.isArray(result.content)).toBe(true);
144 | expect(result.isError).toBeDefined();
145 |
146 | // Should have execution metadata
147 | const metadataContent = result.content.find((c) =>
148 | c.text.includes("Execution completed"),
149 | );
150 | expect(metadataContent).toBeDefined();
151 | });
152 |
153 | test("readme_best_practices should return MCPToolResponse that can be formatted", async () => {
154 | const { readmeBestPractices } = await import(
155 | "../../src/tools/readme-best-practices.js"
156 | );
157 | const { formatMCPResponse } = await import("../../src/types/api.js");
158 |
159 | const readmePath = join(tempDir, "README.md");
160 | await fs.writeFile(
161 | readmePath,
162 | "# Library Project\n\n## Installation\nnpm install",
163 | );
164 |
165 | const result = await readmeBestPractices({
166 | readme_path: readmePath,
167 | });
168 |
169 | // Should be raw MCPToolResponse
170 | expect(result.success).toBeDefined();
171 | expect(result.metadata).toBeDefined();
172 |
173 | // Should be formattable
174 | const formatted = formatMCPResponse(result);
175 | expect(formatted.content).toBeDefined();
176 | expect(Array.isArray(formatted.content)).toBe(true);
177 | expect(formatted.isError).toBe(false);
178 | });
179 | });
180 |
181 | describe("Cross-tool Consistency", () => {
182 | test("both tools should handle the same README file", async () => {
183 | const { evaluateReadmeHealth } = await import(
184 | "../../src/tools/evaluate-readme-health.js"
185 | );
186 | const { readmeBestPractices } = await import(
187 | "../../src/tools/readme-best-practices.js"
188 | );
189 |
190 | const readmePath = join(tempDir, "README.md");
191 | await fs.writeFile(
192 | readmePath,
193 | `# Test Project
194 |
195 | ## Description
196 | This is a comprehensive test project.
197 |
198 | ## Installation
199 | \`\`\`bash
200 | npm install test-project
201 | \`\`\`
202 |
203 | ## Usage
204 | \`\`\`javascript
205 | const test = require('test-project');
206 | test.run();
207 | \`\`\`
208 |
209 | ## Contributing
210 | Please read our contributing guidelines.
211 |
212 | ## License
213 | MIT License
214 | `,
215 | );
216 |
217 | // Both tools should work on the same file
218 | const healthResult = await evaluateReadmeHealth({
219 | readme_path: readmePath,
220 | project_type: "community_library",
221 | });
222 |
223 | const practicesResult = await readmeBestPractices({
224 | readme_path: readmePath,
225 | project_type: "library",
226 | });
227 |
228 | expect(healthResult.isError).toBe(false);
229 | expect(practicesResult.success).toBe(true);
230 | });
231 | });
232 | });
233 |
```
--------------------------------------------------------------------------------
/docs/how-to/repository-analysis.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.954Z"
4 | last_validated: "2025-11-20T00:46:21.954Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Analyze Your Repository with DocuMCP
10 |
11 | This guide walks you through using DocuMCP's repository analysis capabilities to understand your project's documentation needs.
12 |
13 | ## What Repository Analysis Provides
14 |
15 | DocuMCP's analysis examines your project from multiple perspectives:
16 |
17 | - **Project Structure**: File organization, language distribution, directory structure
18 | - **Dependencies**: Package ecosystems, frameworks, and libraries in use
19 | - **Documentation Status**: Existing documentation files, README quality, coverage gaps
20 | - **Complexity Assessment**: Project size, team size estimates, maintenance requirements
21 | - **Recommendations**: Tailored suggestions based on your project characteristics
22 |
23 | ## Basic Analysis
24 |
25 | ### Simple Analysis Request
26 |
27 | ```
28 | analyze my repository
29 | ```
30 |
31 | This performs a standard-depth analysis covering all key aspects of your project.
32 |
33 | ### Specify Analysis Depth
34 |
35 | ```
36 | analyze my repository with deep analysis
37 | ```
38 |
39 | Available depth levels:
40 |
41 | - **quick**: Fast overview focusing on basic structure and languages
42 | - **standard**: Comprehensive analysis including dependencies and documentation (recommended)
43 | - **deep**: Detailed analysis with advanced insights and recommendations
44 |
45 | ## Understanding Analysis Results
46 |
47 | ### Project Structure Section
48 |
49 | ```json
50 | {
51 | "structure": {
52 | "totalFiles": 2034,
53 | "totalDirectories": 87,
54 | "languages": {
55 | ".ts": 86,
56 | ".js": 13,
57 | ".css": 3,
58 | ".html": 37
59 | },
60 | "hasTests": true,
61 | "hasCI": true,
62 | "hasDocs": true
63 | }
64 | }
65 | ```
66 |
67 | This tells you:
68 |
69 | - Scale of your project (file/directory count)
70 | - Primary programming languages
71 | - Presence of tests, CI/CD, and existing documentation
72 |
73 | ### Dependencies Analysis
74 |
75 | ```json
76 | {
77 | "dependencies": {
78 | "ecosystem": "javascript",
79 | "packages": ["@modelcontextprotocol/sdk", "zod", "typescript"],
80 | "devPackages": ["jest", "@types/node", "eslint"]
81 | }
82 | }
83 | ```
84 |
85 | This reveals:
86 |
87 | - Primary package ecosystem (npm, pip, cargo, etc.)
88 | - Key runtime dependencies
89 | - Development and tooling dependencies
90 |
91 | ### Documentation Assessment
92 |
93 | ```json
94 | {
95 | "documentation": {
96 | "hasReadme": true,
97 | "hasContributing": true,
98 | "hasLicense": true,
99 | "existingDocs": ["README.md", "docs/api.md"],
100 | "estimatedComplexity": "complex"
101 | }
102 | }
103 | ```
104 |
105 | This shows:
106 |
107 | - Presence of essential documentation files
108 | - Existing documentation structure
109 | - Complexity level for documentation planning
110 |
111 | ## Advanced Analysis Techniques
112 |
113 | ### Target Specific Directories
114 |
115 | ```
116 | analyze the src directory for API documentation needs
117 | ```
118 |
119 | ### Focus on Documentation Gaps
120 |
121 | ```
122 | what documentation is missing from my project?
123 | ```
124 |
125 | ### Analyze for Specific Use Cases
126 |
127 | ```
128 | analyze my repository to determine if it needs user guides or developer documentation
129 | ```
130 |
131 | ## Using Analysis Results
132 |
133 | ### For SSG Selection
134 |
135 | After analysis, use the results to get targeted recommendations:
136 |
137 | ```
138 | based on the analysis, what static site generator works best for my TypeScript project?
139 | ```
140 |
141 | ### For Documentation Planning
142 |
143 | Use analysis insights to plan your documentation structure:
144 |
145 | ```
146 | given my project complexity, how should I organize my documentation?
147 | ```
148 |
149 | ### For Deployment Strategy
150 |
151 | Let analysis guide your deployment approach:
152 |
153 | ```
154 | considering my project setup, what's the best way to deploy documentation?
155 | ```
156 |
157 | ## Analysis-Driven Workflows
158 |
159 | ### Complete Documentation Setup
160 |
161 | 1. **Analyze**: `analyze my repository for documentation needs`
162 | 2. **Plan**: Use analysis results to understand project characteristics
163 | 3. **Recommend**: `recommend documentation tools based on the analysis`
164 | 4. **Implement**: `set up documentation based on the recommendations`
165 |
166 | ### Documentation Audit
167 |
168 | 1. **Current State**: `analyze my existing documentation structure`
169 | 2. **Gap Analysis**: `what documentation gaps exist in my project?`
170 | 3. **Improvement Plan**: `how can I improve my current documentation?`
171 |
172 | ### Migration Planning
173 |
174 | 1. **Legacy Analysis**: `analyze my project's current documentation approach`
175 | 2. **Modern Approach**: `what modern documentation tools would work better?`
176 | 3. **Migration Strategy**: `how should I migrate from my current setup?`
177 |
178 | ## Interpreting Recommendations
179 |
180 | ### Project Type Classification
181 |
182 | Analysis categorizes your project as:
183 |
184 | - **library**: Reusable code packages requiring API documentation
185 | - **application**: End-user software needing user guides and tutorials
186 | - **tool**: Command-line or developer tools requiring usage documentation
187 |
188 | ### Team Size Estimation
189 |
190 | - **small**: 1-3 developers, favor simple solutions
191 | - **medium**: 4-10 developers, need collaborative features
192 | - **large**: 10+ developers, require enterprise-grade solutions
193 |
194 | ### Complexity Assessment
195 |
196 | - **simple**: Basic projects with minimal documentation needs
197 | - **moderate**: Standard projects requiring structured documentation
198 | - **complex**: Large projects needing comprehensive documentation strategies
199 |
200 | ## Common Analysis Patterns
201 |
202 | ### JavaScript/TypeScript Projects
203 |
204 | Analysis typically reveals:
205 |
206 | - npm ecosystem with extensive dev dependencies
207 | - Need for API documentation (if library)
208 | - Integration with existing build tools
209 | - Recommendation: Often Docusaurus or VuePress
210 |
211 | ### Python Projects
212 |
213 | Analysis usually shows:
214 |
215 | - pip/poetry ecosystem
216 | - Sphinx-compatible documentation needs
217 | - Strong preference for MkDocs
218 | - Integration with Python documentation standards
219 |
220 | ### Multi-Language Projects
221 |
222 | Analysis identifies:
223 |
224 | - Mixed ecosystems and dependencies
225 | - Need for language-agnostic solutions
226 | - Recommendation: Usually Hugo or Jekyll for flexibility
227 |
228 | ## Troubleshooting Analysis
229 |
230 | ### Incomplete Results
231 |
232 | If analysis seems incomplete:
233 |
234 | ```
235 | run deep analysis on my repository to get more detailed insights
236 | ```
237 |
238 | ### Focus on Specific Areas
239 |
240 | If you need more details about certain aspects:
241 |
242 | ```
243 | analyze my project's dependencies in detail
244 | ```
245 |
246 | ### Re-analyze After Changes
247 |
248 | After making significant changes:
249 |
250 | ```
251 | re-analyze my repository to see updated recommendations
252 | ```
253 |
254 | ## Analysis Memory and Caching
255 |
256 | DocuMCP stores analysis results for reference in future operations:
257 |
258 | - Analysis IDs are provided for referencing specific analyses
259 | - Results remain accessible throughout your session
260 | - Memory system learns from successful documentation deployments
261 |
262 | Use analysis IDs in follow-up requests:
263 |
264 | ```
265 | using analysis analysis_abc123, set up the recommended documentation structure
266 | ```
267 |
268 | ## Best Practices
269 |
270 | 1. **Start Fresh**: Begin new documentation projects with analysis
271 | 2. **Regular Reviews**: Re-analyze periodically as projects evolve
272 | 3. **Deep Dive When Needed**: Use deep analysis for complex projects
273 | 4. **Combine with Expertise**: Use analysis as a starting point, not final decision
274 | 5. **Iterate**: Refine based on analysis feedback and results
275 |
276 | Analysis is the foundation of effective documentation planning with DocuMCP. Use it to make informed decisions about tools, structure, and deployment strategies.
277 |
```
--------------------------------------------------------------------------------
/docs/research/domain-5-github-deployment/github-pages-security-analysis.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.967Z"
4 | last_validated: "2025-11-20T00:46:21.967Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # GitHub Pages Deployment Security and Limitations Analysis
10 |
11 | **Research Date**: 2025-01-14
12 | **Domain**: GitHub Pages Deployment Automation
13 | **Status**: Completed
14 |
15 | ## Research Overview
16 |
17 | Comprehensive analysis of GitHub Pages deployment security considerations, limitations, and automation best practices for DocuMCP implementation.
18 |
19 | ## GitHub Pages Security Model Analysis
20 |
21 | ### Deployment Methods & Security Implications
22 |
23 | #### **1. GitHub Actions (Official Method)**
24 |
25 | **Security Profile**:
26 |
27 | - ✅ **OIDC Token-based Authentication**: Uses JWT tokens with branch validation
28 | - ✅ **Permissions Model**: Requires explicit `pages: write` and `id-token: write`
29 | - ✅ **Environment Protection**: Supports environment rules and approvals
30 | - ⚠️ **First Deploy Challenge**: Manual branch selection required initially
31 |
32 | **Implementation Pattern**:
33 |
34 | ```yaml
35 | permissions:
36 | pages: write # Deploy to Pages
37 | id-token: write # Verify deployment origin
38 | contents: read # Checkout repository
39 |
40 | environment:
41 | name: github-pages
42 | url: ${{ steps.deployment.outputs.page_url }}
43 | ```
44 |
45 | #### **2. Deploy Keys (SSH Method)**
46 |
47 | **Security Profile**:
48 |
49 | - ✅ **Repository-specific**: Keys scoped to individual repositories
50 | - ✅ **Write Access Control**: Can be limited to deployment-only access
51 | - ⚠️ **Key Management**: Requires secure key generation and storage
52 | - ⚠️ **Cross-repo Complexity**: Each external repo needs separate key setup
53 |
54 | #### **3. Personal Access Tokens**
55 |
56 | **Security Profile**:
57 |
58 | - ⚠️ **Broad Permissions**: Often have wider access than needed
59 | - ⚠️ **Expiration Management**: Tokens expire and need rotation
60 | - ⚠️ **Account-wide Risk**: Compromise affects all accessible repositories
61 |
62 | ### GitHub Pages Deployment Limitations
63 |
64 | #### **Technical Constraints**
65 |
66 | 1. **Site Size Limits**:
67 |
68 | - Maximum 1GB per repository
69 | - Impacts large documentation sites with assets
70 | - No compression before size calculation
71 |
72 | 2. **Build Frequency Limits**:
73 |
74 | - 10 builds per hour soft limit
75 | - Additional builds queued for next hour
76 | - Can impact rapid deployment cycles
77 |
78 | 3. **Static Content Only**:
79 | - No server-side processing
80 | - No dynamic content generation
81 | - Limited to client-side JavaScript
82 |
83 | #### **Security Constraints**
84 |
85 | 1. **Content Security Policy**:
86 |
87 | - Default CSP may block certain resources
88 | - Limited ability to customize security headers
89 | - No server-side security controls
90 |
91 | 2. **HTTPS Enforcement**:
92 | - Custom domains require manual HTTPS setup
93 | - Certificate management through GitHub
94 | - No control over TLS configuration
95 |
96 | ### CI/CD Workflow Security Best Practices
97 |
98 | #### **Recommended Security Architecture**
99 |
100 | ```yaml
101 | name: Deploy Documentation
102 |
103 | on:
104 | push:
105 | branches: [main]
106 | pull_request:
107 | branches: [main]
108 |
109 | jobs:
110 | security-scan:
111 | runs-on: ubuntu-latest
112 | steps:
113 | - uses: actions/checkout@v4
114 | - name: Security scan
115 | run: |
116 | # Scan for secrets, vulnerabilities
117 | npm audit --audit-level high
118 |
119 | build:
120 | needs: security-scan
121 | runs-on: ubuntu-latest
122 | steps:
123 | - uses: actions/checkout@v4
124 | - name: Build site
125 | run: npm run build
126 | - name: Upload artifact
127 | uses: actions/upload-pages-artifact@v3
128 | with:
129 | path: ./dist
130 |
131 | deploy:
132 | if: github.ref == 'refs/heads/main'
133 | needs: build
134 | runs-on: ubuntu-latest
135 | permissions:
136 | pages: write
137 | id-token: write
138 | environment:
139 | name: github-pages
140 | url: ${{ steps.deployment.outputs.page_url }}
141 | steps:
142 | - name: Deploy to GitHub Pages
143 | id: deployment
144 | uses: actions/deploy-pages@v4
145 | ```
146 |
147 | #### **Security Validation Steps**
148 |
149 | 1. **Pre-deployment Checks**:
150 |
151 | - Secret scanning
152 | - Dependency vulnerability assessment
153 | - Content validation
154 |
155 | 2. **Deployment Security**:
156 |
157 | - Environment protection rules
158 | - Required reviewers for production
159 | - Branch protection enforcement
160 |
161 | 3. **Post-deployment Verification**:
162 | - Site accessibility validation
163 | - Security header verification
164 | - Content integrity checks
165 |
166 | ### DocuMCP Security Implementation Recommendations
167 |
168 | #### **Multi-layered Security Approach**
169 |
170 | 1. **Tool-level Security**:
171 |
172 | ```typescript
173 | // Example security validation in MCP tool
174 | const validateDeploymentSecurity = (config: DeploymentConfig) => {
175 | const securityChecks = {
176 | hasSecretScanning: checkSecretScanning(config),
177 | hasEnvironmentProtection: checkEnvironmentRules(config),
178 | hasProperPermissions: validatePermissions(config),
179 | hasSecurityHeaders: validateSecurityHeaders(config),
180 | };
181 |
182 | return securityChecks;
183 | };
184 | ```
185 |
186 | 2. **Configuration Template Security**:
187 |
188 | - Generate workflows with minimal required permissions
189 | - Include security scanning by default
190 | - Enforce environment protection for production
191 |
192 | 3. **User Education Components**:
193 | - Security best practices documentation
194 | - Common vulnerability warnings
195 | - Regular security updates guidance
196 |
197 | ### Risk Assessment & Mitigation
198 |
199 | #### **High-Risk Scenarios**
200 |
201 | 1. **Secret Exposure in Repositories**:
202 |
203 | - **Risk**: API keys, tokens in code
204 | - **Mitigation**: Mandatory secret scanning, education
205 |
206 | 2. **Malicious Pull Request Deployments**:
207 |
208 | - **Risk**: Untrusted code in preview deployments
209 | - **Mitigation**: Environment protection, review requirements
210 |
211 | 3. **Supply Chain Attacks**:
212 | - **Risk**: Compromised dependencies
213 | - **Mitigation**: Dependency scanning, lock files
214 |
215 | #### **Medium-Risk Scenarios**
216 |
217 | 1. **Excessive Permissions**:
218 |
219 | - **Risk**: Overprivileged deployment workflows
220 | - **Mitigation**: Principle of least privilege templates
221 |
222 | 2. **Unprotected Environments**:
223 | - **Risk**: Direct production deployments
224 | - **Mitigation**: Default environment protection
225 |
226 | ### Implementation Priorities for DocuMCP
227 |
228 | #### **Critical Security Features**
229 |
230 | 1. **Automated Security Scanning**: Integrate secret and vulnerability scanning
231 | 2. **Permission Minimization**: Generate workflows with minimal required permissions
232 | 3. **Environment Protection**: Default protection rules for production environments
233 | 4. **Security Documentation**: Clear guidance on security best practices
234 |
235 | #### **Enhanced Security Features**
236 |
237 | 1. **Custom Security Checks**: Advanced validation for specific project types
238 | 2. **Security Reporting**: Automated security posture assessment
239 | 3. **Incident Response**: Guidance for security issue handling
240 |
241 | ## Research Validation Status
242 |
243 | - ✅ GitHub Pages security model analyzed
244 | - ✅ Deployment methods evaluated
245 | - ✅ Security best practices documented
246 | - ✅ Risk assessment completed
247 | - ⚠️ Needs validation: Security template effectiveness testing
248 | - ⚠️ Needs implementation: DocuMCP security feature integration
249 |
250 | ## Sources & References
251 |
252 | 1. GitHub Pages Official Documentation - Security Guidelines
253 | 2. GitHub Actions Security Best Practices
254 | 3. OWASP Static Site Security Guide
255 | 4. GitHub Security Advisory Database
256 | 5. Community Security Analysis Reports
257 |
```
--------------------------------------------------------------------------------
/docs/research/research-integration-summary-2025-01-14.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.968Z"
4 | last_validated: "2025-11-20T00:46:21.968Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Research Integration Summary
10 |
11 | **Date**: 2025-01-14
12 | **Status**: Completed
13 | **Integration Method**: Direct ADR Updates + Implementation Recommendations
14 |
15 | ## Research Integration Overview
16 |
17 | This document summarizes how research findings from systematic web research using Firecrawl MCP server have been incorporated into DocuMCP's architectural decisions and implementation planning.
18 |
19 | ## Research Areas Integrated
20 |
21 | ### ✅ **1. MCP Server Architecture (ADR-001)**
22 |
23 | **Research Source**: `domain-1-mcp-architecture/mcp-performance-research.md`
24 |
25 | **Key Integrations**:
26 |
27 | - **Performance Validation**: Confirmed TypeScript MCP SDK provides minimal overhead with JSON-RPC 2.0
28 | - **Memory Optimization**: Integrated streaming patterns (10x memory reduction) and worker threads (3-4x performance)
29 | - **Implementation Strategy**: Added concrete code patterns for repository analysis with performance benchmarks
30 |
31 | **ADR Updates Applied**:
32 |
33 | - Added "Research Integration" section with validated performance characteristics
34 | - Integrated specific implementation patterns for streaming and worker threads
35 | - Established research-validated performance targets for different repository sizes
36 |
37 | ### ✅ **2. SSG Recommendation Engine (ADR-003)**
38 |
39 | **Research Source**: `domain-3-ssg-recommendation/ssg-performance-analysis.md`
40 |
41 | **Key Integrations**:
42 |
43 | - **Performance Matrix**: Comprehensive build time analysis across SSG scales
44 | - **Algorithm Enhancement**: Research-validated scoring with scale-based weighting
45 | - **Real-World Data**: Hugo 250x faster than Gatsby (small sites), gap narrows to 40x (large sites)
46 |
47 | **ADR Updates Applied**:
48 |
49 | - Enhanced performance modeling with research-validated SSG performance matrix
50 | - Updated recommendation algorithm with evidence-based scoring
51 | - Integrated scale-based performance weighting (critical path vs features)
52 |
53 | ### ✅ **3. GitHub Pages Deployment Security (ADR-005)**
54 |
55 | **Research Source**: `domain-5-github-deployment/github-pages-security-analysis.md`
56 |
57 | **Key Integrations**:
58 |
59 | - **Security Architecture**: OIDC token authentication with JWT validation
60 | - **Permission Minimization**: Specific `pages: write` and `id-token: write` requirements
61 | - **Environment Protection**: Default security rules with approval workflows
62 | - **Automated Scanning**: Integrated secret and vulnerability detection
63 |
64 | **ADR Updates Applied**:
65 |
66 | - Enhanced repository configuration management with research-validated security practices
67 | - Added multi-layered security approach with specific implementation details
68 | - Integrated automated security scanning and environment protection requirements
69 |
70 | ## Implementation Impact Analysis
71 |
72 | ### **Immediate Implementation Requirements**
73 |
74 | 1. **High Priority Updates** (Week 1-2):
75 |
76 | - Implement streaming-based repository analysis with 10MB threshold
77 | - Create worker thread pool for parallel file processing
78 | - Integrate OIDC-based GitHub Pages deployment templates
79 |
80 | 2. **Medium Priority Enhancements** (Week 3-4):
81 | - Develop SSG performance scoring algorithm with research-validated weights
82 | - Implement automated security scanning in generated workflows
83 | - Create environment protection templates
84 |
85 | ### **Architecture Validation Status**
86 |
87 | | **Decision Area** | **Research Status** | **Validation Result** | **Implementation Ready** |
88 | | --------------------- | ------------------- | ---------------------------- | ------------------------ |
89 | | TypeScript MCP SDK | ✅ Validated | Confirmed optimal choice | ✅ Yes |
90 | | Node.js Performance | ✅ Validated | Specific patterns identified | ✅ Yes |
91 | | SSG Recommendation | ✅ Validated | Algorithm refined | ✅ Yes |
92 | | GitHub Pages Security | ✅ Validated | Security model confirmed | ✅ Yes |
93 | | Repository Analysis | ✅ Validated | Streaming patterns proven | ✅ Yes |
94 |
95 | ### **Risk Mitigation Updates**
96 |
97 | **Original Risk**: Memory constraints for large repository analysis
98 | **Research Mitigation**: 10x memory reduction with streaming + worker threads
99 | **Implementation**: Concrete code patterns integrated into ADR-001
100 |
101 | **Original Risk**: SSG recommendation accuracy
102 | **Research Mitigation**: Evidence-based performance weighting algorithm
103 | **Implementation**: Performance matrix and scoring algorithm in ADR-003
104 |
105 | **Original Risk**: Deployment security vulnerabilities
106 | **Research Mitigation**: Multi-layered security with OIDC authentication
107 | **Implementation**: Enhanced security configuration in ADR-005
108 |
109 | ## Research Validation Metrics
110 |
111 | ### **Research Quality Assessment**
112 |
113 | - **Sources Analyzed**: 15+ authoritative sources (GitHub docs, CSS-Tricks benchmarks, security guides)
114 | - **Data Points Validated**: 50+ specific performance metrics and security practices
115 | - **Implementation Patterns**: 12+ concrete code examples and configuration templates
116 | - **Best Practices**: 25+ industry-validated approaches integrated
117 |
118 | ### **ADR Enhancement Metrics**
119 |
120 | - **ADRs Updated**: 3 core architectural decisions
121 | - **New Content Added**: ~500 lines of research-validated implementation guidance
122 | - **Performance Targets**: Quantitative benchmarks established for all components
123 | - **Security Practices**: Comprehensive security model with specific configurations
124 |
125 | ## Next Steps & Continuous Integration
126 |
127 | ### **Immediate Actions** (Next 48 hours)
128 |
129 | 1. **Implementation Planning**: Use research-validated patterns for MVP development
130 | 2. **Security Review**: Validate enhanced security configurations with team
131 | 3. **Performance Testing**: Create benchmarks based on research targets
132 |
133 | ### **Short-term Integration** (Next 2 weeks)
134 |
135 | 1. **Prototype Development**: Implement streaming repository analysis
136 | 2. **Algorithm Validation**: Test SSG recommendation scoring with real projects
137 | 3. **Security Testing**: Validate OIDC deployment workflows
138 |
139 | ### **Long-term Monitoring** (Ongoing)
140 |
141 | 1. **Performance Validation**: Compare actual performance against research predictions
142 | 2. **Security Auditing**: Regular validation of security practices
143 | 3. **Research Updates**: Monitor for new performance data and security practices
144 |
145 | ## Research Integration Success Criteria
146 |
147 | ✅ **Architectural Validation**: All core decisions validated with evidence
148 | ✅ **Implementation Guidance**: Concrete patterns and code examples provided
149 | ✅ **Performance Targets**: Quantitative benchmarks established
150 | ✅ **Security Framework**: Comprehensive security model implemented
151 | ✅ **Risk Mitigation**: Major risks addressed with validated solutions
152 |
153 | **Overall Integration Status**: **SUCCESSFUL** - Ready for implementation phase
154 |
155 | ---
156 |
157 | **Research Conducted Using**: Firecrawl MCP Server systematic web research
158 | **Research Duration**: 4 hours intensive analysis
159 | **Integration Method**: Direct ADR updates with validation tracking
160 | **Confidence Level**: 95% - Based on authoritative sources and comprehensive analysis
161 |
```
--------------------------------------------------------------------------------
/docs/how-to/prompting-guide.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.953Z"
4 | last_validated: "2025-11-20T00:46:21.953Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Prompt DocuMCP Effectively
10 |
11 | This guide shows you how to interact with DocuMCP using effective prompts to get the best results from the system.
12 |
13 | ## 🎯 Pro Tip: Use @LLM_CONTEXT.md
14 |
15 | When using DocuMCP in your AI assistant (Claude, ChatGPT, etc.), **reference the LLM_CONTEXT.md file** for instant context about all 45 available tools:
16 |
17 | ```
18 | @LLM_CONTEXT.md analyze my repository and recommend the best deployment strategy
19 | ```
20 |
21 | The `LLM_CONTEXT.md` file provides:
22 |
23 | - Complete tool descriptions and parameters
24 | - Usage examples for all 45 tools
25 | - Common workflow patterns
26 | - Memory system documentation
27 | - Phase 3 code-to-docs sync capabilities
28 |
29 | **Location**: `/LLM_CONTEXT.md` in the root of your project
30 |
31 | This ensures your AI assistant has full context about DocuMCP's capabilities and can provide more accurate recommendations.
32 |
33 | ## Quick Start
34 |
35 | DocuMCP responds to natural language prompts. Here are the most common patterns:
36 |
37 | ### Basic Analysis
38 |
39 | ```
40 | analyze my repository for documentation needs
41 | ```
42 |
43 | ### Get Recommendations
44 |
45 | ```
46 | what static site generator should I use for my project?
47 | ```
48 |
49 | ### Deploy Documentation
50 |
51 | ```
52 | set up GitHub Pages deployment for my docs
53 | ```
54 |
55 | ## Available Tools
56 |
57 | DocuMCP provides several tools you can invoke through natural prompts:
58 |
59 | ### 1. Repository Analysis
60 |
61 | **Purpose**: Analyze your project structure, dependencies, and documentation needs.
62 |
63 | **Example Prompts**:
64 |
65 | - "Analyze my repository structure"
66 | - "What documentation gaps do I have?"
67 | - "Examine my project for documentation opportunities"
68 |
69 | **What it returns**: Project analysis with language detection, dependency mapping, and complexity assessment.
70 |
71 | ### 2. SSG Recommendations
72 |
73 | **Purpose**: Get intelligent static site generator recommendations based on your project.
74 |
75 | **Example Prompts**:
76 |
77 | - "Recommend a static site generator for my TypeScript project"
78 | - "Which SSG works best with my Python documentation?"
79 | - "Compare documentation tools for my project"
80 |
81 | **What it returns**: Weighted recommendations with justifications for Jekyll, Hugo, Docusaurus, MkDocs, or Eleventy.
82 |
83 | ### 3. Configuration Generation
84 |
85 | **Purpose**: Generate SSG-specific configuration files.
86 |
87 | **Example Prompts**:
88 |
89 | - "Generate a Hugo config for my project"
90 | - "Create MkDocs configuration files"
91 | - "Set up Docusaurus for my documentation"
92 |
93 | **What it returns**: Ready-to-use configuration files optimized for your project.
94 |
95 | ### 4. Documentation Structure
96 |
97 | **Purpose**: Create Diataxis-compliant documentation structure.
98 |
99 | **Example Prompts**:
100 |
101 | - "Set up documentation structure following Diataxis"
102 | - "Create organized docs folders for my project"
103 | - "Build a comprehensive documentation layout"
104 |
105 | **What it returns**: Organized folder structure with templates following documentation best practices.
106 |
107 | ### 5. GitHub Pages Deployment
108 |
109 | **Purpose**: Automate GitHub Pages deployment workflows.
110 |
111 | **Example Prompts**:
112 |
113 | - "Deploy my docs to GitHub Pages"
114 | - "Set up automated documentation deployment"
115 | - "Create GitHub Actions for my documentation site"
116 |
117 | **What it returns**: GitHub Actions workflows configured for your chosen SSG.
118 |
119 | ### 6. Deployment Verification
120 |
121 | **Purpose**: Verify and troubleshoot GitHub Pages deployments.
122 |
123 | **Example Prompts**:
124 |
125 | - "Check if my GitHub Pages deployment is working"
126 | - "Troubleshoot my documentation deployment"
127 | - "Verify my docs site is live"
128 |
129 | **What it returns**: Deployment status and troubleshooting recommendations.
130 |
131 | ## Advanced Prompting Techniques
132 |
133 | ### Chained Operations
134 |
135 | You can chain multiple operations in a single conversation:
136 |
137 | ```
138 | 1. First analyze my repository
139 | 2. Then recommend the best SSG
140 | 3. Finally set up the deployment workflow
141 | ```
142 |
143 | ### Specific Requirements
144 |
145 | Be specific about your needs:
146 |
147 | ```
148 | I need a documentation site that:
149 | - Works with TypeScript
150 | - Supports API documentation
151 | - Has good search functionality
152 | - Deploys automatically on commits
153 | ```
154 |
155 | ### Context-Aware Requests
156 |
157 | Reference previous analysis:
158 |
159 | ```
160 | Based on the analysis you just did, create the documentation structure and deploy it to GitHub Pages
161 | ```
162 |
163 | ## Best Practices
164 |
165 | ### 1. Start with Analysis
166 |
167 | Always begin with repository analysis to get tailored recommendations:
168 |
169 | ```
170 | analyze my project for documentation needs
171 | ```
172 |
173 | ### 2. Be Specific About Goals
174 |
175 | Tell DocuMCP what you're trying to achieve:
176 |
177 | - "I need developer documentation for my API"
178 | - "I want user guides for my application"
179 | - "I need project documentation for contributors"
180 |
181 | ### 3. Specify Constraints
182 |
183 | Mention any limitations or preferences:
184 |
185 | - "I prefer minimal setup"
186 | - "I need something that works with our CI/CD pipeline"
187 | - "I want to use our existing design system"
188 |
189 | ### 4. Ask for Explanations
190 |
191 | Request reasoning behind recommendations:
192 |
193 | ```
194 | why did you recommend Hugo over Jekyll for my project?
195 | ```
196 |
197 | ### 5. Iterate and Refine
198 |
199 | Use follow-up prompts to refine results:
200 |
201 | ```
202 | can you modify the GitHub Actions workflow to also run tests?
203 | ```
204 |
205 | ## Common Workflows
206 |
207 | ### Complete Documentation Setup
208 |
209 | ```
210 | 1. "Analyze my repository for documentation needs"
211 | 2. "Recommend the best static site generator for my project"
212 | 3. "Generate configuration files for the recommended SSG"
213 | 4. "Set up Diataxis-compliant documentation structure"
214 | 5. "Deploy everything to GitHub Pages"
215 | ```
216 |
217 | ### Documentation Audit
218 |
219 | ```
220 | 1. "Analyze my existing documentation"
221 | 2. "What gaps do you see in my current docs?"
222 | 3. "How can I improve my documentation structure?"
223 | ```
224 |
225 | ### Deployment Troubleshooting
226 |
227 | ```
228 | 1. "My GitHub Pages site isn't working"
229 | 2. "Check my deployment configuration"
230 | 3. "Help me fix the build errors"
231 | ```
232 |
233 | ## Memory and Context
234 |
235 | DocuMCP remembers context within a conversation, so you can:
236 |
237 | - Reference previous analysis results
238 | - Build on earlier recommendations
239 | - Chain operations together seamlessly
240 |
241 | Example conversation flow:
242 |
243 | ```
244 | User: "analyze my repository"
245 | DocuMCP: [provides analysis]
246 | User: "based on that analysis, what SSG do you recommend?"
247 | DocuMCP: [provides recommendation using analysis context]
248 | User: "set it up with that recommendation"
249 | DocuMCP: [configures the recommended SSG]
250 | ```
251 |
252 | ## Troubleshooting Prompts
253 |
254 | If you're not getting the results you expect, try:
255 |
256 | ### More Specific Prompts
257 |
258 | Instead of: "help with docs"
259 | Try: "analyze my TypeScript project and recommend documentation tools"
260 |
261 | ### Context Setting
262 |
263 | Instead of: "set up deployment"
264 | Try: "set up GitHub Pages deployment for the MkDocs site we just configured"
265 |
266 | ### Direct Tool Requests
267 |
268 | If you know exactly what you want:
269 |
270 | - "use the analyze_repository tool on my current directory"
271 | - "run the recommend_ssg tool with my project data"
272 |
273 | ## Getting Help
274 |
275 | If you need assistance with prompting:
276 |
277 | - Ask DocuMCP to explain available tools: "what can you help me with?"
278 | - Request examples: "show me example prompts for documentation setup"
279 | - Ask for clarification: "I don't understand the recommendation, can you explain?"
280 |
281 | Remember: DocuMCP is designed to understand natural language, so don't hesitate to ask questions in your own words!
282 |
```
--------------------------------------------------------------------------------
/docs/tutorials/memory-workflows.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.973Z"
4 | last_validated: "2025-11-20T00:46:21.973Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Memory Workflows and Advanced Features
10 |
11 | This tutorial covers DocuMCP's memory system and advanced workflow features for intelligent documentation management.
12 |
13 | ## Overview
14 |
15 | DocuMCP includes a sophisticated memory system that learns from your documentation patterns and provides intelligent assistance:
16 |
17 | ### Memory System Features
18 |
19 | - **Historical Analysis**: Learns from past documentation projects
20 | - **User Preferences**: Adapts to your documentation style
21 | - **Pattern Recognition**: Identifies successful documentation patterns
22 | - **Smart Recommendations**: Provides context-aware suggestions
23 |
24 | ### Advanced Workflows
25 |
26 | - **Multi-Project Memory**: Share insights across projects
27 | - **Collaborative Learning**: Learn from team documentation patterns
28 | - **Automated Optimization**: Continuously improve documentation quality
29 |
30 | ## Getting Started with Memory
31 |
32 | ### Initial Setup
33 |
34 | ```bash
35 | # Initialize memory system:
36 | "initialize memory system for my documentation workflow"
37 | ```
38 |
39 | ### Basic Memory Operations
40 |
41 | ```bash
42 | # Store analysis results:
43 | "store this analysis in memory for future reference"
44 |
45 | # Recall similar projects:
46 | "find similar projects in my memory"
47 |
48 | # Update preferences:
49 | "update my documentation preferences based on this project"
50 | ```
51 |
52 | ## Memory System Architecture
53 |
54 | ### Memory Components
55 |
56 | 1. **Analysis Memory**: Stores repository analysis results
57 | 2. **Recommendation Memory**: Tracks SSG recommendation patterns
58 | 3. **Deployment Memory**: Records deployment success patterns
59 | 4. **User Preference Memory**: Learns individual preferences
60 |
61 | ### Memory Storage
62 |
63 | ```yaml
64 | # Memory configuration
65 | memory:
66 | storage_path: ".documcp/memory"
67 | retention_policy: "keep_all"
68 | backup_enabled: true
69 | compression: true
70 | ```
71 |
72 | ## Advanced Memory Features
73 |
74 | ### Contextual Retrieval
75 |
76 | ```bash
77 | # Find relevant memories:
78 | "find memories related to TypeScript documentation projects"
79 |
80 | # Get contextual suggestions:
81 | "get suggestions based on my previous documentation patterns"
82 | ```
83 |
84 | ### Pattern Learning
85 |
86 | ```bash
87 | # Learn from successful deployments:
88 | "learn from successful documentation deployments"
89 |
90 | # Identify patterns:
91 | "identify successful documentation patterns in my memory"
92 | ```
93 |
94 | ### Collaborative Memory
95 |
96 | ```bash
97 | # Share memories with team:
98 | "share documentation patterns with my team"
99 |
100 | # Import team memories:
101 | "import documentation patterns from team members"
102 | ```
103 |
104 | ## Memory Workflow Examples
105 |
106 | ### Project Analysis Workflow
107 |
108 | ```bash
109 | # Complete analysis with memory integration:
110 | "analyze my repository and store results in memory for future reference"
111 | ```
112 |
113 | This workflow:
114 |
115 | 1. Analyzes the current repository
116 | 2. Compares with similar projects in memory
117 | 3. Provides enhanced recommendations
118 | 4. Stores results for future reference
119 |
120 | ### Recommendation Workflow
121 |
122 | ```bash
123 | # Get memory-enhanced recommendations:
124 | "recommend SSG based on my memory and current project"
125 | ```
126 |
127 | This workflow:
128 |
129 | 1. Retrieves relevant memories
130 | 2. Applies learned patterns
131 | 3. Provides personalized recommendations
132 | 4. Updates memory with results
133 |
134 | ### Deployment Workflow
135 |
136 | ```bash
137 | # Deploy with memory insights:
138 | "deploy documentation using insights from my memory"
139 | ```
140 |
141 | This workflow:
142 |
143 | 1. Applies learned deployment patterns
144 | 2. Uses successful configuration templates
145 | 3. Monitors for known issues
146 | 4. Records results for future learning
147 |
148 | ## Memory Management
149 |
150 | ### Memory Operations
151 |
152 | ```bash
153 | # List all memories:
154 | "list all memories in my system"
155 |
156 | # Search memories:
157 | "search memories for 'React documentation'"
158 |
159 | # Export memories:
160 | "export my documentation memories"
161 |
162 | # Import memories:
163 | "import documentation memories from file"
164 | ```
165 |
166 | ### Memory Optimization
167 |
168 | ```bash
169 | # Optimize memory storage:
170 | "optimize memory storage and remove duplicates"
171 |
172 | # Clean up old memories:
173 | "clean up memories older than 6 months"
174 |
175 | # Compress memory:
176 | "compress memory storage for efficiency"
177 | ```
178 |
179 | ## Advanced Workflow Patterns
180 |
181 | ### Multi-Project Memory Sharing
182 |
183 | ```bash
184 | # Set up project memory sharing:
185 | "set up memory sharing between my projects"
186 | ```
187 |
188 | ### Team Collaboration
189 |
190 | ```bash
191 | # Enable team memory sharing:
192 | "enable team memory sharing for documentation patterns"
193 | ```
194 |
195 | ### Automated Learning
196 |
197 | ```bash
198 | # Enable automated learning:
199 | "enable automated learning from documentation patterns"
200 | ```
201 |
202 | ## Memory Analytics
203 |
204 | ### Memory Insights
205 |
206 | ```bash
207 | # Get memory insights:
208 | "provide insights from my documentation memory"
209 | ```
210 |
211 | ### Success Pattern Analysis
212 |
213 | ```bash
214 | # Analyze success patterns:
215 | "analyze successful documentation patterns in my memory"
216 | ```
217 |
218 | ### Performance Tracking
219 |
220 | ```bash
221 | # Track memory performance:
222 | "track performance of memory-enhanced recommendations"
223 | ```
224 |
225 | ## Troubleshooting Memory Issues
226 |
227 | ### Common Problems
228 |
229 | **Problem**: Memory not loading
230 | **Solution**: Check memory file permissions and integrity
231 |
232 | **Problem**: Slow memory operations
233 | **Solution**: Optimize memory storage and clean up old data
234 |
235 | **Problem**: Inconsistent recommendations
236 | **Solution**: Review memory data quality and patterns
237 |
238 | ### Memory Debugging
239 |
240 | ```bash
241 | # Debug memory issues:
242 | "debug memory system problems"
243 |
244 | # Validate memory integrity:
245 | "validate memory data integrity"
246 |
247 | # Reset memory system:
248 | "reset memory system to defaults"
249 | ```
250 |
251 | ## Best Practices
252 |
253 | ### Memory Management
254 |
255 | 1. **Regular Backups**: Backup memory data regularly
256 | 2. **Quality Control**: Review and clean memory data
257 | 3. **Privacy**: Be mindful of sensitive data in memories
258 | 4. **Performance**: Monitor memory system performance
259 | 5. **Documentation**: Document your memory workflows
260 |
261 | ### Workflow Optimization
262 |
263 | 1. **Consistent Patterns**: Use consistent documentation patterns
264 | 2. **Regular Updates**: Update memory with new learnings
265 | 3. **Team Sharing**: Share successful patterns with team
266 | 4. **Continuous Learning**: Enable continuous learning features
267 | 5. **Performance Monitoring**: Monitor workflow performance
268 |
269 | ## Memory System Integration
270 |
271 | ### With Documentation Tools
272 |
273 | - **Repository Analysis**: Enhanced with historical data
274 | - **SSG Recommendations**: Improved with pattern learning
275 | - **Deployment Automation**: Optimized with success patterns
276 | - **Content Generation**: Informed by previous content
277 |
278 | ### With External Systems
279 |
280 | - **CI/CD Integration**: Memory-aware deployment pipelines
281 | - **Analytics Integration**: Memory-enhanced performance tracking
282 | - **Team Tools**: Collaborative memory sharing
283 | - **Backup Systems**: Automated memory backup
284 |
285 | ## Advanced Configuration
286 |
287 | ### Memory Configuration
288 |
289 | ```yaml
290 | # Advanced memory configuration
291 | memory:
292 | storage:
293 | type: "local"
294 | path: ".documcp/memory"
295 | encryption: true
296 |
297 | learning:
298 | enabled: true
299 | auto_update: true
300 | pattern_detection: true
301 |
302 | sharing:
303 | team_enabled: false
304 | project_sharing: true
305 | export_format: "json"
306 | ```
307 |
308 | ### Performance Tuning
309 |
310 | ```bash
311 | # Tune memory performance:
312 | "optimize memory system performance"
313 | ```
314 |
315 | ## Next Steps
316 |
317 | - [How-to Guides](../how-to/)
318 | - [Reference Documentation](../reference/)
319 | - [Architecture Explanation](../explanation/)
320 | - [Advanced Configuration](../reference/configuration.md)
321 |
```
--------------------------------------------------------------------------------
/docs/how-to/documentation-freshness-tracking.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.950Z"
4 | last_validated: "2025-11-20T00:46:21.950Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Track Documentation Freshness
10 |
11 | This guide shows you how to use DocuMCP's documentation freshness tracking system to monitor and maintain up-to-date documentation.
12 |
13 | ## Quick Start
14 |
15 | ```bash
16 | # Initialize freshness tracking:
17 | "validate documentation freshness for my docs directory"
18 |
19 | # Check freshness status:
20 | "track documentation freshness"
21 | ```
22 |
23 | ## Overview
24 |
25 | Documentation freshness tracking helps you:
26 |
27 | - **Identify stale documentation**: Find files that haven't been updated recently
28 | - **Maintain quality**: Ensure documentation stays current with code changes
29 | - **Track history**: Monitor documentation updates over time via knowledge graph integration
30 | - **Automate maintenance**: Set up workflows for regular freshness checks
31 |
32 | ## Initial Setup
33 |
34 | ### Step 1: Initialize Freshness Metadata
35 |
36 | Before tracking freshness, you need to initialize metadata for your documentation files:
37 |
38 | ```json
39 | {
40 | "docsPath": "/path/to/docs",
41 | "projectPath": "/path/to/project",
42 | "initializeMissing": true,
43 | "validateAgainstGit": true
44 | }
45 | ```
46 |
47 | This will:
48 |
49 | - Create freshness metadata for all documentation files
50 | - Set initial timestamps based on file modification dates
51 | - Link metadata to git history (if available)
52 |
53 | ### Step 2: Verify Initialization
54 |
55 | Check that metadata was created successfully:
56 |
57 | ```bash
58 | # Track freshness to see initialized files:
59 | "track documentation freshness for my docs"
60 | ```
61 |
62 | You should see all files marked as "fresh" initially.
63 |
64 | ## Regular Freshness Checks
65 |
66 | ### Basic Tracking
67 |
68 | Run regular freshness checks to monitor documentation staleness:
69 |
70 | ```json
71 | {
72 | "docsPath": "/path/to/docs",
73 | "includeFileList": true
74 | }
75 | ```
76 |
77 | ### Using Presets
78 |
79 | DocuMCP provides convenient presets for different update frequencies:
80 |
81 | - **realtime**: For documentation that changes frequently (minutes/hours)
82 | - **active**: For actively maintained docs (days)
83 | - **recent**: For recently updated docs (weeks)
84 | - **weekly**: For weekly review cycles
85 | - **monthly**: For monthly maintenance (default)
86 | - **quarterly**: For quarterly reviews
87 |
88 | ```json
89 | {
90 | "docsPath": "/path/to/docs",
91 | "preset": "monthly"
92 | }
93 | ```
94 |
95 | ### Custom Thresholds
96 |
97 | Define your own staleness thresholds:
98 |
99 | ```json
100 | {
101 | "docsPath": "/path/to/docs",
102 | "warningThreshold": {
103 | "value": 7,
104 | "unit": "days"
105 | },
106 | "staleThreshold": {
107 | "value": 30,
108 | "unit": "days"
109 | },
110 | "criticalThreshold": {
111 | "value": 90,
112 | "unit": "days"
113 | }
114 | }
115 | ```
116 |
117 | ## Understanding Freshness Levels
118 |
119 | ### Fresh ✅
120 |
121 | Files updated within the warning threshold (default: 7 days)
122 |
123 | ### Warning 🟡
124 |
125 | Files older than warning threshold but newer than stale threshold (7-30 days)
126 |
127 | ### Stale 🟠
128 |
129 | Files older than stale threshold but newer than critical threshold (30-90 days)
130 |
131 | ### Critical 🔴
132 |
133 | Files older than critical threshold (90+ days)
134 |
135 | ### Unknown ❓
136 |
137 | Files without freshness metadata (need initialization)
138 |
139 | ## Workflow Examples
140 |
141 | ### Weekly Documentation Review
142 |
143 | ```bash
144 | # 1. Check freshness status
145 | "track documentation freshness with preset weekly"
146 |
147 | # 2. Review stale files and update as needed
148 | # (manually update documentation)
149 |
150 | # 3. Validate freshness after updates
151 | "validate documentation freshness and update existing metadata"
152 | ```
153 |
154 | ### After Major Code Changes
155 |
156 | ```bash
157 | # 1. Update documentation to reflect code changes
158 | # (manually update files)
159 |
160 | # 2. Validate freshness against git
161 | "validate documentation freshness with git validation"
162 |
163 | # 3. Track updated status
164 | "track documentation freshness"
165 | ```
166 |
167 | ### Automated CI/CD Integration
168 |
169 | Add freshness checks to your CI/CD pipeline:
170 |
171 | ```yaml
172 | # .github/workflows/docs-freshness.yml
173 | - name: Check Documentation Freshness
174 | run: |
175 | documcp track_documentation_freshness \
176 | --docsPath ./docs \
177 | --preset monthly \
178 | --failOnStale true
179 | ```
180 |
181 | ## Advanced Usage
182 |
183 | ### Knowledge Graph Integration
184 |
185 | Freshness tracking events are automatically stored in the knowledge graph:
186 |
187 | ```json
188 | {
189 | "docsPath": "/path/to/docs",
190 | "projectPath": "/path/to/project",
191 | "storeInKG": true
192 | }
193 | ```
194 |
195 | This enables:
196 |
197 | - Historical analysis of documentation updates
198 | - Pattern recognition across projects
199 | - Intelligent recommendations based on past behavior
200 |
201 | ### Sorting and Filtering
202 |
203 | Customize how files are displayed:
204 |
205 | ```json
206 | {
207 | "docsPath": "/path/to/docs",
208 | "sortBy": "staleness", // Options: "age", "path", "staleness"
209 | "includeFileList": true
210 | }
211 | ```
212 |
213 | ### Git Integration
214 |
215 | Validate freshness against git history:
216 |
217 | ```json
218 | {
219 | "docsPath": "/path/to/docs",
220 | "projectPath": "/path/to/project",
221 | "validateAgainstGit": true
222 | }
223 | ```
224 |
225 | This compares file modification times with git commit history for more accurate staleness detection.
226 |
227 | ## Best Practices
228 |
229 | ### 1. Initialize Early
230 |
231 | Set up freshness tracking when you first create documentation:
232 |
233 | ```bash
234 | "initialize freshness tracking for my new documentation"
235 | ```
236 |
237 | ### 2. Regular Checks
238 |
239 | Schedule regular freshness checks:
240 |
241 | - Weekly for active projects
242 | - Monthly for stable projects
243 | - Quarterly for archived documentation
244 |
245 | ### 3. Update Thresholds
246 |
247 | Adjust thresholds based on your project's update frequency:
248 |
249 | - Active projects: 7/30/90 days
250 | - Stable projects: 30/90/180 days
251 | - Archived docs: 90/180/365 days
252 |
253 | ### 4. Integrate with Workflows
254 |
255 | Combine freshness tracking with other DocuMCP tools:
256 |
257 | ```bash
258 | # Check freshness → Update stale docs → Validate → Deploy
259 | "track documentation freshness, then update stale files, validate, and deploy"
260 | ```
261 |
262 | ### 5. Monitor Trends
263 |
264 | Use knowledge graph insights to identify patterns:
265 |
266 | ```bash
267 | # Get freshness insights from knowledge graph
268 | "get insights about documentation freshness trends"
269 | ```
270 |
271 | ## Troubleshooting
272 |
273 | ### Problem: All files show as "unknown"
274 |
275 | **Solution**: Run `validate_documentation_freshness` with `initializeMissing: true`
276 |
277 | ### Problem: Freshness not updating after file changes
278 |
279 | **Solution**: Run `validate_documentation_freshness` with `updateExisting: true`
280 |
281 | ### Problem: Git validation failing
282 |
283 | **Solution**: Ensure `projectPath` points to git repository root and git is initialized
284 |
285 | ### Problem: Thresholds not working as expected
286 |
287 | **Solution**: Check that threshold values are positive numbers and units match your needs
288 |
289 | ## Integration with Other Tools
290 |
291 | ### With Sitemap Management
292 |
293 | ```bash
294 | # Track freshness → Generate sitemap → Deploy
295 | "track documentation freshness, then generate sitemap and deploy"
296 | ```
297 |
298 | ### With Content Validation
299 |
300 | ```bash
301 | # Validate freshness → Validate content → Check links
302 | "validate documentation freshness, then validate content and check links"
303 | ```
304 |
305 | ### With Gap Detection
306 |
307 | ```bash
308 | # Detect gaps → Track freshness → Update documentation
309 | "detect documentation gaps, track freshness, and update stale files"
310 | ```
311 |
312 | ## Next Steps
313 |
314 | - [Site Monitoring](site-monitoring.md) - Monitor your documentation site health
315 | - [SEO Optimization](seo-optimization.md) - Improve search engine visibility
316 | - [Performance Optimization](performance-optimization.md) - Optimize documentation performance
317 | - [MCP Tools Reference](../reference/mcp-tools.md#documentation-freshness-tracking-tools) - Complete API reference
318 |
```
--------------------------------------------------------------------------------
/tests/memory/learning.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Basic unit tests for Incremental Learning System
3 | * Tests basic instantiation and core functionality
4 | * Part of Issue #54 - Core Memory System Unit Tests
5 | */
6 |
7 | import { promises as fs } from "fs";
8 | import path from "path";
9 | import os from "os";
10 | import { MemoryManager } from "../../src/memory/manager.js";
11 | import {
12 | IncrementalLearningSystem,
13 | ProjectFeatures,
14 | } from "../../src/memory/learning.js";
15 |
16 | describe("IncrementalLearningSystem", () => {
17 | let tempDir: string;
18 | let memoryManager: MemoryManager;
19 | let learning: IncrementalLearningSystem;
20 |
21 | beforeEach(async () => {
22 | // Create unique temp directory for each test
23 | tempDir = path.join(
24 | os.tmpdir(),
25 | `memory-learning-test-${Date.now()}-${Math.random()
26 | .toString(36)
27 | .substr(2, 9)}`,
28 | );
29 | await fs.mkdir(tempDir, { recursive: true });
30 |
31 | // Create memory manager for learning system
32 | memoryManager = new MemoryManager(tempDir);
33 | await memoryManager.initialize();
34 |
35 | learning = new IncrementalLearningSystem(memoryManager);
36 | await learning.initialize();
37 | });
38 |
39 | afterEach(async () => {
40 | // Cleanup temp directory
41 | try {
42 | await fs.rm(tempDir, { recursive: true, force: true });
43 | } catch (error) {
44 | // Ignore cleanup errors
45 | }
46 | });
47 |
48 | describe("Basic Learning System Tests", () => {
49 | test("should create learning system instance", () => {
50 | expect(learning).toBeDefined();
51 | expect(learning).toBeInstanceOf(IncrementalLearningSystem);
52 | });
53 |
54 | test("should be able to enable and disable learning", () => {
55 | learning.setLearningEnabled(false);
56 | learning.setLearningEnabled(true);
57 | // Just test that the methods exist and don't throw
58 | expect(true).toBe(true);
59 | });
60 |
61 | test("should have pattern retrieval capabilities", async () => {
62 | // Test pattern retrieval without throwing errors
63 | const patterns = await learning.getPatterns();
64 | expect(Array.isArray(patterns)).toBe(true);
65 | });
66 |
67 | test("should provide learning statistics", async () => {
68 | const stats = await learning.getStatistics();
69 | expect(stats).toBeDefined();
70 | expect(typeof stats.totalPatterns).toBe("number");
71 | expect(typeof stats.averageConfidence).toBe("number");
72 | expect(Array.isArray(stats.insights)).toBe(true);
73 | });
74 |
75 | test("should handle clearing patterns", async () => {
76 | await learning.clearPatterns();
77 | // Verify patterns are cleared
78 | const patterns = await learning.getPatterns();
79 | expect(Array.isArray(patterns)).toBe(true);
80 | expect(patterns.length).toBe(0);
81 | });
82 |
83 | test("should provide improved recommendations", async () => {
84 | const projectFeatures: ProjectFeatures = {
85 | language: "typescript",
86 | framework: "react",
87 | size: "medium" as const,
88 | complexity: "moderate" as const,
89 | hasTests: true,
90 | hasCI: true,
91 | hasDocs: false,
92 | isOpenSource: true,
93 | };
94 |
95 | const baseRecommendation = {
96 | recommended: "docusaurus",
97 | confidence: 0.8,
98 | score: 0.85,
99 | };
100 |
101 | const improved = await learning.getImprovedRecommendation(
102 | projectFeatures,
103 | baseRecommendation,
104 | );
105 | expect(improved).toBeDefined();
106 | expect(improved.recommendation).toBeDefined();
107 | expect(typeof improved.confidence).toBe("number");
108 | expect(Array.isArray(improved.insights)).toBe(true);
109 | });
110 |
111 | test("should handle learning from memory entries", async () => {
112 | const memoryEntry = await memoryManager.remember(
113 | "recommendation",
114 | {
115 | recommended: "docusaurus",
116 | confidence: 0.9,
117 | language: { primary: "typescript" },
118 | framework: { name: "react" },
119 | },
120 | {
121 | projectId: "test-project",
122 | ssg: "docusaurus",
123 | },
124 | );
125 |
126 | // Learn from successful outcome
127 | await learning.learn(memoryEntry, "success");
128 | // Verify no errors thrown
129 | expect(true).toBe(true);
130 | });
131 | });
132 |
133 | describe("Learning Statistics and Analysis", () => {
134 | test("should provide comprehensive learning statistics", async () => {
135 | const stats = await learning.getStatistics();
136 | expect(stats).toBeDefined();
137 | expect(typeof stats.totalPatterns).toBe("number");
138 | expect(typeof stats.averageConfidence).toBe("number");
139 | expect(typeof stats.learningVelocity).toBe("number");
140 | expect(typeof stats.patternsByType).toBe("object");
141 | expect(Array.isArray(stats.insights)).toBe(true);
142 | });
143 |
144 | test("should handle multiple learning iterations", async () => {
145 | const projectFeatures: ProjectFeatures = {
146 | language: "javascript",
147 | framework: "vue",
148 | size: "small" as const,
149 | complexity: "simple" as const,
150 | hasTests: false,
151 | hasCI: false,
152 | hasDocs: true,
153 | isOpenSource: false,
154 | };
155 |
156 | const baseRecommendation = {
157 | recommended: "vuepress",
158 | confidence: 0.7,
159 | score: 0.75,
160 | };
161 |
162 | // Multiple learning cycles
163 | for (let i = 0; i < 3; i++) {
164 | const improved = await learning.getImprovedRecommendation(
165 | projectFeatures,
166 | baseRecommendation,
167 | );
168 | expect(improved.recommendation).toBeDefined();
169 | }
170 |
171 | expect(true).toBe(true);
172 | });
173 | });
174 |
175 | describe("Error Handling", () => {
176 | test("should handle empty patterns gracefully", async () => {
177 | // Clear all patterns first
178 | await learning.clearPatterns();
179 |
180 | const patterns = await learning.getPatterns();
181 | expect(Array.isArray(patterns)).toBe(true);
182 | expect(patterns.length).toBe(0);
183 | });
184 |
185 | test("should handle learning with minimal data", async () => {
186 | const projectFeatures: ProjectFeatures = {
187 | language: "unknown",
188 | size: "small" as const,
189 | complexity: "simple" as const,
190 | hasTests: false,
191 | hasCI: false,
192 | hasDocs: false,
193 | isOpenSource: false,
194 | };
195 |
196 | const baseRecommendation = {
197 | recommended: "jekyll",
198 | confidence: 0.5,
199 | };
200 |
201 | const improved = await learning.getImprovedRecommendation(
202 | projectFeatures,
203 | baseRecommendation,
204 | );
205 | expect(improved).toBeDefined();
206 | expect(improved.recommendation).toBeDefined();
207 | });
208 |
209 | test("should handle concurrent learning operations", async () => {
210 | const promises = Array.from({ length: 3 }, async (_, i) => {
211 | const projectFeatures: ProjectFeatures = {
212 | language: "go",
213 | size: "medium" as const,
214 | complexity: "moderate" as const,
215 | hasTests: true,
216 | hasCI: true,
217 | hasDocs: true,
218 | isOpenSource: true,
219 | };
220 |
221 | const baseRecommendation = {
222 | recommended: "hugo",
223 | confidence: 0.8 + i * 0.02,
224 | };
225 |
226 | return learning.getImprovedRecommendation(
227 | projectFeatures,
228 | baseRecommendation,
229 | );
230 | });
231 |
232 | const results = await Promise.all(promises);
233 | expect(results.length).toBe(3);
234 | results.forEach((result) => {
235 | expect(result.recommendation).toBeDefined();
236 | });
237 | });
238 | });
239 | });
240 |
```
--------------------------------------------------------------------------------
/docs/how-to/analytics-setup.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.949Z"
4 | last_validated: "2025-11-20T00:46:21.949Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Use DocuMCP Deployment Analytics
10 |
11 | This guide shows you how to access and use DocuMCP's built-in deployment analytics to track your documentation deployment success and patterns.
12 |
13 | ## Quick Setup
14 |
15 | ```bash
16 | # Analyze deployment patterns:
17 | "analyze my deployment history and provide insights"
18 | ```
19 |
20 | ## Analytics Overview
21 |
22 | DocuMCP provides comprehensive **deployment analytics** to help you understand and optimize your documentation deployment process:
23 |
24 | ### Analytics Types
25 |
26 | - **Deployment Success Tracking**: Monitor deployment success/failure rates
27 | - **SSG Performance Analytics**: Compare static site generator effectiveness
28 | - **Build Time Metrics**: Track deployment speed and optimization opportunities
29 | - **Project Pattern Analysis**: Understand which configurations work best
30 |
31 | ### Built-in Analytics Features
32 |
33 | - **Deployment Health Scoring**: 0-100 health score for your deployment pipeline
34 | - **SSG Comparison**: Compare success rates across different static site generators
35 | - **Trend Analysis**: Track deployment patterns over time
36 | - **Knowledge Graph Integration**: Learn from deployment history for better recommendations
37 |
38 | ## Using Deployment Analytics
39 |
40 | ### Method 1: Generate Full Analytics Report
41 |
42 | ```bash
43 | # Get comprehensive deployment analytics:
44 | "analyze my deployments and provide a full report"
45 | ```
46 |
47 | This will provide:
48 |
49 | 1. Overall deployment success rates
50 | 2. SSG performance comparison
51 | 3. Build time analysis
52 | 4. Project pattern insights
53 | 5. Recommendations for optimization
54 |
55 | ### Method 2: Specific Analytics Queries
56 |
57 | #### Get SSG Statistics
58 |
59 | ```bash
60 | # Analyze specific SSG performance:
61 | "show me statistics for Docusaurus deployments"
62 | ```
63 |
64 | #### Compare SSG Performance
65 |
66 | ```bash
67 | # Compare multiple SSGs:
68 | "compare deployment success rates between Hugo and Jekyll"
69 | ```
70 |
71 | #### Get Deployment Health Score
72 |
73 | ```bash
74 | # Check deployment pipeline health:
75 | "what is my deployment health score?"
76 | ```
77 |
78 | #### Analyze Deployment Trends
79 |
80 | ```bash
81 | # View deployment trends over time:
82 | "show me deployment trends for the last 30 days"
83 | ```
84 |
85 | ## Deployment Analytics Examples
86 |
87 | ### Sample Analytics Report
88 |
89 | ```typescript
90 | // Example deployment analytics report structure
91 | {
92 | "summary": {
93 | "totalProjects": 15,
94 | "totalDeployments": 42,
95 | "overallSuccessRate": 0.85,
96 | "mostUsedSSG": "docusaurus",
97 | "mostSuccessfulSSG": "hugo"
98 | },
99 | "patterns": [
100 | {
101 | "ssg": "docusaurus",
102 | "totalDeployments": 18,
103 | "successfulDeployments": 16,
104 | "failedDeployments": 2,
105 | "successRate": 0.89,
106 | "averageBuildTime": 45000,
107 | "projectCount": 8
108 | }
109 | ],
110 | "insights": [
111 | {
112 | "type": "success",
113 | "title": "High Success Rate",
114 | "description": "Excellent! 85% of deployments succeed"
115 | }
116 | ]
117 | }
118 | ```
119 |
120 | ### Health Score Breakdown
121 |
122 | ```typescript
123 | // Example health score analysis
124 | {
125 | "score": 78,
126 | "factors": [
127 | {
128 | "name": "Overall Success Rate",
129 | "impact": 34,
130 | "status": "good"
131 | },
132 | {
133 | "name": "Active Projects",
134 | "impact": 20,
135 | "status": "good"
136 | },
137 | {
138 | "name": "Deployment Activity",
139 | "impact": 15,
140 | "status": "warning"
141 | },
142 | {
143 | "name": "SSG Diversity",
144 | "impact": 9,
145 | "status": "warning"
146 | }
147 | ]
148 | }
149 | ```
150 |
151 | ### MCP Tool Integration
152 |
153 | ```typescript
154 | // Using the analyze_deployments MCP tool directly
155 | import { analyzeDeployments } from "./dist/tools/analyze-deployments.js";
156 |
157 | // Get full analytics report
158 | const report = await analyzeDeployments({
159 | analysisType: "full_report",
160 | });
161 |
162 | // Get specific SSG statistics
163 | const docusaurusStats = await analyzeDeployments({
164 | analysisType: "ssg_stats",
165 | ssg: "docusaurus",
166 | });
167 |
168 | // Compare multiple SSGs
169 | const comparison = await analyzeDeployments({
170 | analysisType: "compare",
171 | ssgs: ["hugo", "jekyll", "docusaurus"],
172 | });
173 |
174 | // Get deployment health score
175 | const health = await analyzeDeployments({
176 | analysisType: "health",
177 | });
178 | ```
179 |
180 | ## Advanced Deployment Analytics
181 |
182 | ### Deployment Pattern Analysis
183 |
184 | ```bash
185 | # Analyze deployment patterns by technology:
186 | "show me deployment success patterns for TypeScript projects"
187 |
188 | # Analyze by project size:
189 | "compare deployment success rates for small vs large projects"
190 |
191 | # Analyze by team size:
192 | "show deployment patterns for different team sizes"
193 | ```
194 |
195 | ### Knowledge Graph Insights
196 |
197 | ```bash
198 | # Get insights from deployment history:
199 | "what SSG works best for React projects based on deployment history?"
200 |
201 | # Learn from similar projects:
202 | "recommend deployment strategy based on similar successful projects"
203 |
204 | # Analyze failure patterns:
205 | "what are the common causes of deployment failures?"
206 | ```
207 |
208 | ### Trend Analysis
209 |
210 | ```bash
211 | # Analyze deployment trends:
212 | "show me deployment success trends over the last 6 months"
213 |
214 | # Compare time periods:
215 | "compare deployment performance between Q3 and Q4"
216 |
217 | # Identify improvement opportunities:
218 | "what deployment metrics have improved recently?"
219 | ```
220 |
221 | ## Troubleshooting
222 |
223 | ### Common Issues
224 |
225 | **Problem**: No deployment data available
226 | **Solution**: Deploy at least one project to start collecting analytics data
227 |
228 | **Problem**: Analytics tool returns empty results
229 | **Solution**: Ensure knowledge graph storage directory exists and has proper permissions
230 |
231 | **Problem**: Health score seems low
232 | **Solution**: Review deployment failures and optimize SSG configurations
233 |
234 | **Problem**: Missing deployment history
235 | **Solution**: Check that deployment tracking is enabled in knowledge graph
236 |
237 | ### Analytics Debugging
238 |
239 | ```bash
240 | # Debug deployment analytics issues:
241 | "check my deployment analytics configuration and data availability"
242 | ```
243 |
244 | ## Best Practices
245 |
246 | ### Deployment Analytics Guidelines
247 |
248 | 1. **Regular Deployments**: Deploy frequently to build meaningful analytics data
249 | 2. **Track Failures**: Learn from deployment failures to improve success rates
250 | 3. **Monitor Trends**: Review analytics weekly to identify patterns
251 | 4. **Compare SSGs**: Use analytics to choose the best SSG for each project type
252 | 5. **Health Monitoring**: Keep deployment health score above 70
253 |
254 | ### Data Quality
255 |
256 | 1. **Consistent Tracking**: Ensure all deployments are tracked in knowledge graph
257 | 2. **Clean Data**: Review and clean up failed deployment records periodically
258 | 3. **Regular Analysis**: Run analytics reports monthly to identify trends
259 | 4. **Documentation**: Document deployment patterns and insights
260 | 5. **Team Sharing**: Share analytics insights with your development team
261 |
262 | ## Deployment Analytics Tools
263 |
264 | ### Built-in DocuMCP Analytics
265 |
266 | - **Deployment success tracking**: Monitor success/failure rates
267 | - **SSG performance analysis**: Compare static site generator effectiveness
268 | - **Build time metrics**: Track deployment speed and optimization opportunities
269 | - **Knowledge graph insights**: Learn from deployment history patterns
270 |
271 | ### MCP Tools Available
272 |
273 | - `analyze_deployments`: Generate comprehensive deployment analytics
274 | - `deploy_pages`: Track deployment attempts and outcomes
275 | - `recommend_ssg`: Get SSG recommendations based on analytics
276 |
277 | ## Next Steps
278 |
279 | - [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
280 | - [SSG Recommendations](../reference/mcp-tools.md#recommend_ssg)
281 | - [Knowledge Graph](../knowledge-graph.md)
282 | - [Troubleshooting](troubleshooting.md)
283 |
```
--------------------------------------------------------------------------------
/src/tools/verify-deployment.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { z } from "zod";
2 | import { promises as fs } from "fs";
3 | import path from "path";
4 | import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
5 |
6 | const inputSchema = z.object({
7 | repository: z.string(),
8 | url: z.string().optional(),
9 | });
10 |
11 | interface DeploymentCheck {
12 | check: string;
13 | status: "pass" | "fail" | "warning";
14 | message: string;
15 | recommendation?: string;
16 | }
17 |
18 | export async function verifyDeployment(
19 | args: unknown,
20 | ): Promise<{ content: any[] }> {
21 | const startTime = Date.now();
22 | const { repository, url } = inputSchema.parse(args);
23 |
24 | try {
25 | const checks: DeploymentCheck[] = [];
26 |
27 | // Determine repository path
28 | const repoPath = repository.startsWith("http") ? "." : repository;
29 |
30 | // Check 1: GitHub Actions workflow exists
31 | const workflowPath = path.join(repoPath, ".github", "workflows");
32 | try {
33 | const workflows = await fs.readdir(workflowPath);
34 | const deployWorkflow = workflows.find(
35 | (f) =>
36 | f.includes("deploy") || f.includes("pages") || f.includes("docs"),
37 | );
38 |
39 | if (deployWorkflow) {
40 | checks.push({
41 | check: "GitHub Actions Workflow",
42 | status: "pass",
43 | message: `Found deployment workflow: ${deployWorkflow}`,
44 | });
45 | } else {
46 | checks.push({
47 | check: "GitHub Actions Workflow",
48 | status: "fail",
49 | message: "No deployment workflow found",
50 | recommendation: "Run deploy_pages tool to create a workflow",
51 | });
52 | }
53 | } catch {
54 | checks.push({
55 | check: "GitHub Actions Workflow",
56 | status: "fail",
57 | message: "No .github/workflows directory found",
58 | recommendation: "Run deploy_pages tool to set up GitHub Actions",
59 | });
60 | }
61 |
62 | // Check 2: Documentation source files exist
63 | const docsPaths = ["docs", "documentation", "site", "content"];
64 | let docsFound = false;
65 |
66 | for (const docsPath of docsPaths) {
67 | try {
68 | const fullPath = path.join(repoPath, docsPath);
69 | const stats = await fs.stat(fullPath);
70 | if (stats.isDirectory()) {
71 | const files = await fs.readdir(fullPath);
72 | const mdFiles = files.filter(
73 | (f) => f.endsWith(".md") || f.endsWith(".mdx"),
74 | );
75 |
76 | if (mdFiles.length > 0) {
77 | docsFound = true;
78 | checks.push({
79 | check: "Documentation Source Files",
80 | status: "pass",
81 | message: `Found ${mdFiles.length} documentation files in ${docsPath}/`,
82 | });
83 | break;
84 | }
85 | }
86 | } catch {
87 | // Directory doesn't exist, continue checking
88 | }
89 | }
90 |
91 | if (!docsFound) {
92 | checks.push({
93 | check: "Documentation Source Files",
94 | status: "warning",
95 | message: "No documentation files found in standard locations",
96 | recommendation:
97 | "Run setup_structure tool to create documentation structure",
98 | });
99 | }
100 |
101 | // Check 3: Configuration files
102 | const configPatterns = [
103 | "docusaurus.config.js",
104 | "mkdocs.yml",
105 | "hugo.toml",
106 | "hugo.yaml",
107 | "_config.yml",
108 | ".eleventy.js",
109 | ];
110 |
111 | let configFound = false;
112 | for (const config of configPatterns) {
113 | try {
114 | await fs.access(path.join(repoPath, config));
115 | configFound = true;
116 | checks.push({
117 | check: "SSG Configuration",
118 | status: "pass",
119 | message: `Found configuration file: ${config}`,
120 | });
121 | break;
122 | } catch {
123 | // File doesn't exist, continue
124 | }
125 | }
126 |
127 | if (!configFound) {
128 | checks.push({
129 | check: "SSG Configuration",
130 | status: "fail",
131 | message: "No static site generator configuration found",
132 | recommendation: "Run generate_config tool to create SSG configuration",
133 | });
134 | }
135 |
136 | // Check 4: Build output directory
137 | const buildDirs = ["_site", "build", "dist", "public", "out"];
138 | let buildFound = false;
139 |
140 | for (const buildDir of buildDirs) {
141 | try {
142 | const buildPath = path.join(repoPath, buildDir);
143 | const stats = await fs.stat(buildPath);
144 | if (stats.isDirectory()) {
145 | buildFound = true;
146 | checks.push({
147 | check: "Build Output",
148 | status: "pass",
149 | message: `Found build output directory: ${buildDir}/`,
150 | });
151 | break;
152 | }
153 | } catch {
154 | // Directory doesn't exist
155 | }
156 | }
157 |
158 | if (!buildFound) {
159 | checks.push({
160 | check: "Build Output",
161 | status: "warning",
162 | message: "No build output directory found",
163 | recommendation: "Run your SSG build command to generate the site",
164 | });
165 | }
166 |
167 | // Check 5: GitHub Pages settings (if URL provided)
168 | if (url) {
169 | checks.push({
170 | check: "Deployment URL",
171 | status: "warning",
172 | message: `Expected URL: ${url}`,
173 | recommendation: "Verify GitHub Pages is enabled in repository settings",
174 | });
175 | }
176 |
177 | // Generate summary
178 | const passCount = checks.filter((c) => c.status === "pass").length;
179 | const failCount = checks.filter((c) => c.status === "fail").length;
180 | const warningCount = checks.filter((c) => c.status === "warning").length;
181 |
182 | let overallStatus = "Ready for deployment";
183 | if (failCount > 0) {
184 | overallStatus = "Configuration required";
185 | } else if (warningCount > 0) {
186 | overallStatus = "Minor issues detected";
187 | }
188 |
189 | const verificationResult = {
190 | repository,
191 | url,
192 | overallStatus,
193 | checks,
194 | summary: {
195 | passed: passCount,
196 | warnings: warningCount,
197 | failed: failCount,
198 | total: checks.length,
199 | },
200 | };
201 |
202 | const response: MCPToolResponse<typeof verificationResult> = {
203 | success: true,
204 | data: verificationResult,
205 | metadata: {
206 | toolVersion: "1.0.0",
207 | executionTime: Date.now() - startTime,
208 | timestamp: new Date().toISOString(),
209 | },
210 | recommendations: [
211 | {
212 | type:
213 | failCount > 0 ? "critical" : warningCount > 0 ? "warning" : "info",
214 | title: "Deployment Verification Complete",
215 | description: `${overallStatus}. ${passCount} checks passed, ${warningCount} warnings, ${failCount} failures.`,
216 | },
217 | ],
218 | nextSteps: checks
219 | .filter((check) => check.recommendation)
220 | .map((check) => ({
221 | action: check.recommendation!,
222 | toolRequired: check.recommendation!.includes("deploy_pages")
223 | ? "deploy_pages"
224 | : check.recommendation!.includes("setup_structure")
225 | ? "setup_structure"
226 | : check.recommendation!.includes("generate_config")
227 | ? "generate_config"
228 | : "manual",
229 | description: check.message,
230 | priority: check.status === "fail" ? "high" : ("medium" as const),
231 | })),
232 | };
233 |
234 | return formatMCPResponse(response);
235 | } catch (error) {
236 | const errorResponse: MCPToolResponse = {
237 | success: false,
238 | error: {
239 | code: "VERIFICATION_FAILED",
240 | message: `Failed to verify deployment: ${error}`,
241 | resolution: "Ensure repository path is accessible",
242 | },
243 | metadata: {
244 | toolVersion: "1.0.0",
245 | executionTime: Date.now() - startTime,
246 | timestamp: new Date().toISOString(),
247 | },
248 | };
249 | return formatMCPResponse(errorResponse);
250 | }
251 | }
252 |
253 | // Removed unused getStatusEmoji function - status indicators now handled in formatMCPResponse
254 |
```
--------------------------------------------------------------------------------
/.github/copilot-instructions.md:
--------------------------------------------------------------------------------
```markdown
1 | # DocuMCP AI Coding Agent Instructions
2 |
3 | DocuMCP is an intelligent MCP server for GitHub Pages documentation deployment with 45+ tools, Knowledge Graph memory system, and AST-based code analysis.
4 |
5 | ## Architecture Essentials
6 |
7 | ### MCP Server Design (src/index.ts)
8 |
9 | - **Stateless operation**: Each tool analyzes current state; no persistent session data
10 | - **Resource storage**: Temporary session context in `resourceStore` Map with URIs like `documcp://analysis/{id}`
11 | - **Response format**: ALL tools MUST use `formatMCPResponse()` from `src/types/api.ts` returning `MCPToolResponse`
12 | - **Memory integration**: Tools auto-store results in JSONL (`.documcp/memory/`) and query historical data
13 |
14 | ### Tool Implementation Pattern
15 |
16 | Every tool follows this structure:
17 |
18 | 1. Zod schema for input validation (e.g., `inputSchema.parse()`)
19 | 2. Business logic with error handling
20 | 3. Return via `formatMCPResponse({ success, data, metadata, recommendations?, nextSteps? })`
21 | 4. Store result as resource: `storeResourceFromToolResult(result, 'analysis', analysis.id)`
22 |
23 | **Example** (see `src/tools/analyze-repository.ts`):
24 |
25 | ```typescript
26 | const inputSchema = z.object({
27 | path: z.string(),
28 | depth: z.enum(["quick", "standard", "deep"]).optional(),
29 | });
30 | export async function analyzeRepository(
31 | args: unknown,
32 | ): Promise<MCPToolResponse> {
33 | const input = inputSchema.parse(args);
34 | // ... logic ...
35 | return formatMCPResponse({
36 | success: true,
37 | data: analysis,
38 | metadata: { toolVersion, executionTime, timestamp },
39 | });
40 | }
41 | ```
42 |
43 | ### Knowledge Graph Memory (src/memory/)
44 |
45 | - **Entities**: Project, User, Configuration, Technology, CodeFile, DocumentationSection (see `src/memory/schemas.ts`)
46 | - **Relationships**: `project_uses_technology`, `project_deployed_with`, `similar_to`, `documents`, etc.
47 | - **Storage**: `.documcp/memory/knowledge-graph-entities.jsonl` and `knowledge-graph-relationships.jsonl`
48 | - **Integration**: Use `createOrUpdateProject()`, `getProjectContext()`, `trackDeployment()` from `src/memory/kg-integration.ts`
49 |
50 | **analyze_repository enhancement**: Retrieves project history before analysis, shows previous analysis count, similar projects
51 |
52 | ## Development Workflows
53 |
54 | ### Essential Commands
55 |
56 | ```bash
57 | npm run build # Compile TypeScript → dist/
58 | npm run dev # Development watch mode with tsx
59 | npm test # Run Jest test suite
60 | npm run test:coverage # Coverage report (80% threshold)
61 | npm run build:inspect # Launch MCP Inspector for interactive testing
62 | npm run ci # Full CI pipeline: typecheck + lint + test + build
63 | make qa # Quality assurance: lint + types + test + coverage
64 | ```
65 |
66 | ### Testing Strategy
67 |
68 | - **Location**: `tests/` mirroring `src/` structure
69 | - **Coverage**: 80% global (branches/functions/lines), 60% for `recommend-ssg.ts` (complex logic)
70 | - **Excluded**: Experimental memory features, `src/index.ts` entry point
71 | - **Pattern**: Use `formatMCPResponse()` for consistent response validation
72 | - **Integration**: Multi-tool workflow tests in `tests/integration/`
73 |
74 | ### MCP Inspector Workflow
75 |
76 | 1. `npm run build:inspect` opens browser at `http://localhost:5173`
77 | 2. Click "Connect" to attach to server
78 | 3. Test tools with custom parameters interactively
79 | 4. Verify resources/prompts without full integration
80 |
81 | ## Project-Specific Conventions
82 |
83 | ### ESM Module Requirements
84 |
85 | - **ALL imports** must end with `.js` (even for `.ts` files): `import { foo } from './utils.js'`
86 | - Use `import type` for type-only imports: `import type { MyType } from './types.js'`
87 | - File URLs: `fileURLToPath(import.meta.url)` and `dirname()`
88 |
89 | ### Path & Permission Handling
90 |
91 | - **Security**: Use `isPathAllowed(path, allowedRoots)` from `src/utils/permission-checker.ts` before file operations
92 | - **Async FS**: Always use `fs.promises` API, never sync methods
93 | - **Cross-platform**: Use `path` module for joining/resolving
94 |
95 | ### Git Integration
96 |
97 | - Use `simple-git` library for repository operations
98 | - Handle missing `.git` directories gracefully (check `hasGit` flag)
99 | - Always validate repo state before analysis
100 |
101 | ### Diataxis Framework
102 |
103 | Documentation structured as:
104 |
105 | - **Tutorials**: Learning-oriented (getting started)
106 | - **How-To Guides**: Problem-solving (specific tasks)
107 | - **Reference**: Information-oriented (API docs)
108 | - **Explanation**: Understanding-oriented (architecture, concepts)
109 |
110 | Tools like `setup-structure` and `populate-content` enforce this structure.
111 |
112 | ## Critical Implementation Details
113 |
114 | ### Phase 3: AST-Based Code Analysis
115 |
116 | - **AST Parser** (`src/utils/ast-analyzer.ts`): Multi-language support via Tree-sitter (TypeScript, Python, Go, Rust, Java, Ruby, Bash)
117 | - **Drift Detection** (`src/utils/drift-detector.ts`): Snapshot-based comparison, categorizes changes (breaking/major/minor/patch)
118 | - **Sync Tool** (`src/tools/sync-code-to-docs.ts`): Modes: detect/preview/apply/auto, confidence threshold (default 0.8)
119 | - **Content Generator** (`src/tools/generate-contextual-content.ts`): Creates Diataxis-compliant docs from actual code structure
120 |
121 | **Example drift detection**:
122 |
123 | ```typescript
124 | // Detects function signature changes, new/removed classes, breaking changes
125 | const drift = await detectDrift({ projectPath, docsPath, snapshotDir });
126 | drift.affectedFiles.forEach((f) => console.log(f.driftType, f.severity));
127 | ```
128 |
129 | ### Error Handling Pattern
130 |
131 | ```typescript
132 | try {
133 | // tool logic
134 | return formatMCPResponse({ success: true, data: result, metadata });
135 | } catch (error) {
136 | return formatMCPResponse({
137 | success: false,
138 | error: {
139 | code: "TOOL_ERROR",
140 | message: error.message,
141 | resolution: "Check inputs and try again",
142 | },
143 | metadata,
144 | });
145 | }
146 | ```
147 |
148 | ### Adding New Tools Checklist
149 |
150 | 1. Create `src/tools/my-tool.ts` with Zod schema and logic
151 | 2. Export tool function returning `MCPToolResponse`
152 | 3. Add to `TOOLS` array in `src/index.ts` with name, description, inputSchema
153 | 4. Add handler in `CallToolRequestSchema` switch case
154 | 5. Store result: `storeResourceFromToolResult(result, 'type', id)`
155 | 6. Create tests: `tests/tools/my-tool.test.ts`
156 | 7. Run `npm run ci` to validate
157 |
158 | ## Key Integration Points
159 |
160 | ### Memory Query Patterns
161 |
162 | ```typescript
163 | // Query similar projects by analysis results
164 | const similar = await getSimilarProjects(analysisResult, limit);
165 |
166 | // Get project insights with historical context
167 | const insights = await getProjectInsights(projectPath);
168 |
169 | // Export/import memory for backup
170 | await exportMemories({ outputPath: "./backup.json" });
171 | await importMemories({ inputPath: "./backup.json" });
172 | ```
173 |
174 | ### Resource Storage Pattern
175 |
176 | ```typescript
177 | // Tools create resources for cross-tool reference
178 | resourceStore.set(`documcp://analysis/${id}`, {
179 | uri: `documcp://analysis/${id}`,
180 | name: `Repository Analysis ${id}`,
181 | mimeType: "application/json",
182 | text: JSON.stringify(result, null, 2),
183 | });
184 | ```
185 |
186 | ### ADR References
187 |
188 | - **ADR-001**: TypeScript MCP SDK chosen over Python/Go for ecosystem maturity
189 | - **ADR-002**: Multi-layered repository analysis (structure + dependencies + documentation)
190 | - **ADR-003**: Algorithmic SSG recommendation with confidence scoring
191 | - **ADR-006**: Consistent tool API design with Zod validation
192 | - **ADR-010**: Resource pattern redesign for session-based storage
193 |
194 | Full ADRs: `docs/adrs/`
195 |
196 | ## Common Pitfalls
197 |
198 | - ❌ Forgetting `.js` extension in imports → Module resolution fails
199 | - ❌ Using `formatMCPResponse()` incorrectly → Response validation errors
200 | - ❌ Missing Zod schema validation → Runtime type errors
201 | - ❌ Synchronous file operations → Blocking operations
202 | - ❌ Not checking path permissions → Security vulnerabilities
203 | - ❌ Returning raw objects instead of `MCPToolResponse` → Protocol violations
204 |
205 | ## Quick Reference
206 |
207 | **Node.js**: ≥20.0.0 | **Module**: ESM | **Test Framework**: Jest (ts-jest) | **Storage**: `.documcp/memory/` (JSONL)
208 | **MCP Inspector**: `npm run build:inspect` | **Full test suite**: `npm run ci` | **Docs**: `docs/` (Docusaurus)
209 |
```
--------------------------------------------------------------------------------
/docs/guides/link-validation.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.947Z"
4 | last_validated: "2025-11-20T00:46:21.947Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Link Validation in Knowledge Graph
10 |
11 | ## Overview
12 |
13 | DocuMCP now includes automatic link validation for documentation content, integrated directly into the Knowledge Graph memory system. This feature validates external links, tracks their status over time, and surfaces broken links during repository analysis.
14 |
15 | ## Architecture
16 |
17 | ### Components
18 |
19 | 1. **kg-link-validator.ts** - Core link validation module
20 | 2. **kg-code-integration.ts** - Automatic validation during doc analysis
21 | 3. **Knowledge Graph** - Stores validation results as entities
22 |
23 | ### Entity Type: `link_validation`
24 |
25 | ```typescript
26 | {
27 | totalLinks: number; // Total links found
28 | validLinks: number; // Links that returned HTTP 200
29 | brokenLinks: number; // Links that failed (404, timeout, etc.)
30 | warningLinks: number; // Links that were skipped
31 | unknownLinks: number; // Links that couldn't be validated
32 | healthScore: number; // 0-100 score based on valid/total
33 | lastValidated: string; // ISO 8601 timestamp
34 | brokenLinksList: string[]; // Array of broken link URLs
35 | }
36 | ```
37 |
38 | ### Relationships
39 |
40 | 1. **has_link_validation**: `documentation_section` → `link_validation`
41 |
42 | - Connects docs to their validation results
43 |
44 | 2. **requires_fix**: `link_validation` → `documentation_section`
45 | - Created when broken links are detected
46 | - Properties:
47 | - `severity`: "high" (>5 broken) or "medium" (1-5 broken)
48 | - `brokenLinkCount`: Number of broken links
49 | - `detectedAt`: ISO timestamp
50 |
51 | ## How It Works
52 |
53 | ### 1. Automatic Validation During Analysis
54 |
55 | When `analyze_repository` runs, it:
56 |
57 | 1. Extracts documentation content
58 | 2. Creates documentation entities in KG
59 | 3. **Automatically validates external links** (async, non-blocking)
60 | 4. Stores validation results in KG
61 |
62 | ```typescript
63 | // In kg-code-integration.ts
64 | for (const doc of extractedContent.existingDocs) {
65 | const docNode = createDocSectionEntity(
66 | projectId,
67 | doc.path,
68 | doc.title,
69 | doc.content,
70 | );
71 | kg.addNode(docNode);
72 |
73 | // Validate links in background
74 | validateAndStoreDocumentationLinks(docNode.id, doc.content).catch((error) =>
75 | console.warn(`Failed to validate links: ${error.message}`),
76 | );
77 | }
78 | ```
79 |
80 | ### 2. Link Extraction
81 |
82 | Supports both Markdown and HTML formats:
83 |
84 | ```markdown
85 | <!-- Markdown links -->
86 |
87 | [GitHub](https://github.com)
88 |
89 | <!-- HTML links -->
90 |
91 | <a href="https://example.com">Link</a>
92 | ```
93 |
94 | ### 3. Validation Strategy
95 |
96 | Uses native Node.js `fetch` API with:
97 |
98 | - **HTTP HEAD requests** (faster than GET)
99 | - **5-second timeout** (configurable)
100 | - **Retry logic** (2 retries by default)
101 | - **Concurrent checking** (up to 10 simultaneous)
102 |
103 | ```typescript
104 | const result = await validateExternalLinks(urls, {
105 | timeout: 5000, // 5 seconds
106 | retryCount: 2, // Retry failed links
107 | concurrency: 10, // Check 10 links at once
108 | });
109 | ```
110 |
111 | ### 4. Storage in Knowledge Graph
112 |
113 | Results are stored as entities and can be queried:
114 |
115 | ```typescript
116 | // Get validation history for a doc section
117 | const history = await getLinkValidationHistory(docSectionId);
118 |
119 | // Latest validation
120 | const latest = history[0];
121 | console.log(`Health Score: ${latest.properties.healthScore}%`);
122 | console.log(`Broken Links: ${latest.properties.brokenLinks}`);
123 | ```
124 |
125 | ## Usage Examples
126 |
127 | ### Query Broken Links
128 |
129 | ```typescript
130 | import { getKnowledgeGraph } from "./memory/kg-integration.js";
131 |
132 | const kg = await getKnowledgeGraph();
133 |
134 | // Find all link validation entities with broken links
135 | const allNodes = await kg.getAllNodes();
136 | const validations = allNodes.filter(
137 | (n) => n.type === "link_validation" && n.properties.brokenLinks > 0,
138 | );
139 |
140 | validations.forEach((v) => {
141 | console.log(`Found ${v.properties.brokenLinks} broken links:`);
142 | v.properties.brokenLinksList.forEach((url) => console.log(` - ${url}`));
143 | });
144 | ```
145 |
146 | ### Get Documentation Health Report
147 |
148 | ```typescript
149 | import { getKnowledgeGraph } from "./memory/kg-integration.js";
150 |
151 | const kg = await getKnowledgeGraph();
152 |
153 | // Find all documentation sections
154 | const docSections = (await kg.getAllNodes()).filter(
155 | (n) => n.type === "documentation_section",
156 | );
157 |
158 | for (const doc of docSections) {
159 | // Get validation results
160 | const edges = await kg.findEdges({
161 | source: doc.id,
162 | type: "has_link_validation",
163 | });
164 |
165 | if (edges.length > 0) {
166 | const validationId = edges[0].target;
167 | const validation = (await kg.getAllNodes()).find(
168 | (n) => n.id === validationId,
169 | );
170 |
171 | if (validation) {
172 | console.log(`\n${doc.properties.filePath}:`);
173 | console.log(` Health: ${validation.properties.healthScore}%`);
174 | console.log(` Valid: ${validation.properties.validLinks}`);
175 | console.log(` Broken: ${validation.properties.brokenLinks}`);
176 | }
177 | }
178 | }
179 | ```
180 |
181 | ### Manual Validation
182 |
183 | ```typescript
184 | import {
185 | validateExternalLinks,
186 | storeLinkValidationInKG,
187 | } from "./memory/kg-link-validator.js";
188 |
189 | // Validate specific URLs
190 | const result = await validateExternalLinks([
191 | "https://github.com",
192 | "https://example.com/404",
193 | ]);
194 |
195 | console.log(result);
196 | // {
197 | // totalLinks: 2,
198 | // validLinks: 1,
199 | // brokenLinks: 1,
200 | // results: [...]
201 | // }
202 |
203 | // Store in KG
204 | await storeLinkValidationInKG(docSectionId, result);
205 | ```
206 |
207 | ## Integration with analyze_repository
208 |
209 | The `analyze_repository` tool now includes link validation data:
210 |
211 | ```json
212 | {
213 | "success": true,
214 | "data": {
215 | "intelligentAnalysis": {
216 | "documentationHealth": {
217 | "outdatedCount": 2,
218 | "coveragePercent": 85,
219 | "totalCodeFiles": 20,
220 | "documentedFiles": 17,
221 | "linkHealth": {
222 | "totalLinks": 45,
223 | "brokenLinks": 3,
224 | "healthScore": 93
225 | }
226 | }
227 | }
228 | }
229 | }
230 | ```
231 |
232 | ## Configuration
233 |
234 | ### Environment Variables
235 |
236 | ```bash
237 | # Link validation timeout (milliseconds)
238 | DOCUMCP_LINK_TIMEOUT=5000
239 |
240 | # Maximum retries for failed links
241 | DOCUMCP_LINK_RETRIES=2
242 |
243 | # Concurrent link checks
244 | DOCUMCP_LINK_CONCURRENCY=10
245 | ```
246 |
247 | ### Skip Link Validation
248 |
249 | Link validation is non-blocking and runs in the background. If it fails, it logs a warning but doesn't stop the analysis.
250 |
251 | ## Performance Considerations
252 |
253 | 1. **Non-blocking**: Validation runs asynchronously after doc entities are created
254 | 2. **Cached Results**: Results stored in KG, no re-validation on subsequent reads
255 | 3. **Concurrent Checking**: Validates up to 10 links simultaneously
256 | 4. **Smart Timeouts**: 5-second timeout prevents hanging on slow servers
257 |
258 | ## Troubleshooting
259 |
260 | ### Links Not Being Validated
261 |
262 | **Issue**: Documentation sections have no validation results
263 |
264 | **Check**:
265 |
266 | 1. Are there external links in the content?
267 | 2. Check console for warnings: `Failed to validate links in...`
268 | 3. Verify network connectivity
269 |
270 | ### False Positives
271 |
272 | **Issue**: Valid links marked as broken
273 |
274 | **Solutions**:
275 |
276 | 1. Increase timeout: Some servers respond slowly
277 | 2. Check if server blocks HEAD requests (rare)
278 | 3. Verify URL is publicly accessible (not behind auth)
279 |
280 | ### Memory Storage Not Updated
281 |
282 | **Issue**: KG doesn't show validation results
283 |
284 | **Check**:
285 |
286 | ```typescript
287 | import { saveKnowledgeGraph } from "./memory/kg-integration.js";
288 |
289 | // Manually save KG
290 | await saveKnowledgeGraph();
291 | ```
292 |
293 | ## Future Enhancements
294 |
295 | 1. **AST-based Internal Link Validation**
296 |
297 | - Verify internal file references exist
298 | - Check anchor links (`#section-id`)
299 |
300 | 2. **Link Health Trends**
301 |
302 | - Track link health over time
303 | - Alert on degrading link quality
304 |
305 | 3. **Batch Re-validation**
306 |
307 | - MCP tool to re-check all links
308 | - Scheduled validation for long-lived projects
309 |
310 | 4. **Link Recommendation**
311 | - Suggest fixing broken links
312 | - Recommend archive.org alternatives for dead links
313 |
314 | ## Dependencies
315 |
316 | - **linkinator** (v6.1.4) - Link validation library (installed)
317 | - **native fetch** - Node.js 20+ built-in HTTP client
318 |
319 | ## Related Documentation
320 |
321 | - [Architecture Decision Records](../adrs/)
322 | - [Phase 2: Intelligence & Learning System](../phase-2-intelligence.md)
323 | - [Memory Workflows Tutorial](../tutorials/memory-workflows.md)
324 |
```
--------------------------------------------------------------------------------
/src/memory/kg-link-validator.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Knowledge Graph Link Validator
3 | * Validates external and internal links in documentation and stores results in KG
4 | */
5 |
6 | import crypto from "crypto";
7 | import { getKnowledgeGraph } from "./kg-integration.js";
8 | import { GraphNode } from "./knowledge-graph.js";
9 |
10 | export interface LinkValidationResult {
11 | url: string;
12 | status: "valid" | "broken" | "warning" | "unknown";
13 | statusCode?: number;
14 | errorMessage?: string;
15 | lastChecked: string;
16 | responseTime?: number;
17 | }
18 |
19 | export interface LinkValidationSummary {
20 | totalLinks: number;
21 | validLinks: number;
22 | brokenLinks: number;
23 | warningLinks: number;
24 | unknownLinks: number;
25 | results: LinkValidationResult[];
26 | }
27 |
28 | /**
29 | * Validate external links in documentation content
30 | */
31 | export async function validateExternalLinks(
32 | urls: string[],
33 | options?: {
34 | timeout?: number;
35 | retryCount?: number;
36 | concurrency?: number;
37 | },
38 | ): Promise<LinkValidationSummary> {
39 | const _timeout = options?.timeout || 5000;
40 | // const _retryCount = options?.retryCount || 2;
41 | // const _concurrency = options?.concurrency || 10;
42 |
43 | const results: LinkValidationResult[] = [];
44 | const summary: LinkValidationSummary = {
45 | totalLinks: urls.length,
46 | validLinks: 0,
47 | brokenLinks: 0,
48 | warningLinks: 0,
49 | unknownLinks: 0,
50 | results: [],
51 | };
52 |
53 | // Create a temporary HTML file with all links to validate
54 | // const _tempHtml = `<html><body>${urls
55 | // .map((url) => `<a href="${url}">${url}</a>`)
56 | // .join("\n")}</body></html>`;
57 |
58 | try {
59 | // Use individual validation for now (linkinator API is complex)
60 | // TODO: Optimize with linkinator's batch checking in future
61 | for (const url of urls) {
62 | try {
63 | const result = await validateSingleLink(url, _timeout);
64 | results.push(result);
65 |
66 | if (result.status === "valid") summary.validLinks++;
67 | else if (result.status === "broken") summary.brokenLinks++;
68 | else if (result.status === "warning") summary.warningLinks++;
69 | else summary.unknownLinks++;
70 | } catch {
71 | results.push({
72 | url,
73 | status: "unknown",
74 | errorMessage: "Validation failed",
75 | lastChecked: new Date().toISOString(),
76 | });
77 | summary.unknownLinks++;
78 | }
79 | }
80 | } catch (error) {
81 | console.warn("Link validation error:", error);
82 | }
83 |
84 | summary.results = results;
85 | return summary;
86 | }
87 |
88 | /**
89 | * Validate a single link with HTTP HEAD request
90 | */
91 | async function validateSingleLink(
92 | url: string,
93 | timeout: number,
94 | ): Promise<LinkValidationResult> {
95 | const startTime = Date.now();
96 |
97 | try {
98 | const controller = new AbortController();
99 | const timeoutId = setTimeout(() => controller.abort(), timeout);
100 |
101 | const response = await fetch(url, {
102 | method: "HEAD",
103 | signal: controller.signal,
104 | redirect: "follow",
105 | });
106 |
107 | clearTimeout(timeoutId);
108 |
109 | const responseTime = Date.now() - startTime;
110 |
111 | if (response.ok) {
112 | return {
113 | url,
114 | status: "valid",
115 | statusCode: response.status,
116 | lastChecked: new Date().toISOString(),
117 | responseTime,
118 | };
119 | } else {
120 | return {
121 | url,
122 | status: "broken",
123 | statusCode: response.status,
124 | errorMessage: `HTTP ${response.status}: ${response.statusText}`,
125 | lastChecked: new Date().toISOString(),
126 | responseTime,
127 | };
128 | }
129 | } catch (error: any) {
130 | return {
131 | url,
132 | status: "broken",
133 | errorMessage: error.message || "Network error",
134 | lastChecked: new Date().toISOString(),
135 | };
136 | }
137 | }
138 |
139 | /**
140 | * Store link validation results in Knowledge Graph
141 | */
142 | export async function storeLinkValidationInKG(
143 | docSectionId: string,
144 | validationSummary: LinkValidationSummary,
145 | ): Promise<void> {
146 | const kg = await getKnowledgeGraph();
147 |
148 | // Create link validation entity
149 | const validationId = `link_validation:${crypto
150 | .randomBytes(8)
151 | .toString("hex")}`;
152 |
153 | const validationNode: GraphNode = {
154 | id: validationId,
155 | type: "link_validation",
156 | label: "Link Validation Result",
157 | properties: {
158 | totalLinks: validationSummary.totalLinks,
159 | validLinks: validationSummary.validLinks,
160 | brokenLinks: validationSummary.brokenLinks,
161 | warningLinks: validationSummary.warningLinks,
162 | unknownLinks: validationSummary.unknownLinks,
163 | healthScore:
164 | validationSummary.totalLinks > 0
165 | ? (validationSummary.validLinks / validationSummary.totalLinks) * 100
166 | : 100,
167 | lastValidated: new Date().toISOString(),
168 | brokenLinksList: validationSummary.results
169 | .filter((r) => r.status === "broken")
170 | .map((r) => r.url),
171 | },
172 | weight: 1.0,
173 | lastUpdated: new Date().toISOString(),
174 | };
175 |
176 | kg.addNode(validationNode);
177 |
178 | // Create relationship: documentation_section -> link_validation
179 | kg.addEdge({
180 | source: docSectionId,
181 | target: validationId,
182 | type: "has_link_validation",
183 | weight: 1.0,
184 | confidence: 1.0,
185 | properties: {
186 | validatedAt: new Date().toISOString(),
187 | hasBrokenLinks: validationSummary.brokenLinks > 0,
188 | needsAttention: validationSummary.brokenLinks > 0,
189 | },
190 | });
191 |
192 | // If there are broken links, create "requires_fix" edges
193 | if (validationSummary.brokenLinks > 0) {
194 | kg.addEdge({
195 | source: validationId,
196 | target: docSectionId,
197 | type: "requires_fix",
198 | weight: validationSummary.brokenLinks / validationSummary.totalLinks,
199 | confidence: 1.0,
200 | properties: {
201 | severity: validationSummary.brokenLinks > 5 ? "high" : "medium",
202 | brokenLinkCount: validationSummary.brokenLinks,
203 | detectedAt: new Date().toISOString(),
204 | },
205 | });
206 | }
207 | }
208 |
209 | /**
210 | * Get link validation history from Knowledge Graph
211 | */
212 | export async function getLinkValidationHistory(
213 | docSectionId: string,
214 | ): Promise<GraphNode[]> {
215 | const kg = await getKnowledgeGraph();
216 |
217 | const edges = await kg.findEdges({
218 | source: docSectionId,
219 | type: "has_link_validation",
220 | });
221 |
222 | const validationNodes: GraphNode[] = [];
223 | const allNodes = await kg.getAllNodes();
224 |
225 | for (const edge of edges) {
226 | const validationNode = allNodes.find((n) => n.id === edge.target);
227 | if (validationNode) {
228 | validationNodes.push(validationNode);
229 | }
230 | }
231 |
232 | // Sort by lastValidated (newest first)
233 | return validationNodes.sort(
234 | (a, b) =>
235 | new Date(b.properties.lastValidated).getTime() -
236 | new Date(a.properties.lastValidated).getTime(),
237 | );
238 | }
239 |
240 | /**
241 | * Extract links from documentation content
242 | */
243 | export function extractLinksFromContent(content: string): {
244 | externalLinks: string[];
245 | internalLinks: string[];
246 | } {
247 | const externalLinks: string[] = [];
248 | const internalLinks: string[] = [];
249 |
250 | // Markdown links: [text](url)
251 | const markdownLinkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
252 | let match;
253 |
254 | while ((match = markdownLinkRegex.exec(content)) !== null) {
255 | const url = match[2];
256 | if (url.startsWith("http://") || url.startsWith("https://")) {
257 | externalLinks.push(url);
258 | } else {
259 | internalLinks.push(url);
260 | }
261 | }
262 |
263 | // HTML links: <a href="url">
264 | const htmlLinkRegex = /<a\s+(?:[^>]*?\s+)?href=(["'])(.*?)\1/gi;
265 |
266 | while ((match = htmlLinkRegex.exec(content)) !== null) {
267 | const url = match[2];
268 | if (url.startsWith("http://") || url.startsWith("https://")) {
269 | externalLinks.push(url);
270 | } else {
271 | internalLinks.push(url);
272 | }
273 | }
274 |
275 | return {
276 | externalLinks: [...new Set(externalLinks)], // Remove duplicates
277 | internalLinks: [...new Set(internalLinks)],
278 | };
279 | }
280 |
281 | /**
282 | * Validate all links in a documentation section and store in KG
283 | */
284 | export async function validateAndStoreDocumentationLinks(
285 | docSectionId: string,
286 | content: string,
287 | ): Promise<LinkValidationSummary> {
288 | const { externalLinks } = extractLinksFromContent(content);
289 |
290 | if (externalLinks.length === 0) {
291 | return {
292 | totalLinks: 0,
293 | validLinks: 0,
294 | brokenLinks: 0,
295 | warningLinks: 0,
296 | unknownLinks: 0,
297 | results: [],
298 | };
299 | }
300 |
301 | const validationSummary = await validateExternalLinks(externalLinks);
302 | await storeLinkValidationInKG(docSectionId, validationSummary);
303 |
304 | return validationSummary;
305 | }
306 |
```
--------------------------------------------------------------------------------
/docs/reference/cli.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.960Z"
4 | last_validated: "2025-11-20T00:46:21.960Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Command Line Interface
10 |
11 | DocuMCP primarily operates as an MCP server integrated with AI assistants, but it also provides command-line utilities for direct usage and debugging.
12 |
13 | ## MCP Server Usage
14 |
15 | The primary way to use DocuMCP is through MCP-compatible clients:
16 |
17 | ### Starting the MCP Server
18 |
19 | ```bash
20 | # Using npx (recommended)
21 | npx documcp
22 |
23 | # Using global installation
24 | documcp
25 |
26 | # Using Node.js directly
27 | node dist/index.js
28 | ```
29 |
30 | ### Server Information
31 |
32 | ```bash
33 | # Check version
34 | documcp --version
35 |
36 | # Show help
37 | documcp --help
38 |
39 | # Debug mode
40 | DEBUG=* documcp
41 | ```
42 |
43 | ## MCP Client Integration
44 |
45 | ### Claude Desktop Configuration
46 |
47 | Add to `claude_desktop_config.json`:
48 |
49 | ```json
50 | {
51 | "mcpServers": {
52 | "documcp": {
53 | "command": "npx",
54 | "args": ["documcp"],
55 | "env": {
56 | "DOCUMCP_STORAGE_DIR": "/path/to/storage"
57 | }
58 | }
59 | }
60 | }
61 | ```
62 |
63 | ### Environment Variables
64 |
65 | | Variable | Description | Default |
66 | | --------------------- | ------------------------ | ----------------- |
67 | | `DOCUMCP_STORAGE_DIR` | Memory storage directory | `.documcp/memory` |
68 | | `DEBUG` | Enable debug logging | `false` |
69 | | `NODE_ENV` | Node.js environment | `development` |
70 |
71 | ## Development Commands
72 |
73 | For development and testing:
74 |
75 | ### Build Commands
76 |
77 | ```bash
78 | # Build TypeScript
79 | npm run build
80 |
81 | # Build in watch mode
82 | npm run dev
83 |
84 | # Type checking
85 | npm run typecheck
86 | ```
87 |
88 | ### Testing Commands
89 |
90 | ```bash
91 | # Run all tests
92 | npm test
93 |
94 | # Run tests with coverage
95 | npm run test:coverage
96 |
97 | # Run performance benchmarks
98 | npm run test:performance
99 |
100 | # CI test run
101 | npm run test:ci
102 | ```
103 |
104 | ### Code Quality Commands
105 |
106 | ```bash
107 | # Lint code
108 | npm run lint
109 |
110 | # Fix linting issues
111 | npm run lint:fix
112 |
113 | # Format code
114 | npm run format
115 |
116 | # Check formatting
117 | npm run format:check
118 |
119 | # Full validation
120 | npm run validate:rules
121 | ```
122 |
123 | ### Documentation Commands
124 |
125 | ```bash
126 | # Check documentation links
127 | npm run docs:check-links
128 |
129 | # Check external links
130 | npm run docs:check-links:external
131 |
132 | # Check internal links only
133 | npm run docs:check-links:internal
134 |
135 | # Validate documentation structure
136 | npm run docs:validate
137 |
138 | # Complete documentation test
139 | npm run docs:test
140 | ```
141 |
142 | ### Security Commands
143 |
144 | ```bash
145 | # Check for vulnerabilities
146 | npm run security:check
147 |
148 | # Audit dependencies
149 | npm audit
150 |
151 | # Fix security issues
152 | npm audit fix
153 | ```
154 |
155 | ### Benchmark Commands
156 |
157 | ```bash
158 | # Run performance benchmarks
159 | npm run benchmark:run
160 |
161 | # Show current performance metrics
162 | npm run benchmark:current
163 |
164 | # Create benchmark configuration
165 | npm run benchmark:create-config
166 |
167 | # Show benchmark help
168 | npm run benchmark:help
169 | ```
170 |
171 | ## Tool Invocation via CLI
172 |
173 | While DocuMCP is designed for MCP integration, you can test tools via Node.js:
174 |
175 | ### Direct Tool Testing
176 |
177 | ```javascript
178 | // test-tool.js
179 | import { analyzeRepository } from "./dist/tools/analyze-repository.js";
180 |
181 | async function test() {
182 | const result = await analyzeRepository({
183 | path: process.cwd(),
184 | depth: "standard",
185 | });
186 | console.log(JSON.stringify(result, null, 2));
187 | }
188 |
189 | test().catch(console.error);
190 | ```
191 |
192 | ```bash
193 | # Run test
194 | node test-tool.js
195 | ```
196 |
197 | ### Tool-Specific Examples
198 |
199 | **Repository Analysis:**
200 |
201 | ```javascript
202 | import { analyzeRepository } from "./dist/tools/analyze-repository.js";
203 |
204 | const analysis = await analyzeRepository({
205 | path: "/path/to/repository",
206 | depth: "deep",
207 | });
208 | ```
209 |
210 | **SSG Recommendation:**
211 |
212 | ```javascript
213 | import { recommendSSG } from "./dist/tools/recommend-ssg.js";
214 |
215 | const recommendation = await recommendSSG({
216 | analysisId: "analysis_12345",
217 | preferences: {
218 | ecosystem: "javascript",
219 | priority: "features",
220 | },
221 | });
222 | ```
223 |
224 | **Configuration Generation:**
225 |
226 | ```javascript
227 | import { generateConfig } from "./dist/tools/generate-config.js";
228 |
229 | const config = await generateConfig({
230 | ssg: "docusaurus",
231 | projectName: "My Project",
232 | outputPath: "./docs",
233 | });
234 | ```
235 |
236 | ## Debugging
237 |
238 | ### Debug Modes
239 |
240 | Enable detailed logging:
241 |
242 | ```bash
243 | # All debug info
244 | DEBUG=* documcp
245 |
246 | # Specific modules
247 | DEBUG=documcp:* documcp
248 | DEBUG=documcp:analysis documcp
249 | DEBUG=documcp:memory documcp
250 | ```
251 |
252 | ### Log Levels
253 |
254 | DocuMCP supports different log levels:
255 |
256 | ```bash
257 | # Error only
258 | NODE_ENV=production documcp
259 |
260 | # Development (verbose)
261 | NODE_ENV=development documcp
262 |
263 | # Custom logging
264 | DEBUG=documcp:error,documcp:warn documcp
265 | ```
266 |
267 | ### Performance Debugging
268 |
269 | ```bash
270 | # Enable performance tracking
271 | DEBUG=documcp:perf documcp
272 |
273 | # Memory usage tracking
274 | DEBUG=documcp:memory documcp
275 |
276 | # Network requests
277 | DEBUG=documcp:http documcp
278 | ```
279 |
280 | ## Configuration Files
281 |
282 | ### Project-level Configuration
283 |
284 | Create `.documcprc.json` in your project:
285 |
286 | ```json
287 | {
288 | "storage": {
289 | "directory": ".documcp/memory",
290 | "maxEntries": 1000,
291 | "cleanupDays": 30
292 | },
293 | "analysis": {
294 | "defaultDepth": "standard",
295 | "excludePatterns": ["node_modules", ".git", "dist"]
296 | },
297 | "deployment": {
298 | "defaultBranch": "gh-pages",
299 | "verifyDeployment": true
300 | }
301 | }
302 | ```
303 |
304 | ### Global Configuration
305 |
306 | Create `~/.documcp/config.json`:
307 |
308 | ```json
309 | {
310 | "defaultPreferences": {
311 | "ecosystem": "any",
312 | "priority": "simplicity"
313 | },
314 | "github": {
315 | "defaultOrg": "your-username"
316 | },
317 | "memory": {
318 | "enableLearning": true,
319 | "shareAnonymousData": false
320 | }
321 | }
322 | ```
323 |
324 | ## Exit Codes
325 |
326 | DocuMCP uses standard exit codes:
327 |
328 | | Code | Meaning |
329 | | ---- | -------------------- |
330 | | 0 | Success |
331 | | 1 | General error |
332 | | 2 | Invalid arguments |
333 | | 3 | File system error |
334 | | 4 | Network error |
335 | | 5 | Configuration error |
336 | | 6 | Tool execution error |
337 |
338 | ## Scripting and Automation
339 |
340 | ### Batch Operations
341 |
342 | Create scripts for common workflows:
343 |
344 | ```bash
345 | #!/bin/bash
346 | # deploy-docs.sh
347 |
348 | set -e
349 |
350 | echo "Starting documentation deployment..."
351 |
352 | # Test locally first
353 | echo "Testing local build..."
354 | npm run docs:validate
355 |
356 | # Deploy via DocuMCP
357 | echo "Analyzing repository..."
358 | # Trigger MCP analysis through your client
359 |
360 | echo "Deployment complete!"
361 | ```
362 |
363 | ### CI/CD Integration
364 |
365 | DocuMCP can be used in CI/CD pipelines:
366 |
367 | ```yaml
368 | # .github/workflows/docs.yml
369 | name: Documentation
370 |
371 | on:
372 | push:
373 | branches: [main]
374 | paths: ["docs/**", "*.md"]
375 |
376 | jobs:
377 | deploy-docs:
378 | runs-on: ubuntu-latest
379 | steps:
380 | - uses: actions/checkout@v4
381 |
382 | - name: Setup Node.js
383 | uses: actions/setup-node@v4
384 | with:
385 | node-version: "20"
386 |
387 | - name: Install DocuMCP
388 | run: npm install -g documcp
389 |
390 | - name: Validate documentation
391 | run: |
392 | # Use DocuMCP validation tools
393 | npm run docs:validate
394 | ```
395 |
396 | ### Programmatic Usage
397 |
398 | For advanced integration:
399 |
400 | ```javascript
401 | // integration.js
402 | import { Server } from "@modelcontextprotocol/sdk/server/index.js";
403 | import { analyzeRepository } from "./dist/tools/analyze-repository.js";
404 | import { recommendSSG } from "./dist/tools/recommend-ssg.js";
405 | import { deployPages } from "./dist/tools/deploy-pages.js";
406 |
407 | class DocuMCPIntegration {
408 | async deployDocumentation(repoPath) {
409 | // Analyze
410 | const analysis = await analyzeRepository({
411 | path: repoPath,
412 | depth: "standard",
413 | });
414 |
415 | // Get recommendation
416 | const recommendation = await recommendSSG({
417 | analysisId: analysis.id,
418 | });
419 |
420 | // Deploy
421 | const deployment = await deployPages({
422 | repository: repoPath,
423 | ssg: recommendation.recommended,
424 | });
425 |
426 | return { analysis, recommendation, deployment };
427 | }
428 | }
429 | ```
430 |
431 | ## Troubleshooting CLI Issues
432 |
433 | ### Common Problems
434 |
435 | **Command not found:**
436 |
437 | ```bash
438 | # Check installation
439 | which documcp
440 | npm list -g documcp
441 |
442 | # Reinstall if needed
443 | npm uninstall -g documcp
444 | npm install -g documcp
445 | ```
446 |
447 | **Permission errors:**
448 |
449 | ```bash
450 | # Check permissions
451 | ls -la $(which documcp)
452 |
453 | # Fix permissions
454 | chmod +x $(which documcp)
455 | ```
456 |
457 | **Module resolution errors:**
458 |
459 | ```bash
460 | # Clear npm cache
461 | npm cache clean --force
462 |
463 | # Rebuild
464 | npm run build
465 | ```
466 |
467 | ### Getting Help
468 |
469 | ```bash
470 | # Show help
471 | documcp --help
472 |
473 | # Show version
474 | documcp --version
475 |
476 | # Contact support
477 | echo "Report issues: https://github.com/tosin2013/documcp/issues"
478 | ```
479 |
480 | For more detailed troubleshooting, see the [Troubleshooting Guide](../how-to/troubleshooting.md).
481 |
```
--------------------------------------------------------------------------------
/docs/adrs/007-mcp-prompts-and-resources-integration.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | id: 007-mcp-prompts-and-resources-integration
3 | title: "ADR-007: MCP Prompts and Resources Integration"
4 | sidebar_label: "ADR-7: MCP Prompts and Resources Integration"
5 | sidebar_position: 7
6 | documcp:
7 | last_updated: "2025-11-20T00:46:21.941Z"
8 | last_validated: "2025-11-20T00:46:21.941Z"
9 | auto_updated: false
10 | update_frequency: monthly
11 | ---
12 |
13 | # ADR-007: MCP Prompts and Resources Integration for AI Assistance
14 |
15 | ## Status
16 |
17 | Proposed
18 |
19 | ## Context
20 |
21 | DocuMCP needs AI assistance capabilities, and the Model Context Protocol provides native support for exactly this use case through **Prompts** and **Resources**. Rather than extending the protocol, we should leverage MCP's built-in capabilities:
22 |
23 | - **MCP Prompts**: Pre-written templates that help users accomplish specific tasks
24 | - **MCP Resources**: File-like data that can be read by clients (like API responses, file contents, or generated documentation)
25 |
26 | Current MCP Core Concepts that we can utilize:
27 |
28 | 1. **Tools**: Interactive functions (already implemented - analyze_repository, recommend_ssg, etc.)
29 | 2. **Prompts**: Template-based assistance for common workflows
30 | 3. **Resources**: Readable data and content that clients can access
31 |
32 | This approach maintains full MCP compliance while providing rich AI assistance through the protocol's intended mechanisms.
33 |
34 | ## Decision
35 |
36 | We will implement AI assistance using MCP's native **Prompts** and **Resources** capabilities, providing pre-written prompt templates for documentation workflows and exposing generated content through the MCP resource system.
37 |
38 | ### Core Implementation Strategy:
39 |
40 | #### 1. MCP Prompts for Documentation Workflows
41 |
42 | ```typescript
43 | // Implement MCP ListPromptsRequestSchema and GetPromptRequestSchema
44 | const DOCUMENTATION_PROMPTS = [
45 | {
46 | name: "analyze-and-recommend",
47 | description: "Complete repository analysis and SSG recommendation workflow",
48 | arguments: [
49 | {
50 | name: "repository_path",
51 | description: "Path to repository",
52 | required: true,
53 | },
54 | {
55 | name: "priority",
56 | description: "Priority: simplicity, features, performance",
57 | },
58 | ],
59 | },
60 | {
61 | name: "setup-documentation",
62 | description:
63 | "Create comprehensive documentation structure with best practices",
64 | arguments: [
65 | { name: "project_name", description: "Project name", required: true },
66 | { name: "ssg_type", description: "Static site generator type" },
67 | ],
68 | },
69 | {
70 | name: "troubleshoot-deployment",
71 | description: "Diagnose and fix GitHub Pages deployment issues",
72 | arguments: [
73 | {
74 | name: "repository_url",
75 | description: "GitHub repository URL",
76 | required: true,
77 | },
78 | { name: "error_message", description: "Deployment error message" },
79 | ],
80 | },
81 | ];
82 | ```
83 |
84 | #### 2. MCP Resources for Generated Content
85 |
86 | ```typescript
87 | // Implement ListResourcesRequestSchema and ReadResourceRequestSchema
88 | interface DocuMCPResource {
89 | uri: string; // e.g., "documcp://analysis/repo-123"
90 | name: string; // Human-readable name
91 | description: string; // What this resource contains
92 | mimeType: string; // Content type
93 | }
94 |
95 | // Resource types we'll expose:
96 | const RESOURCE_TYPES = [
97 | "documcp://analysis/{analysisId}", // Repository analysis results
98 | "documcp://config/{ssgType}/{projectId}", // Generated configuration files
99 | "documcp://structure/{projectId}", // Documentation structure templates
100 | "documcp://deployment/{workflowId}", // GitHub Actions workflows
101 | "documcp://templates/{templateType}", // Reusable templates
102 | ];
103 | ```
104 |
105 | #### 3. Integration with Existing Tools
106 |
107 | - **Tools remain unchanged**: analyze_repository, recommend_ssg, generate_config, etc.
108 | - **Prompts provide workflows**: Chain multiple tool calls with guided prompts
109 | - **Resources expose results**: Make tool outputs accessible as MCP resources
110 |
111 | ### Example Workflow Integration:
112 |
113 | ```typescript
114 | // MCP Prompt: "analyze-and-recommend"
115 | // Generated prompt text that guides the user through:
116 | // 1. Call analyze_repository tool
117 | // 2. Review analysis results via documcp://analysis/{id} resource
118 | // 3. Call recommend_ssg tool with analysis results
119 | // 4. Access recommendations via documcp://recommendations/{id} resource
120 | // 5. Call generate_config with selected SSG
121 | ```
122 |
123 | ## Alternatives Considered
124 |
125 | ### Alternative 1: Custom Protocol Extensions (Previous Approach)
126 |
127 | - **Pros**: Maximum flexibility, custom AI features
128 | - **Cons**: Protocol complexity, compatibility issues, non-standard
129 | - **Decision**: Rejected in favor of MCP-native approach
130 |
131 | ### Alternative 2: Tools-Only Approach
132 |
133 | - **Pros**: Simple, already implemented
134 | - **Cons**: No guided workflows, no template assistance, harder user experience
135 | - **Decision**: Insufficient for comprehensive AI assistance
136 |
137 | ### Alternative 3: External AI Service Integration
138 |
139 | - **Pros**: Leverage existing AI platforms
140 | - **Cons**: Breaks MCP cohesion, additional dependencies, latency
141 | - **Decision**: Conflicts with MCP server simplicity
142 |
143 | ## Consequences
144 |
145 | ### Positive Consequences
146 |
147 | - **MCP Compliance**: Uses protocol as designed, no custom extensions needed
148 | - **Client Compatibility**: Works with all MCP clients (Claude Desktop, GitHub Copilot, etc.)
149 | - **Guided Workflows**: Prompts provide step-by-step assistance for complex tasks
150 | - **Rich Content Access**: Resources make generated content easily accessible
151 | - **Template Reusability**: Prompts can be customized and reused across projects
152 | - **Simplified Architecture**: No need for custom protocol handling or AI-specific interfaces
153 |
154 | ### Negative Consequences
155 |
156 | - **Prompt Complexity**: Complex workflows require sophisticated prompt engineering
157 | - **Resource Management**: Need efficient resource caching and lifecycle management
158 | - **Limited AI Features**: Constrained to MCP's prompt/resource model
159 | - **Template Maintenance**: Prompts need regular updates as tools evolve
160 |
161 | ## Implementation Plan
162 |
163 | ### Phase 1: Core MCP Integration (Week 1-2)
164 |
165 | 1. Implement `ListPromptsRequestSchema` and `GetPromptRequestSchema` handlers
166 | 2. Implement `ListResourcesRequestSchema` and `ReadResourceRequestSchema` handlers
167 | 3. Create resource URI schema and routing system
168 | 4. Add MCP capabilities registration for prompts and resources
169 |
170 | ### Phase 2: Documentation Prompts (Week 3-4)
171 |
172 | 1. Create "analyze-and-recommend" workflow prompt
173 | 2. Create "setup-documentation" structure prompt
174 | 3. Create "troubleshoot-deployment" diagnostic prompt
175 | 4. Add prompt argument validation and help text
176 |
177 | ### Phase 3: Resource Management (Week 5-6)
178 |
179 | 1. Implement resource caching for analysis results
180 | 2. Add generated configuration file resources
181 | 3. Create template library resources
182 | 4. Add resource cleanup and lifecycle management
183 |
184 | ### Phase 4: Advanced Features (Week 7-8)
185 |
186 | 1. Dynamic prompt generation based on project characteristics
187 | 2. Contextual resource recommendations
188 | 3. Prompt composition for complex workflows
189 | 4. Integration testing with major MCP clients
190 |
191 | ## Integration with Existing Architecture
192 |
193 | ### ADR-001 (MCP Server Architecture)
194 |
195 | - Extends the TypeScript MCP SDK usage to include prompts and resources
196 | - Maintains stateless operation model
197 | - Leverages existing modular design
198 |
199 | ### ADR-006 (MCP Tools API Design)
200 |
201 | - Tools remain the primary interface for actions
202 | - Prompts provide guided workflows using existing tools
203 | - Resources expose tool outputs in structured format
204 |
205 | ### ADR-007 (Pluggable Prompt Tool Architecture)
206 |
207 | - **Modified Approach**: Instead of custom prompt engines, use MCP prompts
208 | - Template system becomes MCP prompt templates
209 | - Configuration-driven approach still applies for prompt customization
210 |
211 | ## MCP Server Capabilities Declaration
212 |
213 | ```typescript
214 | server.setRequestHandler(InitializeRequestSchema, async () => ({
215 | protocolVersion: "2024-11-05",
216 | capabilities: {
217 | tools: {}, // Existing tool capabilities
218 | prompts: {}, // NEW: Prompt template capabilities
219 | resources: {}, // NEW: Resource access capabilities
220 | },
221 | serverInfo: {
222 | name: "documcp",
223 | version: "0.2.0",
224 | },
225 | }));
226 | ```
227 |
228 | ## Future Considerations
229 |
230 | - Integration with MCP sampling for AI-powered responses
231 | - Advanced prompt chaining and conditional workflows
232 | - Resource subscriptions for real-time updates
233 | - Community prompt template sharing and marketplace
234 |
```
--------------------------------------------------------------------------------
/docs/tutorials/first-deployment.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.971Z"
4 | last_validated: "2025-11-20T00:46:21.971Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Your First Documentation Deployment
10 |
11 | This tutorial walks you through deploying your first documentation site using DocuMCP, from analysis to live GitHub Pages deployment.
12 |
13 | ## What You'll Build
14 |
15 | By the end of this tutorial, you'll have:
16 |
17 | - A live documentation site on GitHub Pages
18 | - Automated deployment workflow
19 | - Professional Diataxis-structured content
20 | - Understanding of DocuMCP's deployment process
21 |
22 | ## Prerequisites
23 |
24 | - Completed the [Getting Started](getting-started.md) tutorial
25 | - GitHub repository with your code
26 | - Write access to the repository
27 | - GitHub Pages enabled in repository settings
28 |
29 | ## Step-by-Step Deployment
30 |
31 | ### Step 1: Complete Repository Analysis
32 |
33 | If you haven't already, analyze your repository:
34 |
35 | ```bash
36 | # Prompt to DocuMCP:
37 | "analyze my repository for documentation deployment"
38 | ```
39 |
40 | Expected output includes analysis ID (e.g., `analysis_xyz789`) that we'll use throughout the deployment.
41 |
42 | ### Step 2: Get Deployment-Optimized Recommendations
43 |
44 | Request recommendations specifically for deployment:
45 |
46 | ```bash
47 | # Prompt:
48 | "recommend the best static site generator for GitHub Pages deployment based on analysis_xyz789"
49 | ```
50 |
51 | DocuMCP will consider:
52 |
53 | - **GitHub Pages compatibility** (native Jekyll support vs. Actions required)
54 | - **Build time** (Hugo's speed vs. Docusaurus features)
55 | - **Maintenance overhead** (MkDocs simplicity vs. Eleventy flexibility)
56 |
57 | ### Step 3: Generate Deployment Configuration
58 |
59 | Create production-ready configuration:
60 |
61 | ```bash
62 | # For example, if Docusaurus was recommended:
63 | "generate Docusaurus configuration for production deployment to GitHub Pages"
64 | ```
65 |
66 | This creates:
67 |
68 | - **docusaurus.config.js**: Optimized for GitHub Pages
69 | - **package.json updates**: Required dependencies
70 | - **Build scripts**: Production build configuration
71 |
72 | ### Step 4: Set Up Documentation Structure
73 |
74 | Create comprehensive documentation structure:
75 |
76 | ```bash
77 | # Prompt:
78 | "set up Diataxis documentation structure for Docusaurus deployment"
79 | ```
80 |
81 | Creates organized folders:
82 |
83 | ```
84 | docs/
85 | ├── tutorials/ # Learning-oriented
86 | ├── how-to-guides/ # Problem-solving
87 | ├── reference/ # Information-oriented
88 | ├── explanation/ # Understanding-oriented
89 | └── index.md # Landing page
90 | ```
91 |
92 | ### Step 5: Populate with Initial Content
93 |
94 | Generate starter content based on your project:
95 |
96 | ```bash
97 | # Prompt:
98 | "populate the documentation structure with content based on my project analysis"
99 | ```
100 |
101 | DocuMCP creates:
102 |
103 | - **Project-specific tutorials** based on your codebase
104 | - **API documentation** extracted from your code
105 | - **Installation guides** tailored to your tech stack
106 | - **Configuration examples** using your actual project structure
107 |
108 | ### Step 6: Deploy to GitHub Pages
109 |
110 | Set up automated deployment:
111 |
112 | ```bash
113 | # Prompt:
114 | "deploy my Docusaurus documentation to GitHub Pages with automated workflow"
115 | ```
116 |
117 | This generates:
118 |
119 | - **.github/workflows/deploy.yml**: GitHub Actions workflow
120 | - **Optimized build process**: Cached dependencies, parallel builds
121 | - **Security configuration**: OIDC tokens, minimal permissions
122 |
123 | ### Step 7: Verify Deployment
124 |
125 | Check that everything is working:
126 |
127 | ```bash
128 | # Prompt:
129 | "verify my GitHub Pages deployment is working correctly"
130 | ```
131 |
132 | DocuMCP checks:
133 |
134 | - **Workflow status**: Build and deployment success
135 | - **Site accessibility**: Homepage loads correctly
136 | - **Navigation**: All sections are reachable
137 | - **Asset loading**: CSS, JS, images work properly
138 |
139 | ## Example: Complete TypeScript Library Deployment
140 |
141 | Here's a real example for a TypeScript library:
142 |
143 | ### 1. Analysis Results
144 |
145 | ```json
146 | {
147 | "id": "analysis_ts_lib_001",
148 | "structure": {
149 | "totalFiles": 47,
150 | "languages": { ".ts": 32, ".md": 5, ".json": 3 },
151 | "hasTests": true,
152 | "hasCI": true
153 | },
154 | "recommendations": {
155 | "primaryLanguage": "typescript",
156 | "projectType": "library"
157 | }
158 | }
159 | ```
160 |
161 | ### 2. Recommendation
162 |
163 | ```json
164 | {
165 | "recommended": "docusaurus",
166 | "confidence": 0.88,
167 | "reasoning": [
168 | "TypeScript ecosystem alignment",
169 | "Excellent API documentation support",
170 | "React component integration for examples"
171 | ]
172 | }
173 | ```
174 |
175 | ### 3. Generated Configuration
176 |
177 | **docusaurus.config.js**:
178 |
179 | ```javascript
180 | const config = {
181 | title: "TypeScript Library Docs",
182 | tagline: "Comprehensive API documentation",
183 | url: "https://yourusername.github.io",
184 | baseUrl: "/your-repo-name/",
185 |
186 | // GitHub Pages deployment config
187 | organizationName: "yourusername",
188 | projectName: "your-repo-name",
189 | deploymentBranch: "gh-pages",
190 | trailingSlash: false,
191 |
192 | presets: [
193 | [
194 | "classic",
195 | {
196 | docs: {
197 | routeBasePath: "/",
198 | sidebarPath: require.resolve("./sidebars.js"),
199 | },
200 | theme: {
201 | customCss: require.resolve("./src/css/custom.css"),
202 | },
203 | },
204 | ],
205 | ],
206 | };
207 | ```
208 |
209 | ### 4. GitHub Actions Workflow
210 |
211 | **.github/workflows/deploy.yml**:
212 |
213 | ```yaml
214 | name: Deploy Documentation
215 |
216 | on:
217 | push:
218 | branches: [main]
219 | paths: ["docs/**", "docusaurus.config.js"]
220 |
221 | permissions:
222 | contents: read
223 | pages: write
224 | id-token: write
225 |
226 | jobs:
227 | deploy:
228 | environment:
229 | name: github-pages
230 | url: ${{ steps.deployment.outputs.page_url }}
231 | runs-on: ubuntu-latest
232 | steps:
233 | - name: Checkout
234 | uses: actions/checkout@v4
235 |
236 | - name: Setup Node.js
237 | uses: actions/setup-node@v4
238 | with:
239 | node-version: "20"
240 | cache: "npm"
241 |
242 | - name: Install dependencies
243 | run: npm ci
244 |
245 | - name: Build documentation
246 | run: npm run build
247 |
248 | - name: Setup Pages
249 | uses: actions/configure-pages@v5
250 |
251 | - name: Upload artifact
252 | uses: actions/upload-pages-artifact@v4
253 | with:
254 | path: "./build"
255 |
256 | - name: Deploy to GitHub Pages
257 | id: deployment
258 | uses: actions/deploy-pages@v4
259 | ```
260 |
261 | ## Verification Checklist
262 |
263 | After deployment, verify:
264 |
265 | - [ ] **Site is live** at `https://yourusername.github.io/repository-name`
266 | - [ ] **All sections load** (Tutorials, How-to, Reference, Explanation)
267 | - [ ] **Search works** (if enabled)
268 | - [ ] **Mobile responsive** design
269 | - [ ] **Fast loading** (check Core Web Vitals)
270 | - [ ] **SEO optimized** (meta tags, sitemap)
271 |
272 | ## Common Deployment Issues
273 |
274 | ### Build Failures
275 |
276 | **Problem**: Workflow fails during build
277 | **Solution**:
278 |
279 | - Check Node.js version compatibility
280 | - Verify all dependencies are in package.json
281 | - Review build logs in Actions tab
282 |
283 | ### Page Not Found (404)
284 |
285 | **Problem**: Site shows 404 error
286 | **Solution**:
287 |
288 | - Verify `baseUrl` in config matches repository name
289 | - Check GitHub Pages source is set to GitHub Actions
290 | - Confirm deployment branch exists
291 |
292 | ### Assets Not Loading
293 |
294 | **Problem**: CSS/JS files return 404
295 | **Solution**:
296 |
297 | - Ensure `publicPath` is configured correctly
298 | - Check trailing slash configuration
299 | - Verify asset paths are relative
300 |
301 | ## Performance Optimization
302 |
303 | ### Build Speed
304 |
305 | - **Caching**: Enable npm cache in GitHub Actions
306 | - **Parallel builds**: Use appropriate number of workers
307 | - **Incremental builds**: Only rebuild changed files
308 |
309 | ### Site Performance
310 |
311 | - **Image optimization**: Compress and use modern formats
312 | - **Code splitting**: Load only necessary JavaScript
313 | - **CDN integration**: Use GitHub's CDN for assets
314 |
315 | ## Next Steps
316 |
317 | Now that you have a deployed documentation site:
318 |
319 | 1. **[Set up development workflow](development-setup.md)** for ongoing maintenance
320 | 2. **[Configure custom domain](../how-to/custom-domains.md)** (optional)
321 | 3. **[Set up monitoring](../how-to/site-monitoring.md)** for uptime tracking
322 | 4. **[Optimize for search](../how-to/seo-optimization.md)** engines
323 |
324 | ## Summary
325 |
326 | You've successfully:
327 | ✅ Analyzed your repository for deployment
328 | ✅ Generated production-ready configuration
329 | ✅ Set up professional documentation structure
330 | ✅ Deployed to GitHub Pages with automation
331 | ✅ Verified your live documentation site
332 |
333 | Your documentation is now live and will automatically update with each commit!
334 |
335 | ## Troubleshooting
336 |
337 | If you encounter issues:
338 |
339 | 1. Check the [troubleshooting guide](../how-to/troubleshooting.md)
340 | 2. Review GitHub Actions logs
341 | 3. Verify repository permissions
342 | 4. Confirm GitHub Pages settings
343 |
344 | Need help? Open an issue on the [DocuMCP repository](https://github.com/tosin2013/documcp/issues).
345 |
```