This is page 2 of 20. Use http://codebase.md/tosin2013/documcp?lines=false&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
--------------------------------------------------------------------------------
/src/tools/analyze-deployments.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Analyze Deployments Tool
* Phase 2.4: Deployment Analytics and Insights
*
* MCP tool for analyzing deployment patterns and generating insights
*/
import { z } from "zod";
import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
import { getDeploymentAnalytics } from "../memory/deployment-analytics.js";
const inputSchema = z.object({
analysisType: z
.enum(["full_report", "ssg_stats", "compare", "health", "trends"])
.optional()
.default("full_report"),
ssg: z.string().optional().describe("SSG name for ssg_stats analysis"),
ssgs: z
.array(z.string())
.optional()
.describe("Array of SSG names for comparison"),
periodDays: z
.number()
.optional()
.default(30)
.describe("Period in days for trend analysis"),
});
export async function analyzeDeployments(
args: unknown,
): Promise<{ content: any[] }> {
const startTime = Date.now();
try {
const { analysisType, ssg, ssgs, periodDays } = inputSchema.parse(args);
const analytics = getDeploymentAnalytics();
let result: any;
let actionDescription: string;
switch (analysisType) {
case "full_report":
result = await analytics.generateReport();
actionDescription =
"Generated comprehensive deployment analytics report";
break;
case "ssg_stats":
if (!ssg) {
throw new Error("SSG name required for ssg_stats analysis");
}
result = await analytics.getSSGStatistics(ssg);
if (!result) {
throw new Error(`No deployment data found for SSG: ${ssg}`);
}
actionDescription = `Retrieved statistics for ${ssg}`;
break;
case "compare":
if (!ssgs || ssgs.length < 2) {
throw new Error(
"At least 2 SSG names required for comparison analysis",
);
}
result = await analytics.compareSSGs(ssgs);
actionDescription = `Compared ${ssgs.length} SSGs`;
break;
case "health":
result = await analytics.getHealthScore();
actionDescription = "Calculated deployment health score";
break;
case "trends":
result = await analytics.identifyTrends(periodDays);
actionDescription = `Identified deployment trends over ${periodDays} days`;
break;
default:
throw new Error(`Unknown analysis type: ${analysisType}`);
}
const response: MCPToolResponse<any> = {
success: true,
data: result,
metadata: {
toolVersion: "1.0.0",
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString(),
},
recommendations: [
{
type: "info",
title: actionDescription,
description: `Analysis completed successfully`,
},
],
};
// Add context-specific recommendations
if (analysisType === "full_report" && result.recommendations) {
response.recommendations?.push(
...result.recommendations.slice(0, 3).map((rec: string) => ({
type: "info" as const,
title: "Recommendation",
description: rec,
})),
);
}
if (analysisType === "health") {
const healthStatus =
result.score > 70 ? "good" : result.score > 40 ? "warning" : "critical";
response.recommendations?.push({
type: healthStatus === "good" ? "info" : "warning",
title: `Health Score: ${result.score}/100`,
description: `Deployment health is ${healthStatus}`,
});
}
return formatMCPResponse(response);
} catch (error) {
const errorResponse: MCPToolResponse = {
success: false,
error: {
code: "ANALYTICS_FAILED",
message: `Failed to analyze deployments: ${error}`,
resolution:
"Ensure deployment data exists in the knowledge graph and parameters are valid",
},
metadata: {
toolVersion: "1.0.0",
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString(),
},
};
return formatMCPResponse(errorResponse);
}
}
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/release_improvements.md:
--------------------------------------------------------------------------------
```markdown
# Release Pipeline Improvement Issues
## 🚀 Critical Improvements
### Issue 1: Fix npm Package Publishing
**Title:** Verify and fix npm package publishing configuration
**Priority:** High
**Labels:** bug, release, npm
**Problem:**
The release workflow is configured to publish to npm, but the package "documcp" is not found on the npm registry, indicating either publication failures or configuration issues.
**Solution:**
1. Verify NPM_TOKEN secret configuration in GitHub repository secrets
2. Test npm publication locally with dry-run
3. Add publication verification step to release workflow
4. Implement fallback handling for publication failures
**Acceptance Criteria:**
- [ ] npm package "documcp" is publicly accessible on npm registry
- [ ] Release workflow successfully publishes new versions
- [ ] Publication failures are properly logged and handled
---
### Issue 2: Automated Changelog Generation
**Title:** Implement automated changelog generation from commits
**Priority:** High
**Labels:** enhancement, automation, documentation
**Problem:**
Changelog updates are currently manual, leading to potential inconsistencies and missed entries.
**Solution:**
1. Implement conventional commits standard
2. Add automated changelog generation tool (e.g., standard-version, semantic-release)
3. Integrate with release workflow
4. Add commit validation
**Acceptance Criteria:**
- [ ] Changelog automatically updated on release
- [ ] Commit messages follow conventional format
- [ ] Release notes include all relevant changes
---
### Issue 3: Improve Test Coverage to 85%
**Title:** Increase test coverage to meet 85% target threshold
**Priority:** High
**Labels:** testing, quality, coverage
**Problem:**
Current test coverage (82.59%) is below the 85% target, particularly in critical files.
**Solution:**
1. Focus on files with <60% coverage first
2. Add comprehensive tests for error handling
3. Improve branch coverage
4. Add integration tests
**Acceptance Criteria:**
- [ ] Overall statement coverage ≥85%
- [ ] No files with <70% coverage
- [ ] Critical business logic fully tested
---
## 🎯 Quality Improvements
### Issue 4: Conventional Commits Enforcement
**Title:** Implement commitlint for conventional commits enforcement
**Priority:** Medium
**Labels:** enhancement, automation, quality
**Solution:**
1. Add commitlint configuration
2. Set up husky hooks
3. Add commit message validation
4. Update contributing guidelines
---
### Issue 5: Enhanced Release Notes
**Title:** Improve release note quality and structure
**Priority:** Medium
**Labels:** documentation, enhancement
**Solution:**
1. Create release note templates
2. Add categorized sections (Features, Fixes, Breaking Changes)
3. Include contributor recognition
4. Add performance metrics
---
### Issue 6: Smart Dependabot Auto-merge
**Title:** Enhance Dependabot auto-merge with semver awareness
**Priority:** Medium
**Labels:** dependencies, automation, security
**Solution:**
1. Implement semver-based merge rules
2. Add major version update review requirement
3. Include test verification before auto-merge
4. Add security update prioritization
---
## 🔮 Advanced Features
### Issue 7: AI-Enhanced Release Notes
**Title:** Implement AI-powered release note generation
**Priority:** Low
**Labels:** enhancement, ai, automation
**Solution:**
1. Integrate with AI API (OpenAI, Gemini, etc.)
2. Create context-aware prompt templates
3. Add project-specific terminology
4. Implement quality validation
---
### Issue 8: Release Health Dashboard
**Title:** Create release pipeline monitoring dashboard
**Priority:** Low
**Labels:** monitoring, enhancement, devops
**Solution:**
1. Track release success rates
2. Monitor publication times
3. Track test coverage trends
4. Add alerting for failures
## 📊 Implementation Priority
1. **Critical:** Issues 1-3 (npm, changelog, coverage)
2. **Quality:** Issues 4-6 (commits, notes, dependabot)
3. **Advanced:** Issues 7-8 (AI, dashboard)
## 🛠️ Technical Dependencies
- Requires Node.js 20+
- GitHub Actions environment
- npm registry access
- Optional: AI API access for enhanced features
```
--------------------------------------------------------------------------------
/docs/explanation/index.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.947Z"
last_validated: "2025-11-20T00:46:21.947Z"
auto_updated: false
update_frequency: monthly
---
# Explanation Documentation
Conceptual documentation and background information about DocuMCP's architecture and design principles.
## Architecture Overview
- [DocuMCP Architecture](architecture.md) - Complete system architecture overview
- [Phase 2: Intelligence & Learning System](../phase-2-intelligence.md) - Advanced AI features
## Design Principles
### Methodological Pragmatism
DocuMCP is built on methodological pragmatism frameworks, emphasizing:
- **Practical Outcomes**: Focus on what works reliably
- **Systematic Verification**: Structured processes for validating knowledge
- **Explicit Fallibilism**: Acknowledging limitations and uncertainty
- **Cognitive Systematization**: Organizing knowledge into coherent systems
### Error Architecture Awareness
The system recognizes different types of errors:
- **Human-Cognitive Errors**: Knowledge gaps, attention limitations, cognitive biases
- **Artificial-Stochastic Errors**: Pattern completion errors, context limitations, training artifacts
### Systematic Verification
All recommendations include:
- Confidence scores for significant recommendations
- Explicit checks for different error types
- Verification approaches and validation methods
- Consideration of edge cases and limitations
## System Components
### Core Architecture
- **MCP Server**: Model Context Protocol implementation
- **Repository Analysis Engine**: Multi-layered project analysis
- **SSG Recommendation Engine**: Data-driven static site generator selection
- **Documentation Generation**: Intelligent content creation
- **Deployment Automation**: Automated GitHub Pages deployment
### Intelligence System (Phase 2)
- **Memory System**: Historical data and pattern learning
- **User Preferences**: Personalized recommendations
- **Deployment Analytics**: Success pattern analysis
- **Smart Scoring**: Intelligent SSG scoring based on historical data
## Integration Patterns
### MCP Integration
DocuMCP integrates seamlessly with:
- **Claude Desktop**: AI assistant integration
- **GitHub Copilot**: Development environment integration
- **Other MCP Clients**: Broad compatibility through protocol compliance
### Development Workflow
- **Repository Analysis**: Understand project structure and needs
- **SSG Recommendation**: Select optimal static site generator
- **Documentation Generation**: Create comprehensive documentation
- **Deployment**: Automated deployment to GitHub Pages
## Research Foundation
DocuMCP is built on extensive research across multiple domains:
- **Repository Analysis**: Multi-layered analysis techniques
- **SSG Performance**: Comprehensive static site generator analysis
- **Documentation Patterns**: Diataxis framework integration
- **Deployment Optimization**: GitHub Pages deployment best practices
- **API Design**: Model Context Protocol best practices
## Future Directions
### Planned Enhancements
- **Advanced AI Integration**: Enhanced machine learning capabilities
- **Real-time Collaboration**: Multi-user documentation workflows
- **Extended Platform Support**: Support for additional deployment platforms
- **Advanced Analytics**: Comprehensive documentation analytics
### Research Areas
- **Cross-Domain Integration**: Seamless workflow integration
- **Performance Optimization**: Advanced performance tuning
- **User Experience**: Enhanced user interaction patterns
- **Scalability**: Large-scale deployment management
## Philosophy
DocuMCP embodies the principle that documentation should be:
- **Intelligent**: AI-powered analysis and recommendations
- **Automated**: Minimal manual intervention required
- **Comprehensive**: Complete documentation lifecycle coverage
- **Accessible**: Easy to use for developers of all skill levels
- **Reliable**: Consistent, high-quality results
## Related Documentation
- [Tutorials](../tutorials/) - Step-by-step guides
- [How-to Guides](../how-to/) - Task-specific instructions
- [Reference](../reference/) - Technical API reference
- [Architecture Decision Records](../adrs/) - Design decisions and rationale
```
--------------------------------------------------------------------------------
/docs/how-to/custom-domains.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.950Z"
last_validated: "2025-11-20T00:46:21.950Z"
auto_updated: false
update_frequency: monthly
---
# How to Set Up Custom Domains
This guide shows you how to configure custom domains for your DocuMCP-deployed documentation site.
## Quick Setup
```bash
# Prompt DocuMCP:
"set up custom domain for my documentation site"
```
## Custom Domain Overview
DocuMCP supports custom domain configuration for professional documentation sites:
### Domain Types
- **Subdomains**: `docs.yourcompany.com`
- **Root Domains**: `yourcompany.com`
- **Path-based**: `yourcompany.com/docs`
### Requirements
- Domain ownership verification
- DNS configuration access
- GitHub Pages enabled
- SSL certificate (automatic with GitHub Pages)
## Setup Methods
### Method 1: Automated Setup (Recommended)
```bash
# Complete domain setup:
"configure custom domain docs.example.com for my site"
```
This will:
1. Guide you through DNS configuration
2. Set up GitHub Pages custom domain
3. Configure SSL certificate
4. Test domain connectivity
5. Set up redirects if needed
### Method 2: Manual Configuration
#### Step 1: DNS Configuration
Add the following DNS records to your domain:
**For Subdomain (docs.example.com):**
```
Type: CNAME
Name: docs
Value: yourusername.github.io
```
> **Note**: Replace `yourusername` with your GitHub username or organization name.
**For Root Domain (example.com):**
```
Type: A
Name: @
Value: 185.199.108.153
Value: 185.199.109.153
Value: 185.199.110.153
Value: 185.199.111.153
```
#### Step 2: GitHub Pages Configuration
1. Go to your repository settings
2. Navigate to "Pages" section
3. Enter your custom domain
4. Enable "Enforce HTTPS"
#### Step 3: Verification
```bash
# Verify domain setup:
"verify my custom domain configuration"
```
## Domain Configuration Examples
### Subdomain Setup
```yaml
# Custom domain configuration
domain:
type: subdomain
name: "docs.example.com"
redirects:
- from: "example.com/docs"
to: "docs.example.com"
```
### Root Domain Setup
```yaml
# Root domain configuration
domain:
type: root
name: "example.com"
path: "/docs"
ssl: true
```
## Advanced Configuration
### Multiple Domains
```bash
# Set up multiple domains:
"configure domains docs.example.com and help.example.com"
```
### Redirects
```bash
# Set up redirects:
"redirect old-domain.com to new-domain.com"
```
### SSL Configuration
```bash
# Verify SSL setup:
"check SSL certificate for my domain"
```
## Troubleshooting
### Common Issues
**Problem**: Domain not resolving
**Solution**: Check DNS propagation (up to 48 hours)
**Problem**: SSL certificate issues
**Solution**: Verify GitHub Pages settings and DNS
**Problem**: Redirects not working
**Solution**: Check CNAME vs A record configuration
**Problem**: Mixed content warnings
**Solution**: Ensure all resources use HTTPS
### DNS Troubleshooting
```bash
# Check DNS propagation:
dig docs.example.com
nslookup docs.example.com
# Test connectivity:
curl -I https://docs.example.com
```
## Security Considerations
### HTTPS Enforcement
- Always enable HTTPS in GitHub Pages
- Use HSTS headers for security
- Monitor certificate expiration
### Access Control
- Configure appropriate permissions
- Set up authentication if needed
- Monitor access logs
## Performance Optimization
### CDN Configuration
```bash
# Optimize with CDN:
"set up CDN for my custom domain"
```
### Caching Headers
```yaml
# Cache configuration
caching:
static_assets: "1 year"
html_pages: "1 hour"
api_responses: "5 minutes"
```
## Monitoring
### Domain Health
```bash
# Monitor domain health:
"set up monitoring for my custom domain"
```
### SSL Monitoring
```bash
# Monitor SSL certificate:
"monitor SSL certificate for my domain"
```
## Best Practices
1. **Use Subdomains**: Easier to manage than root domains
2. **Enable HTTPS**: Essential for security and SEO
3. **Set Up Redirects**: Maintain old URLs for SEO
4. **Monitor Uptime**: Track domain availability
5. **Document Changes**: Keep DNS records documented
## Next Steps
- [Site Monitoring](site-monitoring.md)
- [SEO Optimization](seo-optimization.md)
- [Analytics Setup](analytics-setup.md)
- [Performance Optimization](performance-optimization.md)
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "documcp",
"version": "0.5.2",
"description": "Intelligent MCP server for GitHub Pages documentation deployment",
"main": "dist/index.js",
"type": "module",
"bin": {
"documcp": "./dist/index.js"
},
"scripts": {
"build": "tsc",
"dev": "tsx watch src/index.ts",
"dev:inspect": "npx @modelcontextprotocol/inspector dist/index.js",
"build:inspect": "npm run build && npm run dev:inspect",
"start": "node dist/index.js",
"test": "jest",
"test:coverage": "jest --coverage",
"test:performance": "jest --testPathPattern=benchmarks",
"test:ci": "jest --coverage --ci --watchAll=false --forceExit",
"lint": "eslint . --ext .ts",
"lint:fix": "eslint . --ext .ts --fix",
"format": "prettier --write \"src/**/*.ts\"",
"format:check": "prettier --check \"src/**/*.ts\"",
"typecheck": "tsc --noEmit",
"validate:rules": "npm run lint && npm run typecheck && npm run test:coverage",
"security:check": "npm audit --audit-level=moderate",
"ci": "npm run typecheck && npm run lint && npm run test:ci && npm run build",
"commitlint": "commitlint --from HEAD~1 --to HEAD --verbose",
"release": "standard-version",
"release:minor": "standard-version --release-as minor",
"release:major": "standard-version --release-as major",
"release:patch": "standard-version --release-as patch",
"docs:generate": "typedoc",
"docs:watch": "typedoc --watch",
"release:dry-run": "standard-version --dry-run",
"prepare": "husky",
"benchmark:run": "tsx src/scripts/benchmark.ts run",
"benchmark:current": "tsx src/scripts/benchmark.ts current",
"benchmark:create-config": "tsx src/scripts/benchmark.ts create-config",
"benchmark:help": "tsx src/scripts/benchmark.ts help",
"docs:check-links": "tsx src/scripts/link-checker.ts",
"docs:check-links:markdown": "markdown-link-check docs/**/*.md --config .markdown-link-check.json",
"docs:check-links:external": "tsx src/scripts/link-checker.ts --external true --internal false",
"docs:check-links:internal": "tsx src/scripts/link-checker.ts --external false --internal true",
"docs:check-links:ci": "tsx src/scripts/link-checker.ts --env ci",
"docs:check-links:all": "npm run docs:check-links:markdown && npm run docs:check-links",
"docs:validate": "./test-docs.sh",
"docs:test": "npm run docs:check-links:all && npm run docs:validate",
"docs:start": "cd docs && npm start",
"docs:build": "cd docs && npm run build",
"docs:serve": "cd docs && npm run serve"
},
"keywords": [
"mcp",
"documentation",
"github-pages",
"static-site-generator",
"diataxis"
],
"author": "Tosin Akinosho",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/tosin2013/documcp.git"
},
"bugs": {
"url": "https://github.com/tosin2013/documcp/issues"
},
"homepage": "https://github.com/tosin2013/documcp#readme",
"dependencies": {
"@modelcontextprotocol/sdk": "^0.6.0",
"@typescript-eslint/typescript-estree": "^8.44.0",
"globby": "^14.1.0",
"gray-matter": "^4.0.3",
"linkinator": "^6.1.4",
"simple-git": "^3.30.0",
"tmp": "^0.2.5",
"tree-sitter-bash": "^0.25.0",
"tree-sitter-go": "^0.25.0",
"tree-sitter-java": "^0.23.5",
"tree-sitter-javascript": "^0.25.0",
"tree-sitter-python": "^0.25.0",
"tree-sitter-ruby": "^0.23.1",
"tree-sitter-rust": "^0.24.0",
"tree-sitter-typescript": "^0.23.2",
"tree-sitter-yaml": "^0.5.0",
"web-tree-sitter": "^0.25.9",
"zod": "^3.22.4",
"zod-to-json-schema": "^3.24.6"
},
"devDependencies": {
"@commitlint/cli": "^19.8.1",
"@commitlint/config-conventional": "^19.8.1",
"@types/jest": "^29.5.11",
"@types/node": "^20.11.0",
"@types/tmp": "^0.2.6",
"@typescript-eslint/eslint-plugin": "^6.19.0",
"@typescript-eslint/parser": "^6.19.0",
"eslint": "^8.56.0",
"husky": "^9.1.7",
"jest": "^29.7.0",
"markdown-link-check": "^3.12.2",
"prettier": "^3.2.4",
"standard-version": "^9.5.0",
"ts-jest": "^29.1.1",
"tsx": "^4.7.0",
"typedoc": "^0.28.13",
"typescript": "^5.3.3"
},
"engines": {
"node": ">=20.0.0"
},
"overrides": {
"markdown-link-check": {
"xmlbuilder2": "^4.0.0"
}
}
}
```
--------------------------------------------------------------------------------
/tests/tools/simple-coverage.test.ts:
--------------------------------------------------------------------------------
```typescript
// Simple coverage tests for all tools
import { promises as fs } from "fs";
import path from "path";
import os from "os";
// Import all tools to increase coverage
import { recommendSSG } from "../../src/tools/recommend-ssg";
import { generateConfig } from "../../src/tools/generate-config";
import { setupStructure } from "../../src/tools/setup-structure";
import { deployPages } from "../../src/tools/deploy-pages";
import { verifyDeployment } from "../../src/tools/verify-deployment";
describe("Simple Tool Coverage Tests", () => {
let tempDir: string;
const originalCwd = process.cwd();
beforeAll(async () => {
tempDir = path.join(os.tmpdir(), "simple-coverage");
await fs.mkdir(tempDir, { recursive: true });
// Clean up any existing KG data in temp directory
const kgDir = path.join(tempDir, ".documcp", "memory");
try {
await fs.rm(kgDir, { recursive: true, force: true });
} catch {
// Ignore if doesn't exist
}
});
afterAll(async () => {
try {
await fs.rm(tempDir, { recursive: true, force: true });
} catch (error) {
// Cleanup errors are okay
}
});
it("should test recommend_ssg tool", async () => {
// Change to temp directory to avoid KG conflicts
process.chdir(tempDir);
try {
const result = await recommendSSG({
analysisId: "test-123",
});
expect(result.content).toBeDefined();
expect(result.content.length).toBeGreaterThan(0);
} finally {
process.chdir(originalCwd);
}
});
it("should test generate_config for each SSG", async () => {
const ssgs = [
"docusaurus",
"mkdocs",
"hugo",
"jekyll",
"eleventy",
] as const;
for (const ssg of ssgs) {
const outputPath = path.join(tempDir, ssg);
const result = await generateConfig({
ssg,
projectName: `Test ${ssg}`,
outputPath,
});
expect(result.content).toBeDefined();
// Verify files were created
const files = await fs.readdir(outputPath);
expect(files.length).toBeGreaterThan(0);
}
});
it("should test setup_structure tool", async () => {
const structurePath = path.join(tempDir, "structure-test");
const result = await setupStructure({
path: structurePath,
ssg: "docusaurus",
includeExamples: true,
});
expect(result.content).toBeDefined();
// Check Diataxis categories were created
const categories = ["tutorials", "how-to", "reference", "explanation"];
for (const category of categories) {
const categoryPath = path.join(structurePath, category);
const stat = await fs.stat(categoryPath);
expect(stat.isDirectory()).toBe(true);
}
});
it("should test deploy_pages tool", async () => {
const deployPath = path.join(tempDir, "deploy-test");
const result = await deployPages({
repository: deployPath,
ssg: "docusaurus",
branch: "gh-pages",
});
expect(result.content).toBeDefined();
// Check workflow was created
const workflowPath = path.join(
deployPath,
".github",
"workflows",
"deploy-docs.yml",
);
const stat = await fs.stat(workflowPath);
expect(stat.isFile()).toBe(true);
});
it("should test verify_deployment tool", async () => {
const verifyPath = path.join(tempDir, "verify-test");
await fs.mkdir(verifyPath, { recursive: true });
const result = await verifyDeployment({
repository: verifyPath,
});
expect(result.content).toBeDefined();
expect(result.content.length).toBeGreaterThan(0);
// Should contain check results with recommendation icons
const fullText = result.content.map((c) => c.text).join(" ");
expect(fullText).toContain("🔴"); // Should contain recommendation icons
});
it("should test error cases", async () => {
// Test generate_config with invalid path
try {
await generateConfig({
ssg: "docusaurus",
projectName: "Test",
outputPath: "/invalid/path/that/should/fail",
});
} catch (error) {
expect(error).toBeDefined();
}
// Test setup_structure error handling
const result = await setupStructure({
path: path.join(tempDir, "new-structure"),
ssg: "mkdocs",
includeExamples: false,
});
expect(result.content).toBeDefined();
});
});
```
--------------------------------------------------------------------------------
/src/tools/manage-preferences.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Manage User Preferences Tool
* Phase 2.2: User Preference Management
*
* MCP tool for viewing and updating user preferences
*/
import { z } from "zod";
import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
import { getUserPreferenceManager } from "../memory/user-preferences.js";
const inputSchema = z.object({
action: z.enum([
"get",
"update",
"reset",
"export",
"import",
"recommendations",
]),
userId: z.string().optional().default("default"),
preferences: z
.object({
preferredSSGs: z.array(z.string()).optional(),
documentationStyle: z
.enum(["minimal", "comprehensive", "tutorial-heavy"])
.optional(),
expertiseLevel: z
.enum(["beginner", "intermediate", "advanced"])
.optional(),
preferredTechnologies: z.array(z.string()).optional(),
preferredDiataxisCategories: z
.array(z.enum(["tutorials", "how-to", "reference", "explanation"]))
.optional(),
autoApplyPreferences: z.boolean().optional(),
})
.optional(),
json: z.string().optional(), // For import action
});
export async function managePreferences(
args: unknown,
): Promise<{ content: any[] }> {
const startTime = Date.now();
try {
const { action, userId, preferences, json } = inputSchema.parse(args);
const manager = await getUserPreferenceManager(userId);
let result: any;
let actionDescription: string;
switch (action) {
case "get":
result = await manager.getPreferences();
actionDescription = "Retrieved user preferences";
break;
case "update":
if (!preferences) {
throw new Error("Preferences object required for update action");
}
result = await manager.updatePreferences(preferences);
actionDescription = "Updated user preferences";
break;
case "reset":
result = await manager.resetPreferences();
actionDescription = "Reset preferences to defaults";
break;
case "export": {
const exportedJson = await manager.exportPreferences();
result = { exported: exportedJson };
actionDescription = "Exported preferences as JSON";
break;
}
case "import": {
if (!json) {
throw new Error("JSON string required for import action");
}
result = await manager.importPreferences(json);
actionDescription = "Imported preferences from JSON";
break;
}
case "recommendations": {
const recommendations = await manager.getSSGRecommendations();
result = {
recommendations,
summary: `Found ${recommendations.length} SSG recommendation(s) based on usage history`,
};
actionDescription = "Retrieved SSG recommendations";
break;
}
default:
throw new Error(`Unknown action: ${action}`);
}
const response: MCPToolResponse<any> = {
success: true,
data: result,
metadata: {
toolVersion: "1.0.0",
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString(),
},
recommendations: [
{
type: "info",
title: actionDescription,
description: `User preferences ${action} completed successfully for user: ${userId}`,
},
],
};
// Add context-specific next steps
if (action === "get" || action === "recommendations") {
response.nextSteps = [
{
action: "Update Preferences",
toolRequired: "manage_preferences",
description: "Modify your preferences using the update action",
priority: "medium",
},
];
} else if (action === "update" || action === "import") {
response.nextSteps = [
{
action: "Test Recommendations",
toolRequired: "recommend_ssg",
description: "See how your preferences affect SSG recommendations",
priority: "high",
},
];
}
return formatMCPResponse(response);
} catch (error) {
const errorResponse: MCPToolResponse = {
success: false,
error: {
code: "PREFERENCE_MANAGEMENT_FAILED",
message: `Failed to manage preferences: ${error}`,
resolution:
"Check that action and parameters are valid, and user ID exists",
},
metadata: {
toolVersion: "1.0.0",
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString(),
},
};
return formatMCPResponse(errorResponse);
}
}
```
--------------------------------------------------------------------------------
/docs/how-to/seo-optimization.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.955Z"
last_validated: "2025-11-20T00:46:21.955Z"
auto_updated: false
update_frequency: monthly
---
# How to Manage Documentation SEO
This guide shows you how to use DocuMCP's sitemap management tools to improve your documentation's search engine visibility.
## Quick Setup
```bash
# Generate sitemap for your documentation:
"generate sitemap for my documentation"
```
## SEO Overview
DocuMCP provides basic SEO support through sitemap management:
### Available SEO Features
- **XML Sitemap Generation**: Automatic sitemap creation for documentation
- **Sitemap Validation**: Verify sitemap structure and URLs
- **Link Discovery**: Automatic detection of documentation pages
- **GitHub Pages Integration**: Optimized for GitHub Pages deployment
### SEO Benefits
- **Search Engine Discovery**: Help search engines find your documentation
- **Crawling Efficiency**: Provide structured navigation for crawlers
- **URL Organization**: Maintain clean URL structure
- **Update Tracking**: Track when pages were last modified
## Setup Methods
### Method 1: Automatic Sitemap Generation
```bash
# Generate sitemap for your documentation:
"generate sitemap for my documentation"
```
This will:
1. Scan your documentation directory
2. Discover all markdown and HTML files
3. Generate XML sitemap with proper URLs
4. Include last modified dates from git history
5. Validate sitemap structure
### Method 2: Manual Sitemap Management
#### Step 1: Generate Sitemap
```bash
# Create XML sitemap:
"create sitemap for my documentation with base URL https://mydocs.com"
```
#### Step 2: Validate Sitemap
```bash
# Validate existing sitemap:
"validate my documentation sitemap"
```
#### Step 3: Update Sitemap
```bash
# Update sitemap with new content:
"update my documentation sitemap"
```
## Sitemap Management
### Using MCP Tools
```typescript
// Generate sitemap using MCP tools
import { manageSitemap } from "./dist/tools/manage-sitemap.js";
// Generate new sitemap
const sitemap = await manageSitemap({
action: "generate",
docsPath: "./docs",
baseUrl: "https://mydocs.github.io/repo",
});
// Validate existing sitemap
const validation = await manageSitemap({
action: "validate",
docsPath: "./docs",
});
// Update sitemap with new content
const update = await manageSitemap({
action: "update",
docsPath: "./docs",
baseUrl: "https://mydocs.github.io/repo",
});
```
### Sitemap Configuration
```yaml
# Sitemap generation settings
sitemap:
base_url: "https://mydocs.github.io/repo"
include_patterns:
- "**/*.md"
- "**/*.html"
exclude_patterns:
- "node_modules/**"
- ".git/**"
update_frequency: "weekly"
use_git_history: true
```
## Best Practices
### Sitemap Management
1. **Regular Updates**: Regenerate sitemap when adding new content
2. **Proper URLs**: Ensure all URLs in sitemap are accessible
3. **Git Integration**: Use git history for accurate last modified dates
4. **Validation**: Always validate sitemap after generation
5. **Submit to Search Engines**: Submit sitemap to Google Search Console
### URL Structure
- Use clean, descriptive URLs
- Maintain consistent URL patterns
- Avoid deep nesting when possible
- Include keywords in URLs naturally
### Content Organization
- Structure content logically
- Use clear headings and navigation
- Maintain consistent documentation patterns
- Link related content appropriately
## Troubleshooting
### Common Issues
**Problem**: Sitemap not generating
**Solution**: Check documentation directory permissions and file patterns
**Problem**: Invalid URLs in sitemap
**Solution**: Verify base URL configuration and file paths
**Problem**: Sitemap not updating
**Solution**: Ensure git history is accessible for last modified dates
**Problem**: Search engines not finding pages
**Solution**: Submit sitemap to Google Search Console and verify accessibility
### Sitemap Debugging
```bash
# Debug sitemap issues:
"validate my sitemap and check for errors"
```
## Sitemap Tools
### Built-in DocuMCP Tools
- **Sitemap Generation**: Create XML sitemaps automatically
- **Sitemap Validation**: Verify sitemap structure and URLs
- **Link Discovery**: Find all documentation pages
- **Git Integration**: Use git history for modification dates
### MCP Tools Available
- `manage_sitemap`: Generate, validate, and update sitemaps
- `check_documentation_links`: Verify all links work correctly
- `validate_content`: Check documentation accuracy
## Next Steps
- [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
- [Site Monitoring](site-monitoring.md)
- [Custom Domains](custom-domains.md)
- [Troubleshooting](troubleshooting.md)
```
--------------------------------------------------------------------------------
/tests/memory/knowledge-graph-enhanced.test.ts:
--------------------------------------------------------------------------------
```typescript
import { promises as fs } from "fs";
import { join } from "path";
import { tmpdir } from "os";
import { KnowledgeGraph } from "../../src/memory/knowledge-graph.js";
import { MemoryManager } from "../../src/memory/manager.js";
describe("Knowledge Graph Basic Tests", () => {
let tempDir: string;
let memoryManager: MemoryManager;
let knowledgeGraph: KnowledgeGraph;
beforeEach(async () => {
tempDir = join(
tmpdir(),
`test-kg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
);
await fs.mkdir(tempDir, { recursive: true });
memoryManager = new MemoryManager(tempDir);
await memoryManager.initialize();
knowledgeGraph = new KnowledgeGraph(memoryManager);
await knowledgeGraph.initialize();
// Add test data to memory manager
await memoryManager.remember(
"analysis",
{
projectType: "javascript",
complexity: "medium",
framework: "react",
technologies: ["webpack", "babel", "jest"],
},
{
projectId: "project-1",
tags: ["frontend", "spa"],
},
);
await memoryManager.remember(
"recommendation",
{
ssg: "docusaurus",
confidence: 0.9,
reasons: ["React ecosystem", "Good documentation features"],
},
{
projectId: "project-1",
tags: ["react", "documentation"],
},
);
});
afterEach(async () => {
try {
await fs.rm(tempDir, { recursive: true });
} catch {
// Ignore cleanup errors
}
});
describe("Basic Functionality", () => {
it("should initialize knowledge graph", async () => {
expect(knowledgeGraph).toBeDefined();
});
it("should build graph from memories", async () => {
await knowledgeGraph.buildFromMemories();
const stats = await knowledgeGraph.getStatistics();
expect(stats).toBeDefined();
expect(typeof stats.nodeCount).toBe("number");
expect(typeof stats.edgeCount).toBe("number");
expect(stats.nodeCount).toBeGreaterThanOrEqual(0);
});
it("should get all nodes", async () => {
await knowledgeGraph.buildFromMemories();
const nodes = await knowledgeGraph.getAllNodes();
expect(Array.isArray(nodes)).toBe(true);
expect(nodes.length).toBeGreaterThanOrEqual(0);
});
it("should get all edges", async () => {
await knowledgeGraph.buildFromMemories();
const edges = await knowledgeGraph.getAllEdges();
expect(Array.isArray(edges)).toBe(true);
expect(edges.length).toBeGreaterThanOrEqual(0);
});
it("should get connections for a node", async () => {
await knowledgeGraph.buildFromMemories();
const nodes = await knowledgeGraph.getAllNodes();
if (nodes.length > 0) {
const connections = await knowledgeGraph.getConnections(nodes[0].id);
expect(Array.isArray(connections)).toBe(true);
}
});
});
describe("Data Management", () => {
it("should save and load from memory", async () => {
await knowledgeGraph.buildFromMemories();
// Save the current state
await knowledgeGraph.saveToMemory();
// Create new instance and load
const newKG = new KnowledgeGraph(memoryManager);
await newKG.initialize();
await newKG.loadFromMemory();
const originalStats = await knowledgeGraph.getStatistics();
const loadedStats = await newKG.getStatistics();
expect(loadedStats.nodeCount).toBe(originalStats.nodeCount);
});
it("should remove nodes", async () => {
await knowledgeGraph.buildFromMemories();
const nodes = await knowledgeGraph.getAllNodes();
if (nodes.length > 0) {
const initialCount = nodes.length;
const removed = await knowledgeGraph.removeNode(nodes[0].id);
expect(removed).toBe(true);
const remainingNodes = await knowledgeGraph.getAllNodes();
expect(remainingNodes.length).toBe(initialCount - 1);
}
});
});
describe("Performance", () => {
it("should handle multiple memories efficiently", async () => {
// Add more test data
const promises = [];
for (let i = 0; i < 20; i++) {
promises.push(
memoryManager.remember(
"analysis",
{
projectType: i % 2 === 0 ? "javascript" : "python",
complexity: ["low", "medium", "high"][i % 3],
index: i,
},
{
projectId: `project-${Math.floor(i / 5)}`,
tags: [`tag-${i % 3}`],
},
),
);
}
await Promise.all(promises);
const startTime = Date.now();
await knowledgeGraph.buildFromMemories();
const buildTime = Date.now() - startTime;
expect(buildTime).toBeLessThan(2000); // Should complete within 2 seconds
const stats = await knowledgeGraph.getStatistics();
expect(stats.nodeCount).toBeGreaterThanOrEqual(0);
});
});
});
```
--------------------------------------------------------------------------------
/src/types/api.ts:
--------------------------------------------------------------------------------
```typescript
// Standardized API response types per DEVELOPMENT_RULES.md CODE-002
export interface MCPToolResponse<T = any> {
success: boolean;
data?: T;
error?: ErrorDetails;
metadata: ResponseMetadata;
recommendations?: Recommendation[];
nextSteps?: NextStep[];
}
export interface ErrorDetails {
code: string;
message: string;
details?: any;
resolution?: string;
}
export interface ResponseMetadata {
toolVersion: string;
executionTime: number;
timestamp: string;
analysisId?: string;
}
export interface Recommendation {
type: "info" | "warning" | "critical";
title: string;
description: string;
action?: string;
}
export interface NextStep {
action: string;
toolRequired?: string;
description?: string;
priority?: "low" | "medium" | "high";
}
// Additional types for README health analysis and best practices
// These types prevent compilation errors when health analysis functionality is added
export interface HealthAnalysis {
score: number;
issues: HealthIssue[];
recommendations: string[];
metadata: {
checkDate: string;
version: string;
};
}
export interface HealthIssue {
type: "critical" | "warning" | "info";
message: string;
section?: string;
line?: number;
}
export interface ChecklistItem {
id: string;
title: string;
description: string;
completed: boolean;
required: boolean;
category: string;
}
export interface BestPracticesReport {
items: ChecklistItem[];
score: number;
categories: {
[category: string]: {
total: number;
completed: number;
score: number;
};
};
recommendations: string[];
}
// MCP content format wrapper for backward compatibility
export interface MCPContentWrapper {
content: Array<{
type: "text";
text: string;
}>;
isError?: boolean;
}
// Helper to convert MCPToolResponse to MCP format
export function formatMCPResponse<T>(
response: MCPToolResponse<T>,
options?: { fullResponse?: boolean },
): MCPContentWrapper {
const content: Array<{ type: "text"; text: string }> = [];
// For backward compatibility: by default, use rich formatting with metadata, recommendations, etc.
// If fullResponse is true (Phase 3 tools), include the full response object as JSON
if (options?.fullResponse) {
content.push({
type: "text",
text: JSON.stringify(response, null, 2),
});
} else {
// Legacy format with rich formatting (original behavior)
if (response.success) {
// Main data response
if (response.data) {
content.push({
type: "text",
text: JSON.stringify(response.data, null, 2),
});
} else {
content.push({
type: "text",
text: "Operation completed successfully",
});
}
// Metadata section
content.push({
type: "text",
text: `\nExecution completed in ${response.metadata.executionTime}ms at ${response.metadata.timestamp}`,
});
// Recommendations section with emoji icons
if (response.recommendations?.length) {
content.push({
type: "text",
text:
"\nRecommendations:\n" +
response.recommendations
.map(
(r) =>
`${getRecommendationIcon(r.type)} ${r.title}: ${
r.description
}`,
)
.join("\n"),
});
}
// Next steps section with arrow symbols
if (response.nextSteps?.length) {
content.push({
type: "text",
text:
"\nNext Steps:\n" +
response.nextSteps
.map((s) => {
let stepText = `→ ${s.action}`;
if (s.toolRequired) {
stepText += ` (use ${s.toolRequired}`;
if (s.description) {
stepText += `: ${s.description}`;
}
stepText += ")";
} else if (s.description) {
stepText += `: ${s.description}`;
}
return stepText;
})
.join("\n"),
});
}
} else if (response.error) {
// Error responses need to be JSON for programmatic error handling
content.push({
type: "text",
text: JSON.stringify(response, null, 2),
});
}
}
return {
content,
isError: !response.success,
};
}
function getRecommendationIcon(type: Recommendation["type"]): string {
switch (type) {
case "info":
return "ℹ️";
case "warning":
return "⚠️";
case "critical":
return "🔴";
default:
return "•";
}
}
// Utility functions for type conversions to prevent common type errors
export function convertBestPracticesReportToChecklistItems(
report: BestPracticesReport,
): ChecklistItem[] {
return report.items;
}
export function generateHealthRecommendations(
analysis: HealthAnalysis,
): string[] {
return analysis.recommendations;
}
```
--------------------------------------------------------------------------------
/tests/memory/temporal-analysis.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Basic unit tests for Temporal Memory Analysis System
* Tests core temporal analysis functionality
* Part of Issue #55 - Advanced Memory Components Unit Tests
*/
import { promises as fs } from "fs";
import path from "path";
import os from "os";
import { MemoryManager } from "../../src/memory/manager.js";
import {
TemporalMemoryAnalysis,
TimeWindow,
TemporalPattern,
TemporalMetrics,
TemporalQuery,
TemporalInsight,
} from "../../src/memory/temporal-analysis.js";
describe("TemporalMemoryAnalysis", () => {
let tempDir: string;
let memoryManager: MemoryManager;
let temporalAnalysis: TemporalMemoryAnalysis;
beforeEach(async () => {
// Create unique temp directory for each test
tempDir = path.join(
os.tmpdir(),
`temporal-analysis-test-${Date.now()}-${Math.random()
.toString(36)
.substr(2, 9)}`,
);
await fs.mkdir(tempDir, { recursive: true });
memoryManager = new MemoryManager(tempDir);
await memoryManager.initialize();
// Create required dependencies for TemporalMemoryAnalysis
const storage = (memoryManager as any).storage;
const learningSystem = {
learn: jest.fn(),
predict: jest.fn(),
adaptModel: jest.fn(),
};
const knowledgeGraph = {
addNode: jest.fn(),
addEdge: jest.fn(),
findPaths: jest.fn(),
};
temporalAnalysis = new TemporalMemoryAnalysis(
storage,
memoryManager,
learningSystem as any,
knowledgeGraph as any,
);
});
afterEach(async () => {
// Cleanup temp directory
try {
await fs.rm(tempDir, { recursive: true, force: true });
} catch (error) {
// Ignore cleanup errors
}
});
describe("Temporal Analysis Initialization", () => {
test("should create temporal analysis system instance", () => {
expect(temporalAnalysis).toBeDefined();
expect(temporalAnalysis).toBeInstanceOf(TemporalMemoryAnalysis);
});
test("should analyze temporal patterns", async () => {
// Add some test memories
await memoryManager.remember("analysis", {
projectPath: "/test/project",
timestamp: new Date().toISOString(),
});
// Test temporal pattern analysis
const patterns = await temporalAnalysis.analyzeTemporalPatterns();
expect(Array.isArray(patterns)).toBe(true);
});
test("should get temporal metrics", async () => {
// Add test memory
await memoryManager.remember("deployment", {
status: "success",
timestamp: new Date().toISOString(),
});
// Test temporal metrics
const metrics = await temporalAnalysis.getTemporalMetrics();
expect(metrics).toBeDefined();
expect(typeof metrics.activityLevel).toBe("number");
});
test("should predict future activity", async () => {
// Add test memories
await memoryManager.remember("analysis", { test: "data1" });
await memoryManager.remember("analysis", { test: "data2" });
// Test prediction
const prediction = await temporalAnalysis.predictFutureActivity();
expect(prediction).toBeDefined();
expect(typeof prediction.nextActivity.confidence).toBe("number");
});
test("should get temporal insights", async () => {
// Add test memory
await memoryManager.remember("recommendation", {
type: "ssg",
recommendation: "use-hugo",
});
// Test insights
const insights = await temporalAnalysis.getTemporalInsights();
expect(Array.isArray(insights)).toBe(true);
});
});
describe("Temporal Query Support", () => {
test("should handle temporal queries with parameters", async () => {
// Add test data
await memoryManager.remember("analysis", { framework: "react" });
await memoryManager.remember("deployment", { status: "success" });
const query: TemporalQuery = {
granularity: "day",
aggregation: "count",
filters: { types: ["analysis"] },
};
const patterns = await temporalAnalysis.analyzeTemporalPatterns(query);
expect(Array.isArray(patterns)).toBe(true);
const metrics = await temporalAnalysis.getTemporalMetrics(query);
expect(metrics).toBeDefined();
});
});
describe("Error Handling", () => {
test("should handle empty data gracefully", async () => {
// Test with no memories
const patterns = await temporalAnalysis.analyzeTemporalPatterns();
expect(Array.isArray(patterns)).toBe(true);
expect(patterns.length).toBe(0);
const metrics = await temporalAnalysis.getTemporalMetrics();
expect(metrics).toBeDefined();
expect(metrics.activityLevel).toBe(0);
});
test("should handle invalid query parameters", async () => {
const invalidQuery = {
granularity: "invalid" as any,
aggregation: "count" as any,
};
// Should not throw but handle gracefully
await expect(
temporalAnalysis.analyzeTemporalPatterns(invalidQuery),
).resolves.toBeDefined();
});
});
});
```
--------------------------------------------------------------------------------
/setup-precommit.sh:
--------------------------------------------------------------------------------
```bash
#!/bin/bash
# Setup script for DocuMCP pre-commit hooks
# Based on: https://gist.githubusercontent.com/tosin2013/15b1d7bffafe17dff6374edf1530469b/raw/324c60dffb93ddd62c007effc1dbf3918c6483e8/install-precommit-tools.sh
set -e
echo "🚀 Setting up DocuMCP pre-commit hooks..."
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Function to print colored output
print_status() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Check if we're in a git repository
if ! git rev-parse --git-dir > /dev/null 2>&1; then
print_error "This is not a git repository!"
exit 1
fi
# Check if Node.js and npm are installed
if ! command -v node &> /dev/null; then
print_error "Node.js is not installed. Please install Node.js 20+ first."
exit 1
fi
if ! command -v npm &> /dev/null; then
print_error "npm is not installed. Please install npm first."
exit 1
fi
# Check Node.js version
NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 20 ]; then
print_error "Node.js version 20 or higher is required. Current version: $(node --version)"
exit 1
fi
print_status "Node.js version: $(node --version) ✓"
# Install npm dependencies if needed
if [ ! -d "node_modules" ]; then
print_status "Installing npm dependencies..."
npm install
else
print_status "npm dependencies already installed ✓"
fi
# Install pre-commit
print_status "Installing pre-commit..."
if command -v brew &> /dev/null; then
# macOS with Homebrew
if ! command -v pre-commit &> /dev/null; then
print_status "Installing pre-commit via Homebrew..."
brew install pre-commit
else
print_status "pre-commit already installed ✓"
fi
elif command -v pip3 &> /dev/null; then
# Linux/WSL with pip3
if ! command -v pre-commit &> /dev/null; then
print_status "Installing pre-commit via pip3..."
pip3 install --user pre-commit
# Add to PATH if needed
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
print_warning "Adding ~/.local/bin to PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
fi
else
print_status "pre-commit already installed ✓"
fi
elif command -v pipx &> /dev/null; then
# Alternative installation via pipx
if ! command -v pre-commit &> /dev/null; then
print_status "Installing pre-commit via pipx..."
pipx install pre-commit
else
print_status "pre-commit already installed ✓"
fi
else
print_error "Cannot install pre-commit. Please install either:"
print_error " - Homebrew (macOS): brew install pre-commit"
print_error " - pip3: pip3 install --user pre-commit"
print_error " - pipx: pipx install pre-commit"
exit 1
fi
# Verify pre-commit installation
if ! command -v pre-commit &> /dev/null; then
print_error "pre-commit installation failed!"
exit 1
fi
print_success "pre-commit installed: $(pre-commit --version)"
# Install pre-commit hooks
print_status "Installing pre-commit hooks..."
pre-commit install-hooks
# Update Husky pre-commit hook to use pre-commit
if [ -f ".husky/pre-commit" ]; then
if ! grep -q "pre-commit run" .husky/pre-commit; then
print_status "Updating Husky pre-commit hook..."
echo "pre-commit run --all-files" > .husky/pre-commit
chmod +x .husky/pre-commit
else
print_status "Husky pre-commit hook already configured ✓"
fi
else
print_warning "Husky pre-commit hook not found. Creating..."
mkdir -p .husky
echo "pre-commit run --all-files" > .husky/pre-commit
chmod +x .husky/pre-commit
fi
# Test the setup
print_status "Testing pre-commit setup..."
if pre-commit run --all-files > /dev/null 2>&1; then
print_success "Pre-commit hooks are working!"
else
print_warning "Pre-commit hooks encountered some issues (this is normal for first run)"
print_status "Running pre-commit with output for diagnosis..."
pre-commit run --all-files || true
fi
print_success "🎉 Pre-commit setup complete!"
echo
echo "📋 Summary of installed hooks:"
echo " ✅ File integrity checks (trailing whitespace, end-of-file, etc.)"
echo " ✅ YAML/JSON validation"
echo " ✅ Security checks (private keys, large files)"
echo " ✅ ESLint code linting with auto-fix"
echo " ✅ Prettier code formatting"
echo " ✅ TypeScript type checking"
echo " ✅ npm security audit"
echo " ✅ Core Jest tests (stable tests only)"
echo " ✅ Documentation link checking"
echo " ✅ Package.json validation"
echo " ✅ Build verification"
echo
echo "🔧 Usage:"
echo " • Hooks run automatically on every commit"
echo " • Run manually: pre-commit run --all-files"
echo " • Update hooks: pre-commit autoupdate"
echo " • Skip hooks (emergency): git commit --no-verify"
echo
echo "📖 For team members:"
echo " • New team members should run: ./setup-precommit.sh"
echo " • All hooks are configured to match existing npm scripts"
echo " • Hooks focus on code quality without blocking development"
echo
print_success "Happy coding! 🚀"
```
--------------------------------------------------------------------------------
/docs/how-to/performance-optimization.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.953Z"
last_validated: "2025-11-20T00:46:21.953Z"
auto_updated: false
update_frequency: monthly
---
# How to Optimize Documentation Deployment Performance
This guide shows you how to optimize your DocuMCP deployment process for faster builds and better deployment success rates.
## Quick Setup
```bash
# Analyze deployment performance:
"analyze my deployment performance and provide optimization recommendations"
```
## Deployment Performance Overview
DocuMCP tracks deployment performance metrics to help you optimize your documentation build process:
### Key Metrics
- **Build Time**: Time taken for documentation generation
- **Deployment Success Rate**: Percentage of successful deployments
- **SSG Performance**: Static site generator efficiency comparison
- **Error Recovery**: Time to resolve deployment failures
### Performance Benefits
- **Faster Deployments**: Reduced time from commit to live site
- **Higher Success Rates**: More reliable deployment pipeline
- **Better Developer Experience**: Quicker feedback cycles
- **Reduced Resource Usage**: Optimized build processes
## Setup Methods
### Method 1: Deployment Performance Analysis
```bash
# Analyze deployment performance:
"analyze my deployment performance and provide optimization recommendations"
```
This will:
1. Analyze current deployment metrics
2. Compare SSG build times
3. Identify deployment bottlenecks
4. Provide optimization recommendations
5. Track performance improvements
### Method 2: SSG Performance Comparison
#### Step 1: Build Time Analysis
```bash
# Analyze build performance:
"compare build times across different static site generators"
```
#### Step 2: Success Rate Optimization
```bash
# Optimize deployment success:
"analyze deployment failures and suggest improvements"
```
#### Step 3: Performance Monitoring
```bash
# Monitor deployment performance:
"track my deployment performance over time"
```
## Deployment Optimization Techniques
### SSG Selection Optimization
```bash
# Analyze SSG performance:
"compare static site generator build times and success rates"
```
#### SSG Performance Factors
- **Build Speed**: Time to generate documentation
- **Success Rate**: Reliability of builds
- **Resource Usage**: Memory and CPU requirements
- **Feature Support**: Compatibility with documentation needs
### Build Configuration Optimization
```typescript
// Optimize build configuration for faster deployments
const buildConfig = {
// Use faster package managers
packageManager: "pnpm", // or "yarn" for faster installs
// Optimize Node.js version
nodeVersion: "20", // Latest LTS for better performance
// Configure build caching
cache: {
enabled: true,
strategy: "aggressive",
},
};
```
### Deployment Pipeline Optimization
```bash
# Optimize deployment pipeline:
"analyze my deployment pipeline and suggest performance improvements"
```
#### Pipeline Best Practices
- **Parallel Processing**: Run independent tasks concurrently
- **Build Caching**: Cache dependencies and build artifacts
- **Incremental Builds**: Only rebuild changed content
- **Resource Allocation**: Optimize memory and CPU usage
## Troubleshooting
### Common Issues
**Problem**: Slow deployment builds
**Solution**: Analyze SSG performance and switch to faster alternatives
**Problem**: Frequent deployment failures
**Solution**: Review error patterns and optimize build configurations
**Problem**: Inconsistent build times
**Solution**: Enable build caching and optimize dependencies
**Problem**: Resource exhaustion during builds
**Solution**: Optimize memory usage and build parallelization
### Performance Debugging
```bash
# Debug deployment performance issues:
"analyze my deployment bottlenecks and suggest optimizations"
```
## Best Practices
### Deployment Performance Guidelines
1. **Choose Fast SSGs**: Use performance data to select optimal static site generators
2. **Enable Caching**: Implement build caching for faster subsequent deployments
3. **Optimize Dependencies**: Keep dependencies minimal and up-to-date
4. **Monitor Build Times**: Track deployment performance over time
5. **Use Analytics**: Leverage deployment analytics for optimization decisions
### Build Optimization Strategies
1. **Incremental Builds**: Only rebuild changed content when possible
2. **Parallel Processing**: Run independent build tasks concurrently
3. **Resource Management**: Optimize memory and CPU usage during builds
4. **Dependency Caching**: Cache node_modules and build artifacts
5. **Build Environment**: Use optimized build environments and Node.js versions
## Deployment Analytics Tools
### Built-in DocuMCP Analytics
- **Build time tracking**: Monitor deployment speed over time
- **Success rate analysis**: Track deployment reliability
- **SSG performance comparison**: Compare static site generator efficiency
- **Failure pattern analysis**: Identify common deployment issues
### MCP Tools Available
- `analyze_deployments`: Get comprehensive deployment performance analytics
- `deploy_pages`: Track deployment attempts and build times
- `recommend_ssg`: Get performance-based SSG recommendations
## Next Steps
- [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
- [Analytics Setup](analytics-setup.md)
- [Site Monitoring](site-monitoring.md)
- [Troubleshooting](troubleshooting.md)
```
--------------------------------------------------------------------------------
/docs/api/modules.html:
--------------------------------------------------------------------------------
```html
<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>DocuMCP API Documentation - v0.4.1</title><meta name="description" content="Documentation for DocuMCP API Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">DocuMCP API Documentation - v0.4.1</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"></ul><h1>DocuMCP API Documentation - v0.4.1</h1></div><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Variables"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h2>Variables</h2></summary><dl class="tsd-member-summaries"><dt class="tsd-member-summary" id="tools"><span class="tsd-member-summary-name"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Variable"><use href="assets/icons.svg#icon-32"></use></svg><a href="variables/TOOLS.html">TOOLS</a><a href="#tools" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></span></dt><dd class="tsd-member-summary"></dd></dl></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Variables"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Variables</summary><div><a href="#tools"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Variable"><use href="assets/icons.svg#icon-32"></use></svg><span>TOOLS</span></a></div></details></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current">DocuMCP API Documentation - v0.4.1</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
```
--------------------------------------------------------------------------------
/docs/research/domain-3-ssg-recommendation/ssg-performance-analysis.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.966Z"
last_validated: "2025-11-20T00:46:21.966Z"
auto_updated: false
update_frequency: monthly
---
# Static Site Generator Performance Analysis
**Research Date**: 2025-01-14
**Domain**: SSG Recommendation Engine
**Status**: Completed
## Research Overview
Comprehensive analysis of static site generator performance characteristics, build times, and deployment considerations for DocuMCP recommendation engine.
## Key Research Findings
### Build Performance Comparison
Based on CSS-Tricks comprehensive benchmarking study:
| SSG | Language | Small Sites (1-1024 files) | Large Sites (1K-64K files) | Key Characteristics |
| -------------- | -------- | --------------------------------- | ------------------------------- | ------------------------------- |
| **Hugo** | Go | ~250x faster than Gatsby | ~40x faster than Gatsby | Fastest across all scales |
| **Jekyll** | Ruby | Competitive with Eleventy | Slower scaling, Ruby bottleneck | Good for small-medium sites |
| **Eleventy** | Node.js | Fast, lightweight | Good scaling | Excellent developer experience |
| **Gatsby** | React | Slower startup (webpack overhead) | Improves relatively at scale | Rich features, plugin ecosystem |
| **Next.js** | React | Framework overhead | Good with optimization | Hybrid capabilities |
| **Docusaurus** | React | Moderate performance | Documentation optimized | Purpose-built for docs |
### Performance Characteristics Analysis
#### **Tier 1: Speed Champions (Hugo)**
- **Build Time**: Sub-second for small sites, seconds for large sites
- **Scaling**: Linear performance, excellent for content-heavy sites
- **Trade-offs**: Limited plugin ecosystem, steeper learning curve
#### **Tier 2: Balanced Performance (Jekyll, Eleventy)**
- **Build Time**: Fast for small sites, moderate scaling
- **Scaling**: Jekyll hits Ruby performance ceiling, Eleventy scales better
- **Trade-offs**: Good balance of features and performance
#### **Tier 3: Feature-Rich (Gatsby, Next.js, Docusaurus)**
- **Build Time**: Significant webpack/framework overhead
- **Scaling**: Performance gap narrows at scale due to optimizations
- **Trade-offs**: Rich ecosystems, modern features, slower builds
### Real-World Performance Implications
#### **For DocuMCP Recommendation Logic:**
1. **Small Projects** (< 100 pages):
- All SSGs perform adequately
- Developer experience becomes primary factor
- Hugo still 250x faster than Gatsby for simple sites
2. **Medium Projects** (100-1000 pages):
- Performance differences become noticeable
- Hugo maintains significant advantage
- Jekyll starts showing Ruby limitations
3. **Large Projects** (1000+ pages):
- Hugo remains fastest but gap narrows
- Framework-based SSGs benefit from optimizations
- Build time becomes CI/CD bottleneck consideration
### Deployment and CI/CD Considerations
#### **GitHub Actions Build Time Impact**
- **Free Plan Limitations**: 2000 minutes/month
- **Cost Implications**: Slow builds consume more CI time
- **Real Example**: Gatsby site taking 15 minutes vs Hugo taking 30 seconds
#### **Content Editor Experience**
- **Preview Generation**: Fast builds enable quick content previews
- **Development Workflow**: Build speed affects local development experience
- **Incremental Builds**: Framework support varies significantly
### Recommendation Engine Criteria
Based on research findings, DocuMCP should weight these factors:
1. **Project Scale Weight**:
- Small projects: 40% performance, 60% features/DX
- Medium projects: 60% performance, 40% features/DX
- Large projects: 80% performance, 20% features/DX
2. **Team Context Multipliers**:
- Technical team: Favor performance (Hugo/Eleventy)
- Non-technical content creators: Favor ease-of-use (Jekyll/Docusaurus)
- Mixed teams: Balanced approach (Next.js/Gatsby)
3. **Use Case Optimization**:
- **Documentation**: Docusaurus > MkDocs > Hugo
- **Marketing Sites**: Next.js > Gatsby > Hugo
- **Blogs**: Jekyll > Eleventy > Hugo
- **Large Content Sites**: Hugo > Eleventy > Others
## Implementation Recommendations for DocuMCP
### Algorithm Design
```typescript
// Performance scoring algorithm
const calculatePerformanceScore = (projectMetrics: ProjectMetrics) => {
const { pageCount, teamSize, techLevel, updateFrequency } = projectMetrics;
// Scale-based performance weighting
const performanceWeight =
pageCount > 1000 ? 0.8 : pageCount > 100 ? 0.6 : 0.4;
// SSG-specific performance scores (0-100)
const performanceScores = {
hugo: 100,
eleventy: 85,
jekyll: pageCount > 500 ? 60 : 80,
nextjs: 70,
gatsby: pageCount > 1000 ? 65 : 45,
docusaurus: 75,
};
return performanceScores;
};
```
### Research Validation
- ✅ Performance benchmarks analyzed from multiple sources
- ✅ Real-world implications documented
- ✅ Recommendation criteria established
- ⚠️ Needs validation: Edge case performance scenarios
- ⚠️ Needs testing: Algorithm implementation with real project data
## Sources & References
1. CSS-Tricks Comprehensive SSG Build Time Analysis
2. Jamstack.org Performance Surveys
3. GitHub Actions CI/CD Cost Analysis
4. Community Performance Reports (Hugo, Gatsby, Next.js)
```
--------------------------------------------------------------------------------
/src/scripts/benchmark.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
// Performance benchmark CLI script per PERF-001 rules
import { promises as fs } from "fs";
import path from "path";
import { createBenchmarker } from "../benchmarks/performance.js";
interface BenchmarkConfig {
testRepos: Array<{
path: string;
name: string;
expectedSize?: "small" | "medium" | "large";
}>;
outputDir?: string;
verbose?: boolean;
}
async function main() {
const args = process.argv.slice(2);
const command = args[0] || "help";
switch (command) {
case "run":
await runBenchmarks(args.slice(1));
break;
case "current":
await benchmarkCurrentRepo();
break;
case "create-config":
await createDefaultConfig();
break;
case "help":
default:
printHelp();
break;
}
}
async function runBenchmarks(args: string[]) {
const configPath = args[0] || "./benchmark-config.json";
try {
const configContent = await fs.readFile(configPath, "utf-8");
const config: BenchmarkConfig = JSON.parse(configContent);
console.log("🎯 Performance Benchmarking System (PERF-001 Compliance)");
console.log("Target Performance:");
console.log(" • Small repos (<100 files): <1 second");
console.log(" • Medium repos (100-1000 files): <10 seconds");
console.log(" • Large repos (1000+ files): <60 seconds\\n");
const benchmarker = createBenchmarker();
const suite = await benchmarker.runBenchmarkSuite(config.testRepos);
// Print detailed report
benchmarker.printDetailedReport(suite);
// Export results if output directory specified
if (config.outputDir) {
await fs.mkdir(config.outputDir, { recursive: true });
const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
const outputPath = path.join(
config.outputDir,
`benchmark-${timestamp}.json`,
);
await benchmarker.exportResults(suite, outputPath);
console.log(`\\n📄 Results exported to: ${outputPath}`);
}
// Exit with appropriate code
process.exit(suite.overallPassed ? 0 : 1);
} catch (error) {
console.error("❌ Benchmark failed:", error);
console.error(
'\\nTry running "npm run benchmark:create-config" to create a default configuration.',
);
process.exit(1);
}
}
async function benchmarkCurrentRepo() {
console.log("🎯 Benchmarking Current Repository");
console.log("=".repeat(40));
const currentRepo = process.cwd();
const repoName = path.basename(currentRepo);
const benchmarker = createBenchmarker();
try {
console.log(`📊 Analyzing: ${repoName} at ${currentRepo}\\n`);
const result = await benchmarker.benchmarkRepository(
currentRepo,
"standard",
);
// Generate single-repo suite
const suite = benchmarker.generateSuite(`Current Repository: ${repoName}`, [
result,
]);
// Print results
benchmarker.printDetailedReport(suite);
// Export to current directory
const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
const outputPath = `./benchmark-current-${timestamp}.json`;
await benchmarker.exportResults(suite, outputPath);
console.log(`\\n📄 Results saved to: ${outputPath}`);
process.exit(suite.overallPassed ? 0 : 1);
} catch (error) {
console.error("❌ Benchmark failed:", error);
process.exit(1);
}
}
async function createDefaultConfig() {
const defaultConfig: BenchmarkConfig = {
testRepos: [
{
path: ".",
name: "Current Repository",
expectedSize: "small",
},
// Add more test repositories here
// {
// path: "/path/to/medium/repo",
// name: "Medium Test Repo",
// expectedSize: "medium"
// },
// {
// path: "/path/to/large/repo",
// name: "Large Test Repo",
// expectedSize: "large"
// }
],
outputDir: "./benchmark-results",
verbose: true,
};
const configPath = "./benchmark-config.json";
await fs.writeFile(configPath, JSON.stringify(defaultConfig, null, 2));
console.log("✅ Created default benchmark configuration:");
console.log(` ${configPath}`);
console.log("");
console.log("📝 Edit this file to add your test repositories, then run:");
console.log(" npm run benchmark:run");
}
function printHelp() {
console.log("🎯 DocuMCP Performance Benchmarking Tool");
console.log("");
console.log("USAGE:");
console.log(
" npm run benchmark:run [config-file] Run full benchmark suite",
);
console.log(
" npm run benchmark:current Benchmark current repository only",
);
console.log(
" npm run benchmark:create-config Create default configuration",
);
console.log(" npm run benchmark:help Show this help");
console.log("");
console.log("PERFORMANCE TARGETS (PERF-001):");
console.log(" • Small repositories (<100 files): <1 second");
console.log(" • Medium repositories (100-1000 files): <10 seconds");
console.log(" • Large repositories (1000+ files): <60 seconds");
console.log("");
console.log("EXAMPLES:");
console.log(" npm run benchmark:current");
console.log(" npm run benchmark:create-config");
console.log(" npm run benchmark:run ./my-config.json");
}
// Handle unhandled promise rejections
process.on("unhandledRejection", (error) => {
console.error("❌ Unhandled rejection:", error);
process.exit(1);
});
main().catch((error) => {
console.error("❌ Script failed:", error);
process.exit(1);
});
```
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
```yaml
name: Release
on:
push:
tags:
- "v*.*.*"
workflow_dispatch:
inputs:
version_type:
description: "Version bump type"
required: true
default: "patch"
type: choice
options:
- patch
- minor
- major
jobs:
test:
name: Pre-release Tests
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20.x"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Run full test suite
run: npm test -- --coverage
- name: Verify 80% coverage threshold
run: |
coverage=$(npm test -- --coverage --silent | grep "All files" | awk '{print $4}' | sed 's/%//')
if (( $(echo "$coverage < 80" | bc -l) )); then
echo "Coverage $coverage% is below 80% threshold"
exit 1
fi
echo "Coverage $coverage% meets requirement"
- name: Performance benchmarks
run: npm run test:performance
- name: Build verification
run: npm run build
release:
name: Create Release
runs-on: ubuntu-latest
needs: test
permissions:
contents: write
packages: write
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20.x"
cache: "npm"
registry-url: "https://registry.npmjs.org"
- name: Verify NPM Token
run: |
if [ -z "$NODE_AUTH_TOKEN" ]; then
echo "Error: NODE_AUTH_TOKEN is not set"
echo "Please configure NPM_TOKEN in repository secrets"
exit 1
fi
echo "NPM token is configured"
- name: Install dependencies
run: npm ci
- name: Build project
run: npm run build
- name: Generate changelog and release
id: release
run: |
git config --local user.email "[email protected]"
git config --local user.name "GitHub Action"
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
printf "Manual release triggered with version type: %s\n" "${{ github.event.inputs.version_type }}"
npm run "release:${{ github.event.inputs.version_type }}"
# Get the new version and changelog
NEW_VERSION=$(node -p "require('./package.json').version")
printf "new_version=v%s\n" "$NEW_VERSION" >> "$GITHUB_OUTPUT"
# Extract changelog for this version
if [ -f "CHANGELOG.md" ]; then
# Get changelog section for current version
CHANGELOG_CONTENT=$(awk "/## \[$NEW_VERSION\]/{flag=1; next} /## \[/{flag=0} flag" CHANGELOG.md || printf "## Changes\n\nAutomated release %s\n" "$NEW_VERSION")
{
echo "changelog_content<<EOF"
printf "%s\n" "$CHANGELOG_CONTENT"
echo "EOF"
} >> "$GITHUB_OUTPUT"
else
printf "changelog_content=Automated release v%s\n" "$NEW_VERSION" >> "$GITHUB_OUTPUT"
fi
# Push the changes
git push --follow-tags origin main
else
echo "Tag-based release"
tag="${GITHUB_REF#refs/tags/}"
printf "new_version=%s\n" "$tag" >> "$GITHUB_OUTPUT"
printf "changelog_content=Release %s\n" "$tag" >> "$GITHUB_OUTPUT"
fi
- name: Create GitHub Release
uses: ncipollo/release-action@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
tag: ${{ steps.release.outputs.new_version }}
name: Release ${{ steps.release.outputs.new_version }}
body: |
## DocuMCP Release ${{ steps.release.outputs.new_version }}
${{ steps.release.outputs.changelog_content }}
### Installation
```bash
npm install -g documcp@${{ steps.release.outputs.new_version }}
```
### System Requirements
- Node.js 20.x or higher
- npm 9.x or higher
### Quick Start
```bash
# Install globally
npm install -g documcp
# Use with MCP client
documcp analyze-repository --path ./my-project
```
draft: false
prerelease: false
skipIfReleaseExists: true
makeLatest: true
- name: Publish to npm
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
run: |
echo "Publishing to npm..."
npm whoami
npm publish
echo "Successfully published to npm!"
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
docs:
name: Deploy Documentation
runs-on: ubuntu-latest
needs: [test, release]
permissions:
pages: write
id-token: write
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20.x"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Generate API documentation
run: npm run docs:generate
- name: Remove problematic media directory
run: rm -rf docs/api/media
- name: Install Docusaurus dependencies
run: cd docs && npm ci
- name: Copy API documentation to build directory
run: |
mkdir -p docs/build/api
cp -r docs/api/* docs/build/api/
- name: Build Docusaurus site
run: cd docs && npm run build
env:
NODE_ENV: production
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload to GitHub Pages
uses: actions/upload-pages-artifact@v3
with:
path: ./docs/build
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
```
--------------------------------------------------------------------------------
/docs/tutorials/getting-started.md:
--------------------------------------------------------------------------------
```markdown
---
id: getting-started
title: Getting Started with DocuMCP
sidebar_label: Getting Started
documcp:
last_updated: "2025-11-20T00:46:21.972Z"
last_validated: "2025-11-20T00:46:21.972Z"
auto_updated: false
update_frequency: monthly
---
# Getting Started with DocuMCP
This tutorial will guide you through setting up and using DocuMCP's intelligent documentation deployment system with memory-enhanced capabilities.
## Prerequisites
Before you begin, ensure you have:
- Node.js 20.0.0 or higher installed
- Access to a GitHub repository
- Claude Desktop, Cursor, or another MCP-compatible client
- Basic familiarity with documentation workflows
## 🎯 Pro Tip: Reference LLM_CONTEXT.md
When using DocuMCP through an AI assistant, **always reference the LLM_CONTEXT.md file** for comprehensive tool context:
```
@LLM_CONTEXT.md help me set up documentation for my TypeScript project
```
The `LLM_CONTEXT.md` file is auto-generated and contains:
- All 45 tool descriptions and parameters
- Usage examples and workflows
- Memory system documentation
- Phase 3 code-to-docs sync features
**Location**: `/LLM_CONTEXT.md` (in project root)
This ensures your AI assistant has complete context and can provide optimal recommendations.
## Step 1: Initial Repository Analysis
Start by analyzing your repository to understand its characteristics and documentation needs:
```json
{
"path": "/path/to/your/project",
"depth": "standard"
}
```
This will analyze your project and return:
- **Project structure**: File counts, languages used, and organization
- **Dependencies**: Production and development packages detected
- **Documentation status**: Existing docs, README, contributing guidelines
- **Smart recommendations**: Primary language, project type, team size estimates
- **Unique analysis ID**: For use in subsequent steps
Example response snippet:
```json
{
"id": "analysis_abc123xyz",
"structure": {
"totalFiles": 150,
"languages": { ".ts": 45, ".js": 12, ".md": 8 },
"hasTests": true,
"hasCI": true
},
"dependencies": {
"ecosystem": "javascript",
"packages": ["react", "typescript"]
},
"recommendations": {
"primaryLanguage": "typescript",
"projectType": "library"
}
}
```
## Step 2: Memory-Enhanced SSG Recommendation
Next, get intelligent recommendations powered by DocuMCP's memory system:
```json
{
"analysisId": "analysis_abc123xyz",
"preferences": {
"ecosystem": "javascript",
"priority": "features"
}
}
```
The memory system leverages patterns from 130+ previous projects to provide:
- **Confidence-scored recommendations** (e.g., Docusaurus with 85% confidence)
- **Historical success data** (69% deployment success rate insights)
- **Pattern-based insights** (Hugo most common with 98 projects, but Docusaurus optimal for TypeScript)
- **Similar project examples** to learn from successful configurations
Example recommendation response:
```json
{
"recommended": "docusaurus",
"confidence": 0.85,
"reasoning": [
"JavaScript/TypeScript ecosystem detected",
"Modern React-based framework aligns with project stack",
"Strong community support and active development"
],
"alternatives": [
{
"name": "MkDocs",
"score": 0.75,
"pros": ["Simple setup", "Great themes"],
"cons": ["Limited React component support"]
}
]
}
```
## Step 3: Configuration Generation
Generate optimized configuration files for your chosen SSG:
```javascript
// Generate Docusaurus configuration
{
"ssg": "docusaurus",
"projectName": "Your Project",
"projectDescription": "Your project description",
"outputPath": "/path/to/your/repository"
}
```
## Step 4: Diataxis Structure Setup
Create a professional documentation structure following the Diataxis framework:
```javascript
// Setup documentation structure
{
"path": "/path/to/your/repository/docs",
"ssg": "docusaurus",
"includeExamples": true
}
```
This creates four optimized sections following the Diataxis framework:
- **Tutorials**: Learning-oriented guides for skill acquisition (study context)
- **How-to Guides**: Problem-solving guides for specific tasks (work context)
- **Reference**: Information-oriented content for lookup and verification (information context)
- **Explanation**: Understanding-oriented content for context and background (understanding context)
## Step 5: GitHub Pages Deployment
Set up automated deployment with security best practices:
```javascript
// Deploy to GitHub Pages
{
"repository": "/path/to/your/repository",
"ssg": "docusaurus",
"branch": "gh-pages"
}
```
This generates:
- GitHub Actions workflow with OIDC authentication
- Minimal security permissions (pages:write, id-token:write only)
- Automated build and deployment pipeline
## Step 6: Memory System Exploration
Explore DocuMCP's advanced memory capabilities:
```javascript
// Get learning statistics
{
"includeDetails": true
}
// Recall similar projects
{
"query": "typescript documentation",
"type": "recommendation",
"limit": 5
}
```
The memory system provides:
- **Pattern Recognition**: Most successful SSG choices for your project type
- **Historical Insights**: Success rates and common issues
- **Smart Recommendations**: Enhanced suggestions based on similar projects
## Verification
Verify your setup with these checks:
1. **Documentation Structure**: Confirm all Diataxis directories are created
2. **Configuration Files**: Check generated config files are valid
3. **GitHub Actions**: Verify workflow file in `.github/workflows/`
4. **Memory Insights**: Review recommendations and confidence scores
## Summary
In this tutorial, you learned how to:
- **Analyze repositories** with comprehensive project profiling
- **Get intelligent SSG recommendations** using memory-enhanced insights
- **Generate optimized configurations** for your chosen static site generator
- **Create Diataxis-compliant structures** for professional documentation
- **Set up automated GitHub Pages deployment** with security best practices
- **Leverage the memory system** for enhanced recommendations and insights
## Next Steps
- Explore [Memory-Enhanced Workflows](./memory-workflows.md)
- Read [How-To Guides](../how-to/) for specific tasks
- Check the [API Reference](../reference/) for complete tool documentation
- Learn about [Diataxis Framework](../explanation/) principles
```
--------------------------------------------------------------------------------
/tests/memory/contextual-retrieval.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Basic unit tests for Contextual Memory Retrieval System
* Tests basic context-aware memory retrieval capabilities
* Part of Issue #55 - Advanced Memory Components Unit Tests
*/
import { promises as fs } from "fs";
import path from "path";
import os from "os";
import { MemoryManager } from "../../src/memory/manager.js";
import ContextualRetrievalSystem, {
RetrievalContext,
} from "../../src/memory/contextual-retrieval.js";
describe("ContextualRetrievalSystem", () => {
let tempDir: string;
let memoryManager: MemoryManager;
let knowledgeGraph: any;
let contextualRetrieval: ContextualRetrievalSystem;
beforeEach(async () => {
// Create unique temp directory for each test
tempDir = path.join(
os.tmpdir(),
`contextual-retrieval-test-${Date.now()}-${Math.random()
.toString(36)
.substr(2, 9)}`,
);
await fs.mkdir(tempDir, { recursive: true });
memoryManager = new MemoryManager(tempDir);
await memoryManager.initialize();
// Create a mock knowledge graph for testing
knowledgeGraph = {
findRelatedNodes: jest.fn().mockResolvedValue([]),
getConnectionStrength: jest.fn().mockResolvedValue(0.5),
query: jest.fn().mockReturnValue({ nodes: [], edges: [] }),
};
contextualRetrieval = new ContextualRetrievalSystem(
memoryManager,
knowledgeGraph,
);
});
afterEach(async () => {
// Cleanup temp directory
try {
await fs.rm(tempDir, { recursive: true, force: true });
} catch (error) {
// Ignore cleanup errors
}
});
describe("Initialization and Configuration", () => {
test("should create ContextualRetrievalSystem instance", () => {
expect(contextualRetrieval).toBeInstanceOf(ContextualRetrievalSystem);
});
test("should have memory manager and knowledge graph dependencies", () => {
expect(contextualRetrieval).toBeDefined();
// Basic integration test - system should be created with dependencies
});
});
describe("Basic Contextual Retrieval", () => {
beforeEach(async () => {
// Set up test memories for retrieval tests
await memoryManager.remember("analysis", {
projectPath: "/test/typescript-project",
language: "typescript",
framework: "react",
outcome: "success",
recommendation: "Use TypeScript for better type safety",
});
await memoryManager.remember("deployment", {
projectPath: "/test/node-project",
language: "javascript",
framework: "express",
outcome: "success",
recommendation: "Deploy with Docker for consistency",
});
await memoryManager.remember("recommendation", {
projectPath: "/test/python-project",
language: "python",
framework: "django",
outcome: "failure",
recommendation: "Check Python version compatibility",
});
});
test("should retrieve contextual matches based on project context", async () => {
const retrievalContext: RetrievalContext = {
currentProject: {
path: "/test/typescript-project",
language: "typescript",
framework: "react",
},
userIntent: {
action: "analyze",
urgency: "medium",
experience: "intermediate",
},
temporalContext: {
recency: "recent",
},
};
const result = await contextualRetrieval.retrieve(
"typescript react documentation",
retrievalContext,
);
expect(result).toBeDefined();
expect(result.matches).toBeDefined();
expect(Array.isArray(result.matches)).toBe(true);
// Basic structure validation
if (result.matches.length > 0) {
const match = result.matches[0];
expect(match).toHaveProperty("memory");
expect(match).toHaveProperty("relevanceScore");
expect(typeof match.relevanceScore).toBe("number");
}
});
test("should handle different user intents", async () => {
const troubleshootContext: RetrievalContext = {
userIntent: {
action: "troubleshoot",
urgency: "high",
experience: "novice",
},
};
const recommendContext: RetrievalContext = {
userIntent: {
action: "recommend",
urgency: "low",
experience: "expert",
},
};
const troubleshootResult = await contextualRetrieval.retrieve(
"deployment failed",
troubleshootContext,
);
const recommendResult = await contextualRetrieval.retrieve(
"best practices",
recommendContext,
);
expect(troubleshootResult).toBeDefined();
expect(recommendResult).toBeDefined();
expect(Array.isArray(troubleshootResult.matches)).toBe(true);
expect(Array.isArray(recommendResult.matches)).toBe(true);
});
test("should consider temporal context for relevance", async () => {
const recentContext: RetrievalContext = {
temporalContext: {
recency: "recent",
},
};
const historicalContext: RetrievalContext = {
temporalContext: {
recency: "historical",
},
};
const recentResult = await contextualRetrieval.retrieve(
"recent activity",
recentContext,
);
const historicalResult = await contextualRetrieval.retrieve(
"historical data",
historicalContext,
);
expect(recentResult).toBeDefined();
expect(historicalResult).toBeDefined();
expect(Array.isArray(recentResult.matches)).toBe(true);
expect(Array.isArray(historicalResult.matches)).toBe(true);
});
});
describe("Error Handling and Edge Cases", () => {
test("should handle empty query gracefully", async () => {
const context: RetrievalContext = {
userIntent: {
action: "analyze",
urgency: "medium",
experience: "intermediate",
},
};
const result = await contextualRetrieval.retrieve("", context);
expect(result).toBeDefined();
expect(result.matches).toBeDefined();
expect(Array.isArray(result.matches)).toBe(true);
});
test("should handle minimal context", async () => {
const minimalContext: RetrievalContext = {};
const result = await contextualRetrieval.retrieve(
"test query",
minimalContext,
);
expect(result).toBeDefined();
expect(result.matches).toBeDefined();
expect(Array.isArray(result.matches)).toBe(true);
});
});
});
```
--------------------------------------------------------------------------------
/docs/guides/playwright-integration.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.948Z"
last_validated: "2025-11-20T00:46:21.948Z"
auto_updated: false
update_frequency: monthly
---
# Playwright Integration Guide
## Overview
DocuMCP can generate a complete Playwright E2E testing setup for your documentation site, including:
- Playwright configuration
- Link validation tests
- Accessibility tests (WCAG 2.1 AA)
- Docker/Podman containerization
- GitHub Actions CI/CD workflow
**Important**: Playwright is NOT a dependency of DocuMCP itself. Instead, DocuMCP **generates** the Playwright setup for your documentation site.
## Quick Start
### Generate Playwright Setup
Use the `setup_playwright_tests` tool to generate all necessary files:
```typescript
{
tool: "setup_playwright_tests",
arguments: {
repositoryPath: "./my-docs-site",
ssg: "docusaurus",
projectName: "My Documentation",
mainBranch: "main",
includeAccessibilityTests: true,
includeDockerfile: true,
includeGitHubActions: true
}
}
```
### What Gets Generated
```
my-docs-site/
├── playwright.config.ts # Playwright configuration
├── Dockerfile.playwright # Multi-stage Docker build
├── .github/workflows/
│ └── docs-e2e-tests.yml # CI/CD workflow
├── tests/e2e/
│ ├── link-validation.spec.ts # Link tests
│ └── accessibility.spec.ts # A11y tests
├── package.json # Updated with Playwright deps
└── .gitignore # Updated with test artifacts
```
## Generated Files Explained
### 1. Playwright Config (`playwright.config.ts`)
```typescript
export default defineConfig({
testDir: "./tests/e2e",
timeout: 30 * 1000,
use: {
baseURL: process.env.BASE_URL || "http://localhost:3000",
},
projects: [{ name: "chromium" }, { name: "firefox" }, { name: "webkit" }],
});
```
### 2. Link Validation Tests
- ✅ Internal navigation links
- ✅ External link HTTP status
- ✅ Anchor/hash links
- ✅ 404 detection
### 3. Accessibility Tests
- ✅ WCAG 2.1 AA compliance (axe-core)
- ✅ Keyboard navigation
- ✅ Image alt text
- ✅ Color contrast
### 4. Docker Multi-Stage Build
```dockerfile
# Build docs
FROM node:20-alpine AS builder
RUN npm run build
# Run tests
FROM mcr.microsoft.com/playwright:v1.55.1 AS tester
RUN npx playwright test
# Serve production
FROM nginx:alpine AS server
COPY build /usr/share/nginx/html
```
### 5. GitHub Actions Workflow
Automated testing on every push/PR:
1. **Build** → Compile documentation
2. **Test** → Run Playwright in container (chromium, firefox, webkit)
3. **Deploy** → Push to GitHub Pages (if tests pass)
4. **Verify** → Test live production site
## Usage After Generation
### Local Testing
```bash
# Install dependencies (in YOUR docs site, not DocuMCP)
cd my-docs-site
npm install
# Install Playwright browsers
npx playwright install
# Run tests
npm run test:e2e
# Run tests in UI mode
npm run test:e2e:ui
# View test report
npm run test:e2e:report
```
### Docker Testing
```bash
# Build test container
docker build -t my-docs-test -f Dockerfile.playwright .
# Run tests in container
docker run --rm my-docs-test
# Or with Podman
podman build -t my-docs-test -f Dockerfile.playwright .
podman run --rm my-docs-test
```
### CI/CD Integration
Push to trigger GitHub Actions:
```bash
git add .
git commit -m "Add Playwright E2E tests"
git push origin main
```
Workflow will automatically:
- Build docs
- Run E2E tests across browsers
- Deploy to GitHub Pages (if all tests pass)
- Test production site after deployment
## Customization
### Add More Tests
Create new test files in `tests/e2e/`:
```typescript
// tests/e2e/navigation.spec.ts
import { test, expect } from "@playwright/test";
test("breadcrumbs should work", async ({ page }) => {
await page.goto("/docs/some-page");
const breadcrumbs = page.locator('[aria-label="breadcrumb"]');
await expect(breadcrumbs).toBeVisible();
});
```
### Modify Configuration
Edit `playwright.config.ts`:
```typescript
export default defineConfig({
// Increase timeout for slow networks
timeout: 60 * 1000,
// Add mobile viewports
projects: [
{ name: "chromium" },
{ name: "Mobile Chrome", use: devices["Pixel 5"] },
],
});
```
## SSG-Specific Configuration
DocuMCP automatically configures for your SSG:
| SSG | Build Command | Build Dir | Port |
| ---------- | -------------------------- | --------- | ---- |
| Jekyll | `bundle exec jekyll build` | `_site` | 4000 |
| Hugo | `hugo` | `public` | 1313 |
| Docusaurus | `npm run build` | `build` | 3000 |
| MkDocs | `mkdocs build` | `site` | 8000 |
| Eleventy | `npx @11ty/eleventy` | `_site` | 8080 |
## Knowledge Graph Integration
Test results are tracked in DocuMCP's Knowledge Graph:
```typescript
{
type: "deployment_validation",
properties: {
playwrightResults: {
totalTests: 25,
passed: 24,
failed: 1,
browsers: ["chromium", "firefox", "webkit"],
linksChecked: 127,
brokenLinks: 0,
accessibilityScore: 98,
}
}
}
```
## Troubleshooting
### Tests Fail on External Links
External link validation can fail due to:
- Network timeouts
- Rate limiting
- CORS issues
**Solution**: Tests only check first 10 external links. Increase timeout in config.
### Container Build Fails
**Issue**: Docker build fails on dependency installation
**Solution**: Check SSG-specific dependencies in package.json
### CI/CD Workflow Times Out
**Issue**: GitHub Actions workflow exceeds time limit
**Solution**: Run only chromium in CI, full matrix locally:
```yaml
# .github/workflows/docs-e2e-tests.yml
strategy:
matrix:
browser: [chromium] # Only chromium in CI
```
## Best Practices
1. **Run tests before pushing** - `npm run test:e2e`
2. **Use Docker locally** - Same environment as CI
3. **Update baselines** - When changing UI intentionally
4. **Monitor CI reports** - Check artifacts for failures
5. **Test production** - Workflow tests live site automatically
## Example Workflow
```bash
# 1. User analyzes their documentation repo with DocuMCP
documcp analyze_repository --path ./my-docs
# 2. User generates Playwright setup
documcp setup_playwright_tests \
--repositoryPath ./my-docs \
--ssg docusaurus \
--projectName "My Docs"
# 3. User installs dependencies (in THEIR repo)
cd my-docs
npm install
npx playwright install
# 4. User runs tests locally
npm run test:e2e
# 5. User pushes to GitHub
git push origin main
# 6. GitHub Actions runs tests automatically
# 7. If tests pass, deploys to GitHub Pages
# 8. Tests production site
```
## Resources
- [Playwright Documentation](https://playwright.dev/)
- [Complete Workflow Guide](./playwright-testing-workflow.md)
- [Link Validation Integration](./link-validation.md)
- [Axe Accessibility Testing](https://github.com/dequelabs/axe-core)
```
--------------------------------------------------------------------------------
/tests/integration/mcp-readme-tools.test.ts:
--------------------------------------------------------------------------------
```typescript
import { promises as fs } from "fs";
import { join } from "path";
describe("MCP Integration Tests", () => {
let tempDir: string;
beforeEach(async () => {
tempDir = join(process.cwd(), "test-mcp-integration-temp");
await fs.mkdir(tempDir, { recursive: true });
});
afterEach(async () => {
try {
await fs.rm(tempDir, { recursive: true, force: true });
} catch (error) {
// Ignore cleanup errors
}
});
describe("Tool Registration", () => {
test("should include evaluate_readme_health in tools list", async () => {
// This test verifies that the README health tool is properly registered
// Since we can't directly access the server instance, we'll test the tool functions directly
// but verify they match the expected MCP interface
const { evaluateReadmeHealth } = await import(
"../../src/tools/evaluate-readme-health.js"
);
// Test with valid parameters that match the MCP schema
const readmePath = join(tempDir, "README.md");
await fs.writeFile(readmePath, "# Test Project\n\nBasic README content.");
const result = await evaluateReadmeHealth({
readme_path: readmePath,
project_type: "community_library", // Valid enum value from schema
});
expect(result.content).toBeDefined();
expect(result.isError).toBe(false);
});
test("should include readme_best_practices in tools list", async () => {
const { readmeBestPractices } = await import(
"../../src/tools/readme-best-practices.js"
);
const readmePath = join(tempDir, "README.md");
await fs.writeFile(
readmePath,
"# Test Library\n\nLibrary documentation.",
);
const result = await readmeBestPractices({
readme_path: readmePath,
project_type: "library", // Valid enum value from schema
});
expect(result.success).toBe(true);
expect(result.data).toBeDefined();
});
});
describe("Parameter Validation", () => {
test("evaluate_readme_health should handle invalid project_type", async () => {
const { evaluateReadmeHealth } = await import(
"../../src/tools/evaluate-readme-health.js"
);
const readmePath = join(tempDir, "README.md");
await fs.writeFile(readmePath, "# Test");
const result = await evaluateReadmeHealth({
readme_path: readmePath,
project_type: "invalid_type" as any,
});
expect(result.isError).toBe(true);
});
test("readme_best_practices should handle invalid project_type", async () => {
const { readmeBestPractices } = await import(
"../../src/tools/readme-best-practices.js"
);
const readmePath = join(tempDir, "README.md");
await fs.writeFile(readmePath, "# Test");
const result = await readmeBestPractices({
readme_path: readmePath,
project_type: "invalid_type" as any,
});
expect(result.success).toBe(false);
expect(result.error).toBeDefined();
});
test("evaluate_readme_health should handle missing file", async () => {
const { evaluateReadmeHealth } = await import(
"../../src/tools/evaluate-readme-health.js"
);
const result = await evaluateReadmeHealth({
readme_path: join(tempDir, "nonexistent.md"),
});
expect(result.isError).toBe(true);
});
test("readme_best_practices should handle missing file without template", async () => {
const { readmeBestPractices } = await import(
"../../src/tools/readme-best-practices.js"
);
const result = await readmeBestPractices({
readme_path: join(tempDir, "nonexistent.md"),
generate_template: false,
});
expect(result.success).toBe(false);
expect(result.error?.code).toBe("README_NOT_FOUND");
});
});
describe("Response Format Consistency", () => {
test("evaluate_readme_health should return MCP-formatted response", async () => {
const { evaluateReadmeHealth } = await import(
"../../src/tools/evaluate-readme-health.js"
);
const readmePath = join(tempDir, "README.md");
await fs.writeFile(
readmePath,
"# Complete Project\n\n## Description\nDetailed description.",
);
const result = await evaluateReadmeHealth({
readme_path: readmePath,
});
// Should be already formatted for MCP
expect(result.content).toBeDefined();
expect(Array.isArray(result.content)).toBe(true);
expect(result.isError).toBeDefined();
// Should have execution metadata
const metadataContent = result.content.find((c) =>
c.text.includes("Execution completed"),
);
expect(metadataContent).toBeDefined();
});
test("readme_best_practices should return MCPToolResponse that can be formatted", async () => {
const { readmeBestPractices } = await import(
"../../src/tools/readme-best-practices.js"
);
const { formatMCPResponse } = await import("../../src/types/api.js");
const readmePath = join(tempDir, "README.md");
await fs.writeFile(
readmePath,
"# Library Project\n\n## Installation\nnpm install",
);
const result = await readmeBestPractices({
readme_path: readmePath,
});
// Should be raw MCPToolResponse
expect(result.success).toBeDefined();
expect(result.metadata).toBeDefined();
// Should be formattable
const formatted = formatMCPResponse(result);
expect(formatted.content).toBeDefined();
expect(Array.isArray(formatted.content)).toBe(true);
expect(formatted.isError).toBe(false);
});
});
describe("Cross-tool Consistency", () => {
test("both tools should handle the same README file", async () => {
const { evaluateReadmeHealth } = await import(
"../../src/tools/evaluate-readme-health.js"
);
const { readmeBestPractices } = await import(
"../../src/tools/readme-best-practices.js"
);
const readmePath = join(tempDir, "README.md");
await fs.writeFile(
readmePath,
`# Test Project
## Description
This is a comprehensive test project.
## Installation
\`\`\`bash
npm install test-project
\`\`\`
## Usage
\`\`\`javascript
const test = require('test-project');
test.run();
\`\`\`
## Contributing
Please read our contributing guidelines.
## License
MIT License
`,
);
// Both tools should work on the same file
const healthResult = await evaluateReadmeHealth({
readme_path: readmePath,
project_type: "community_library",
});
const practicesResult = await readmeBestPractices({
readme_path: readmePath,
project_type: "library",
});
expect(healthResult.isError).toBe(false);
expect(practicesResult.success).toBe(true);
});
});
});
```
--------------------------------------------------------------------------------
/docs/how-to/repository-analysis.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.954Z"
last_validated: "2025-11-20T00:46:21.954Z"
auto_updated: false
update_frequency: monthly
---
# How to Analyze Your Repository with DocuMCP
This guide walks you through using DocuMCP's repository analysis capabilities to understand your project's documentation needs.
## What Repository Analysis Provides
DocuMCP's analysis examines your project from multiple perspectives:
- **Project Structure**: File organization, language distribution, directory structure
- **Dependencies**: Package ecosystems, frameworks, and libraries in use
- **Documentation Status**: Existing documentation files, README quality, coverage gaps
- **Complexity Assessment**: Project size, team size estimates, maintenance requirements
- **Recommendations**: Tailored suggestions based on your project characteristics
## Basic Analysis
### Simple Analysis Request
```
analyze my repository
```
This performs a standard-depth analysis covering all key aspects of your project.
### Specify Analysis Depth
```
analyze my repository with deep analysis
```
Available depth levels:
- **quick**: Fast overview focusing on basic structure and languages
- **standard**: Comprehensive analysis including dependencies and documentation (recommended)
- **deep**: Detailed analysis with advanced insights and recommendations
## Understanding Analysis Results
### Project Structure Section
```json
{
"structure": {
"totalFiles": 2034,
"totalDirectories": 87,
"languages": {
".ts": 86,
".js": 13,
".css": 3,
".html": 37
},
"hasTests": true,
"hasCI": true,
"hasDocs": true
}
}
```
This tells you:
- Scale of your project (file/directory count)
- Primary programming languages
- Presence of tests, CI/CD, and existing documentation
### Dependencies Analysis
```json
{
"dependencies": {
"ecosystem": "javascript",
"packages": ["@modelcontextprotocol/sdk", "zod", "typescript"],
"devPackages": ["jest", "@types/node", "eslint"]
}
}
```
This reveals:
- Primary package ecosystem (npm, pip, cargo, etc.)
- Key runtime dependencies
- Development and tooling dependencies
### Documentation Assessment
```json
{
"documentation": {
"hasReadme": true,
"hasContributing": true,
"hasLicense": true,
"existingDocs": ["README.md", "docs/api.md"],
"estimatedComplexity": "complex"
}
}
```
This shows:
- Presence of essential documentation files
- Existing documentation structure
- Complexity level for documentation planning
## Advanced Analysis Techniques
### Target Specific Directories
```
analyze the src directory for API documentation needs
```
### Focus on Documentation Gaps
```
what documentation is missing from my project?
```
### Analyze for Specific Use Cases
```
analyze my repository to determine if it needs user guides or developer documentation
```
## Using Analysis Results
### For SSG Selection
After analysis, use the results to get targeted recommendations:
```
based on the analysis, what static site generator works best for my TypeScript project?
```
### For Documentation Planning
Use analysis insights to plan your documentation structure:
```
given my project complexity, how should I organize my documentation?
```
### For Deployment Strategy
Let analysis guide your deployment approach:
```
considering my project setup, what's the best way to deploy documentation?
```
## Analysis-Driven Workflows
### Complete Documentation Setup
1. **Analyze**: `analyze my repository for documentation needs`
2. **Plan**: Use analysis results to understand project characteristics
3. **Recommend**: `recommend documentation tools based on the analysis`
4. **Implement**: `set up documentation based on the recommendations`
### Documentation Audit
1. **Current State**: `analyze my existing documentation structure`
2. **Gap Analysis**: `what documentation gaps exist in my project?`
3. **Improvement Plan**: `how can I improve my current documentation?`
### Migration Planning
1. **Legacy Analysis**: `analyze my project's current documentation approach`
2. **Modern Approach**: `what modern documentation tools would work better?`
3. **Migration Strategy**: `how should I migrate from my current setup?`
## Interpreting Recommendations
### Project Type Classification
Analysis categorizes your project as:
- **library**: Reusable code packages requiring API documentation
- **application**: End-user software needing user guides and tutorials
- **tool**: Command-line or developer tools requiring usage documentation
### Team Size Estimation
- **small**: 1-3 developers, favor simple solutions
- **medium**: 4-10 developers, need collaborative features
- **large**: 10+ developers, require enterprise-grade solutions
### Complexity Assessment
- **simple**: Basic projects with minimal documentation needs
- **moderate**: Standard projects requiring structured documentation
- **complex**: Large projects needing comprehensive documentation strategies
## Common Analysis Patterns
### JavaScript/TypeScript Projects
Analysis typically reveals:
- npm ecosystem with extensive dev dependencies
- Need for API documentation (if library)
- Integration with existing build tools
- Recommendation: Often Docusaurus or VuePress
### Python Projects
Analysis usually shows:
- pip/poetry ecosystem
- Sphinx-compatible documentation needs
- Strong preference for MkDocs
- Integration with Python documentation standards
### Multi-Language Projects
Analysis identifies:
- Mixed ecosystems and dependencies
- Need for language-agnostic solutions
- Recommendation: Usually Hugo or Jekyll for flexibility
## Troubleshooting Analysis
### Incomplete Results
If analysis seems incomplete:
```
run deep analysis on my repository to get more detailed insights
```
### Focus on Specific Areas
If you need more details about certain aspects:
```
analyze my project's dependencies in detail
```
### Re-analyze After Changes
After making significant changes:
```
re-analyze my repository to see updated recommendations
```
## Analysis Memory and Caching
DocuMCP stores analysis results for reference in future operations:
- Analysis IDs are provided for referencing specific analyses
- Results remain accessible throughout your session
- Memory system learns from successful documentation deployments
Use analysis IDs in follow-up requests:
```
using analysis analysis_abc123, set up the recommended documentation structure
```
## Best Practices
1. **Start Fresh**: Begin new documentation projects with analysis
2. **Regular Reviews**: Re-analyze periodically as projects evolve
3. **Deep Dive When Needed**: Use deep analysis for complex projects
4. **Combine with Expertise**: Use analysis as a starting point, not final decision
5. **Iterate**: Refine based on analysis feedback and results
Analysis is the foundation of effective documentation planning with DocuMCP. Use it to make informed decisions about tools, structure, and deployment strategies.
```
--------------------------------------------------------------------------------
/docs/research/domain-5-github-deployment/github-pages-security-analysis.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.967Z"
last_validated: "2025-11-20T00:46:21.967Z"
auto_updated: false
update_frequency: monthly
---
# GitHub Pages Deployment Security and Limitations Analysis
**Research Date**: 2025-01-14
**Domain**: GitHub Pages Deployment Automation
**Status**: Completed
## Research Overview
Comprehensive analysis of GitHub Pages deployment security considerations, limitations, and automation best practices for DocuMCP implementation.
## GitHub Pages Security Model Analysis
### Deployment Methods & Security Implications
#### **1. GitHub Actions (Official Method)**
**Security Profile**:
- ✅ **OIDC Token-based Authentication**: Uses JWT tokens with branch validation
- ✅ **Permissions Model**: Requires explicit `pages: write` and `id-token: write`
- ✅ **Environment Protection**: Supports environment rules and approvals
- ⚠️ **First Deploy Challenge**: Manual branch selection required initially
**Implementation Pattern**:
```yaml
permissions:
pages: write # Deploy to Pages
id-token: write # Verify deployment origin
contents: read # Checkout repository
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
```
#### **2. Deploy Keys (SSH Method)**
**Security Profile**:
- ✅ **Repository-specific**: Keys scoped to individual repositories
- ✅ **Write Access Control**: Can be limited to deployment-only access
- ⚠️ **Key Management**: Requires secure key generation and storage
- ⚠️ **Cross-repo Complexity**: Each external repo needs separate key setup
#### **3. Personal Access Tokens**
**Security Profile**:
- ⚠️ **Broad Permissions**: Often have wider access than needed
- ⚠️ **Expiration Management**: Tokens expire and need rotation
- ⚠️ **Account-wide Risk**: Compromise affects all accessible repositories
### GitHub Pages Deployment Limitations
#### **Technical Constraints**
1. **Site Size Limits**:
- Maximum 1GB per repository
- Impacts large documentation sites with assets
- No compression before size calculation
2. **Build Frequency Limits**:
- 10 builds per hour soft limit
- Additional builds queued for next hour
- Can impact rapid deployment cycles
3. **Static Content Only**:
- No server-side processing
- No dynamic content generation
- Limited to client-side JavaScript
#### **Security Constraints**
1. **Content Security Policy**:
- Default CSP may block certain resources
- Limited ability to customize security headers
- No server-side security controls
2. **HTTPS Enforcement**:
- Custom domains require manual HTTPS setup
- Certificate management through GitHub
- No control over TLS configuration
### CI/CD Workflow Security Best Practices
#### **Recommended Security Architecture**
```yaml
name: Deploy Documentation
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Security scan
run: |
# Scan for secrets, vulnerabilities
npm audit --audit-level high
build:
needs: security-scan
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build site
run: npm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
if: github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
```
#### **Security Validation Steps**
1. **Pre-deployment Checks**:
- Secret scanning
- Dependency vulnerability assessment
- Content validation
2. **Deployment Security**:
- Environment protection rules
- Required reviewers for production
- Branch protection enforcement
3. **Post-deployment Verification**:
- Site accessibility validation
- Security header verification
- Content integrity checks
### DocuMCP Security Implementation Recommendations
#### **Multi-layered Security Approach**
1. **Tool-level Security**:
```typescript
// Example security validation in MCP tool
const validateDeploymentSecurity = (config: DeploymentConfig) => {
const securityChecks = {
hasSecretScanning: checkSecretScanning(config),
hasEnvironmentProtection: checkEnvironmentRules(config),
hasProperPermissions: validatePermissions(config),
hasSecurityHeaders: validateSecurityHeaders(config),
};
return securityChecks;
};
```
2. **Configuration Template Security**:
- Generate workflows with minimal required permissions
- Include security scanning by default
- Enforce environment protection for production
3. **User Education Components**:
- Security best practices documentation
- Common vulnerability warnings
- Regular security updates guidance
### Risk Assessment & Mitigation
#### **High-Risk Scenarios**
1. **Secret Exposure in Repositories**:
- **Risk**: API keys, tokens in code
- **Mitigation**: Mandatory secret scanning, education
2. **Malicious Pull Request Deployments**:
- **Risk**: Untrusted code in preview deployments
- **Mitigation**: Environment protection, review requirements
3. **Supply Chain Attacks**:
- **Risk**: Compromised dependencies
- **Mitigation**: Dependency scanning, lock files
#### **Medium-Risk Scenarios**
1. **Excessive Permissions**:
- **Risk**: Overprivileged deployment workflows
- **Mitigation**: Principle of least privilege templates
2. **Unprotected Environments**:
- **Risk**: Direct production deployments
- **Mitigation**: Default environment protection
### Implementation Priorities for DocuMCP
#### **Critical Security Features**
1. **Automated Security Scanning**: Integrate secret and vulnerability scanning
2. **Permission Minimization**: Generate workflows with minimal required permissions
3. **Environment Protection**: Default protection rules for production environments
4. **Security Documentation**: Clear guidance on security best practices
#### **Enhanced Security Features**
1. **Custom Security Checks**: Advanced validation for specific project types
2. **Security Reporting**: Automated security posture assessment
3. **Incident Response**: Guidance for security issue handling
## Research Validation Status
- ✅ GitHub Pages security model analyzed
- ✅ Deployment methods evaluated
- ✅ Security best practices documented
- ✅ Risk assessment completed
- ⚠️ Needs validation: Security template effectiveness testing
- ⚠️ Needs implementation: DocuMCP security feature integration
## Sources & References
1. GitHub Pages Official Documentation - Security Guidelines
2. GitHub Actions Security Best Practices
3. OWASP Static Site Security Guide
4. GitHub Security Advisory Database
5. Community Security Analysis Reports
```
--------------------------------------------------------------------------------
/docs/research/research-integration-summary-2025-01-14.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.968Z"
last_validated: "2025-11-20T00:46:21.968Z"
auto_updated: false
update_frequency: monthly
---
# Research Integration Summary
**Date**: 2025-01-14
**Status**: Completed
**Integration Method**: Direct ADR Updates + Implementation Recommendations
## Research Integration Overview
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.
## Research Areas Integrated
### ✅ **1. MCP Server Architecture (ADR-001)**
**Research Source**: `domain-1-mcp-architecture/mcp-performance-research.md`
**Key Integrations**:
- **Performance Validation**: Confirmed TypeScript MCP SDK provides minimal overhead with JSON-RPC 2.0
- **Memory Optimization**: Integrated streaming patterns (10x memory reduction) and worker threads (3-4x performance)
- **Implementation Strategy**: Added concrete code patterns for repository analysis with performance benchmarks
**ADR Updates Applied**:
- Added "Research Integration" section with validated performance characteristics
- Integrated specific implementation patterns for streaming and worker threads
- Established research-validated performance targets for different repository sizes
### ✅ **2. SSG Recommendation Engine (ADR-003)**
**Research Source**: `domain-3-ssg-recommendation/ssg-performance-analysis.md`
**Key Integrations**:
- **Performance Matrix**: Comprehensive build time analysis across SSG scales
- **Algorithm Enhancement**: Research-validated scoring with scale-based weighting
- **Real-World Data**: Hugo 250x faster than Gatsby (small sites), gap narrows to 40x (large sites)
**ADR Updates Applied**:
- Enhanced performance modeling with research-validated SSG performance matrix
- Updated recommendation algorithm with evidence-based scoring
- Integrated scale-based performance weighting (critical path vs features)
### ✅ **3. GitHub Pages Deployment Security (ADR-005)**
**Research Source**: `domain-5-github-deployment/github-pages-security-analysis.md`
**Key Integrations**:
- **Security Architecture**: OIDC token authentication with JWT validation
- **Permission Minimization**: Specific `pages: write` and `id-token: write` requirements
- **Environment Protection**: Default security rules with approval workflows
- **Automated Scanning**: Integrated secret and vulnerability detection
**ADR Updates Applied**:
- Enhanced repository configuration management with research-validated security practices
- Added multi-layered security approach with specific implementation details
- Integrated automated security scanning and environment protection requirements
## Implementation Impact Analysis
### **Immediate Implementation Requirements**
1. **High Priority Updates** (Week 1-2):
- Implement streaming-based repository analysis with 10MB threshold
- Create worker thread pool for parallel file processing
- Integrate OIDC-based GitHub Pages deployment templates
2. **Medium Priority Enhancements** (Week 3-4):
- Develop SSG performance scoring algorithm with research-validated weights
- Implement automated security scanning in generated workflows
- Create environment protection templates
### **Architecture Validation Status**
| **Decision Area** | **Research Status** | **Validation Result** | **Implementation Ready** |
| --------------------- | ------------------- | ---------------------------- | ------------------------ |
| TypeScript MCP SDK | ✅ Validated | Confirmed optimal choice | ✅ Yes |
| Node.js Performance | ✅ Validated | Specific patterns identified | ✅ Yes |
| SSG Recommendation | ✅ Validated | Algorithm refined | ✅ Yes |
| GitHub Pages Security | ✅ Validated | Security model confirmed | ✅ Yes |
| Repository Analysis | ✅ Validated | Streaming patterns proven | ✅ Yes |
### **Risk Mitigation Updates**
**Original Risk**: Memory constraints for large repository analysis
**Research Mitigation**: 10x memory reduction with streaming + worker threads
**Implementation**: Concrete code patterns integrated into ADR-001
**Original Risk**: SSG recommendation accuracy
**Research Mitigation**: Evidence-based performance weighting algorithm
**Implementation**: Performance matrix and scoring algorithm in ADR-003
**Original Risk**: Deployment security vulnerabilities
**Research Mitigation**: Multi-layered security with OIDC authentication
**Implementation**: Enhanced security configuration in ADR-005
## Research Validation Metrics
### **Research Quality Assessment**
- **Sources Analyzed**: 15+ authoritative sources (GitHub docs, CSS-Tricks benchmarks, security guides)
- **Data Points Validated**: 50+ specific performance metrics and security practices
- **Implementation Patterns**: 12+ concrete code examples and configuration templates
- **Best Practices**: 25+ industry-validated approaches integrated
### **ADR Enhancement Metrics**
- **ADRs Updated**: 3 core architectural decisions
- **New Content Added**: ~500 lines of research-validated implementation guidance
- **Performance Targets**: Quantitative benchmarks established for all components
- **Security Practices**: Comprehensive security model with specific configurations
## Next Steps & Continuous Integration
### **Immediate Actions** (Next 48 hours)
1. **Implementation Planning**: Use research-validated patterns for MVP development
2. **Security Review**: Validate enhanced security configurations with team
3. **Performance Testing**: Create benchmarks based on research targets
### **Short-term Integration** (Next 2 weeks)
1. **Prototype Development**: Implement streaming repository analysis
2. **Algorithm Validation**: Test SSG recommendation scoring with real projects
3. **Security Testing**: Validate OIDC deployment workflows
### **Long-term Monitoring** (Ongoing)
1. **Performance Validation**: Compare actual performance against research predictions
2. **Security Auditing**: Regular validation of security practices
3. **Research Updates**: Monitor for new performance data and security practices
## Research Integration Success Criteria
✅ **Architectural Validation**: All core decisions validated with evidence
✅ **Implementation Guidance**: Concrete patterns and code examples provided
✅ **Performance Targets**: Quantitative benchmarks established
✅ **Security Framework**: Comprehensive security model implemented
✅ **Risk Mitigation**: Major risks addressed with validated solutions
**Overall Integration Status**: **SUCCESSFUL** - Ready for implementation phase
---
**Research Conducted Using**: Firecrawl MCP Server systematic web research
**Research Duration**: 4 hours intensive analysis
**Integration Method**: Direct ADR updates with validation tracking
**Confidence Level**: 95% - Based on authoritative sources and comprehensive analysis
```
--------------------------------------------------------------------------------
/docs/how-to/prompting-guide.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.953Z"
last_validated: "2025-11-20T00:46:21.953Z"
auto_updated: false
update_frequency: monthly
---
# How to Prompt DocuMCP Effectively
This guide shows you how to interact with DocuMCP using effective prompts to get the best results from the system.
## 🎯 Pro Tip: Use @LLM_CONTEXT.md
When using DocuMCP in your AI assistant (Claude, ChatGPT, etc.), **reference the LLM_CONTEXT.md file** for instant context about all 45 available tools:
```
@LLM_CONTEXT.md analyze my repository and recommend the best deployment strategy
```
The `LLM_CONTEXT.md` file provides:
- Complete tool descriptions and parameters
- Usage examples for all 45 tools
- Common workflow patterns
- Memory system documentation
- Phase 3 code-to-docs sync capabilities
**Location**: `/LLM_CONTEXT.md` in the root of your project
This ensures your AI assistant has full context about DocuMCP's capabilities and can provide more accurate recommendations.
## Quick Start
DocuMCP responds to natural language prompts. Here are the most common patterns:
### Basic Analysis
```
analyze my repository for documentation needs
```
### Get Recommendations
```
what static site generator should I use for my project?
```
### Deploy Documentation
```
set up GitHub Pages deployment for my docs
```
## Available Tools
DocuMCP provides several tools you can invoke through natural prompts:
### 1. Repository Analysis
**Purpose**: Analyze your project structure, dependencies, and documentation needs.
**Example Prompts**:
- "Analyze my repository structure"
- "What documentation gaps do I have?"
- "Examine my project for documentation opportunities"
**What it returns**: Project analysis with language detection, dependency mapping, and complexity assessment.
### 2. SSG Recommendations
**Purpose**: Get intelligent static site generator recommendations based on your project.
**Example Prompts**:
- "Recommend a static site generator for my TypeScript project"
- "Which SSG works best with my Python documentation?"
- "Compare documentation tools for my project"
**What it returns**: Weighted recommendations with justifications for Jekyll, Hugo, Docusaurus, MkDocs, or Eleventy.
### 3. Configuration Generation
**Purpose**: Generate SSG-specific configuration files.
**Example Prompts**:
- "Generate a Hugo config for my project"
- "Create MkDocs configuration files"
- "Set up Docusaurus for my documentation"
**What it returns**: Ready-to-use configuration files optimized for your project.
### 4. Documentation Structure
**Purpose**: Create Diataxis-compliant documentation structure.
**Example Prompts**:
- "Set up documentation structure following Diataxis"
- "Create organized docs folders for my project"
- "Build a comprehensive documentation layout"
**What it returns**: Organized folder structure with templates following documentation best practices.
### 5. GitHub Pages Deployment
**Purpose**: Automate GitHub Pages deployment workflows.
**Example Prompts**:
- "Deploy my docs to GitHub Pages"
- "Set up automated documentation deployment"
- "Create GitHub Actions for my documentation site"
**What it returns**: GitHub Actions workflows configured for your chosen SSG.
### 6. Deployment Verification
**Purpose**: Verify and troubleshoot GitHub Pages deployments.
**Example Prompts**:
- "Check if my GitHub Pages deployment is working"
- "Troubleshoot my documentation deployment"
- "Verify my docs site is live"
**What it returns**: Deployment status and troubleshooting recommendations.
## Advanced Prompting Techniques
### Chained Operations
You can chain multiple operations in a single conversation:
```
1. First analyze my repository
2. Then recommend the best SSG
3. Finally set up the deployment workflow
```
### Specific Requirements
Be specific about your needs:
```
I need a documentation site that:
- Works with TypeScript
- Supports API documentation
- Has good search functionality
- Deploys automatically on commits
```
### Context-Aware Requests
Reference previous analysis:
```
Based on the analysis you just did, create the documentation structure and deploy it to GitHub Pages
```
## Best Practices
### 1. Start with Analysis
Always begin with repository analysis to get tailored recommendations:
```
analyze my project for documentation needs
```
### 2. Be Specific About Goals
Tell DocuMCP what you're trying to achieve:
- "I need developer documentation for my API"
- "I want user guides for my application"
- "I need project documentation for contributors"
### 3. Specify Constraints
Mention any limitations or preferences:
- "I prefer minimal setup"
- "I need something that works with our CI/CD pipeline"
- "I want to use our existing design system"
### 4. Ask for Explanations
Request reasoning behind recommendations:
```
why did you recommend Hugo over Jekyll for my project?
```
### 5. Iterate and Refine
Use follow-up prompts to refine results:
```
can you modify the GitHub Actions workflow to also run tests?
```
## Common Workflows
### Complete Documentation Setup
```
1. "Analyze my repository for documentation needs"
2. "Recommend the best static site generator for my project"
3. "Generate configuration files for the recommended SSG"
4. "Set up Diataxis-compliant documentation structure"
5. "Deploy everything to GitHub Pages"
```
### Documentation Audit
```
1. "Analyze my existing documentation"
2. "What gaps do you see in my current docs?"
3. "How can I improve my documentation structure?"
```
### Deployment Troubleshooting
```
1. "My GitHub Pages site isn't working"
2. "Check my deployment configuration"
3. "Help me fix the build errors"
```
## Memory and Context
DocuMCP remembers context within a conversation, so you can:
- Reference previous analysis results
- Build on earlier recommendations
- Chain operations together seamlessly
Example conversation flow:
```
User: "analyze my repository"
DocuMCP: [provides analysis]
User: "based on that analysis, what SSG do you recommend?"
DocuMCP: [provides recommendation using analysis context]
User: "set it up with that recommendation"
DocuMCP: [configures the recommended SSG]
```
## Troubleshooting Prompts
If you're not getting the results you expect, try:
### More Specific Prompts
Instead of: "help with docs"
Try: "analyze my TypeScript project and recommend documentation tools"
### Context Setting
Instead of: "set up deployment"
Try: "set up GitHub Pages deployment for the MkDocs site we just configured"
### Direct Tool Requests
If you know exactly what you want:
- "use the analyze_repository tool on my current directory"
- "run the recommend_ssg tool with my project data"
## Getting Help
If you need assistance with prompting:
- Ask DocuMCP to explain available tools: "what can you help me with?"
- Request examples: "show me example prompts for documentation setup"
- Ask for clarification: "I don't understand the recommendation, can you explain?"
Remember: DocuMCP is designed to understand natural language, so don't hesitate to ask questions in your own words!
```
--------------------------------------------------------------------------------
/docs/tutorials/memory-workflows.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.973Z"
last_validated: "2025-11-20T00:46:21.973Z"
auto_updated: false
update_frequency: monthly
---
# Memory Workflows and Advanced Features
This tutorial covers DocuMCP's memory system and advanced workflow features for intelligent documentation management.
## Overview
DocuMCP includes a sophisticated memory system that learns from your documentation patterns and provides intelligent assistance:
### Memory System Features
- **Historical Analysis**: Learns from past documentation projects
- **User Preferences**: Adapts to your documentation style
- **Pattern Recognition**: Identifies successful documentation patterns
- **Smart Recommendations**: Provides context-aware suggestions
### Advanced Workflows
- **Multi-Project Memory**: Share insights across projects
- **Collaborative Learning**: Learn from team documentation patterns
- **Automated Optimization**: Continuously improve documentation quality
## Getting Started with Memory
### Initial Setup
```bash
# Initialize memory system:
"initialize memory system for my documentation workflow"
```
### Basic Memory Operations
```bash
# Store analysis results:
"store this analysis in memory for future reference"
# Recall similar projects:
"find similar projects in my memory"
# Update preferences:
"update my documentation preferences based on this project"
```
## Memory System Architecture
### Memory Components
1. **Analysis Memory**: Stores repository analysis results
2. **Recommendation Memory**: Tracks SSG recommendation patterns
3. **Deployment Memory**: Records deployment success patterns
4. **User Preference Memory**: Learns individual preferences
### Memory Storage
```yaml
# Memory configuration
memory:
storage_path: ".documcp/memory"
retention_policy: "keep_all"
backup_enabled: true
compression: true
```
## Advanced Memory Features
### Contextual Retrieval
```bash
# Find relevant memories:
"find memories related to TypeScript documentation projects"
# Get contextual suggestions:
"get suggestions based on my previous documentation patterns"
```
### Pattern Learning
```bash
# Learn from successful deployments:
"learn from successful documentation deployments"
# Identify patterns:
"identify successful documentation patterns in my memory"
```
### Collaborative Memory
```bash
# Share memories with team:
"share documentation patterns with my team"
# Import team memories:
"import documentation patterns from team members"
```
## Memory Workflow Examples
### Project Analysis Workflow
```bash
# Complete analysis with memory integration:
"analyze my repository and store results in memory for future reference"
```
This workflow:
1. Analyzes the current repository
2. Compares with similar projects in memory
3. Provides enhanced recommendations
4. Stores results for future reference
### Recommendation Workflow
```bash
# Get memory-enhanced recommendations:
"recommend SSG based on my memory and current project"
```
This workflow:
1. Retrieves relevant memories
2. Applies learned patterns
3. Provides personalized recommendations
4. Updates memory with results
### Deployment Workflow
```bash
# Deploy with memory insights:
"deploy documentation using insights from my memory"
```
This workflow:
1. Applies learned deployment patterns
2. Uses successful configuration templates
3. Monitors for known issues
4. Records results for future learning
## Memory Management
### Memory Operations
```bash
# List all memories:
"list all memories in my system"
# Search memories:
"search memories for 'React documentation'"
# Export memories:
"export my documentation memories"
# Import memories:
"import documentation memories from file"
```
### Memory Optimization
```bash
# Optimize memory storage:
"optimize memory storage and remove duplicates"
# Clean up old memories:
"clean up memories older than 6 months"
# Compress memory:
"compress memory storage for efficiency"
```
## Advanced Workflow Patterns
### Multi-Project Memory Sharing
```bash
# Set up project memory sharing:
"set up memory sharing between my projects"
```
### Team Collaboration
```bash
# Enable team memory sharing:
"enable team memory sharing for documentation patterns"
```
### Automated Learning
```bash
# Enable automated learning:
"enable automated learning from documentation patterns"
```
## Memory Analytics
### Memory Insights
```bash
# Get memory insights:
"provide insights from my documentation memory"
```
### Success Pattern Analysis
```bash
# Analyze success patterns:
"analyze successful documentation patterns in my memory"
```
### Performance Tracking
```bash
# Track memory performance:
"track performance of memory-enhanced recommendations"
```
## Troubleshooting Memory Issues
### Common Problems
**Problem**: Memory not loading
**Solution**: Check memory file permissions and integrity
**Problem**: Slow memory operations
**Solution**: Optimize memory storage and clean up old data
**Problem**: Inconsistent recommendations
**Solution**: Review memory data quality and patterns
### Memory Debugging
```bash
# Debug memory issues:
"debug memory system problems"
# Validate memory integrity:
"validate memory data integrity"
# Reset memory system:
"reset memory system to defaults"
```
## Best Practices
### Memory Management
1. **Regular Backups**: Backup memory data regularly
2. **Quality Control**: Review and clean memory data
3. **Privacy**: Be mindful of sensitive data in memories
4. **Performance**: Monitor memory system performance
5. **Documentation**: Document your memory workflows
### Workflow Optimization
1. **Consistent Patterns**: Use consistent documentation patterns
2. **Regular Updates**: Update memory with new learnings
3. **Team Sharing**: Share successful patterns with team
4. **Continuous Learning**: Enable continuous learning features
5. **Performance Monitoring**: Monitor workflow performance
## Memory System Integration
### With Documentation Tools
- **Repository Analysis**: Enhanced with historical data
- **SSG Recommendations**: Improved with pattern learning
- **Deployment Automation**: Optimized with success patterns
- **Content Generation**: Informed by previous content
### With External Systems
- **CI/CD Integration**: Memory-aware deployment pipelines
- **Analytics Integration**: Memory-enhanced performance tracking
- **Team Tools**: Collaborative memory sharing
- **Backup Systems**: Automated memory backup
## Advanced Configuration
### Memory Configuration
```yaml
# Advanced memory configuration
memory:
storage:
type: "local"
path: ".documcp/memory"
encryption: true
learning:
enabled: true
auto_update: true
pattern_detection: true
sharing:
team_enabled: false
project_sharing: true
export_format: "json"
```
### Performance Tuning
```bash
# Tune memory performance:
"optimize memory system performance"
```
## Next Steps
- [How-to Guides](../how-to/)
- [Reference Documentation](../reference/)
- [Architecture Explanation](../explanation/)
- [Advanced Configuration](../reference/configuration.md)
```
--------------------------------------------------------------------------------
/docs/how-to/documentation-freshness-tracking.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.950Z"
last_validated: "2025-11-20T00:46:21.950Z"
auto_updated: false
update_frequency: monthly
---
# How to Track Documentation Freshness
This guide shows you how to use DocuMCP's documentation freshness tracking system to monitor and maintain up-to-date documentation.
## Quick Start
```bash
# Initialize freshness tracking:
"validate documentation freshness for my docs directory"
# Check freshness status:
"track documentation freshness"
```
## Overview
Documentation freshness tracking helps you:
- **Identify stale documentation**: Find files that haven't been updated recently
- **Maintain quality**: Ensure documentation stays current with code changes
- **Track history**: Monitor documentation updates over time via knowledge graph integration
- **Automate maintenance**: Set up workflows for regular freshness checks
## Initial Setup
### Step 1: Initialize Freshness Metadata
Before tracking freshness, you need to initialize metadata for your documentation files:
```json
{
"docsPath": "/path/to/docs",
"projectPath": "/path/to/project",
"initializeMissing": true,
"validateAgainstGit": true
}
```
This will:
- Create freshness metadata for all documentation files
- Set initial timestamps based on file modification dates
- Link metadata to git history (if available)
### Step 2: Verify Initialization
Check that metadata was created successfully:
```bash
# Track freshness to see initialized files:
"track documentation freshness for my docs"
```
You should see all files marked as "fresh" initially.
## Regular Freshness Checks
### Basic Tracking
Run regular freshness checks to monitor documentation staleness:
```json
{
"docsPath": "/path/to/docs",
"includeFileList": true
}
```
### Using Presets
DocuMCP provides convenient presets for different update frequencies:
- **realtime**: For documentation that changes frequently (minutes/hours)
- **active**: For actively maintained docs (days)
- **recent**: For recently updated docs (weeks)
- **weekly**: For weekly review cycles
- **monthly**: For monthly maintenance (default)
- **quarterly**: For quarterly reviews
```json
{
"docsPath": "/path/to/docs",
"preset": "monthly"
}
```
### Custom Thresholds
Define your own staleness thresholds:
```json
{
"docsPath": "/path/to/docs",
"warningThreshold": {
"value": 7,
"unit": "days"
},
"staleThreshold": {
"value": 30,
"unit": "days"
},
"criticalThreshold": {
"value": 90,
"unit": "days"
}
}
```
## Understanding Freshness Levels
### Fresh ✅
Files updated within the warning threshold (default: 7 days)
### Warning 🟡
Files older than warning threshold but newer than stale threshold (7-30 days)
### Stale 🟠
Files older than stale threshold but newer than critical threshold (30-90 days)
### Critical 🔴
Files older than critical threshold (90+ days)
### Unknown ❓
Files without freshness metadata (need initialization)
## Workflow Examples
### Weekly Documentation Review
```bash
# 1. Check freshness status
"track documentation freshness with preset weekly"
# 2. Review stale files and update as needed
# (manually update documentation)
# 3. Validate freshness after updates
"validate documentation freshness and update existing metadata"
```
### After Major Code Changes
```bash
# 1. Update documentation to reflect code changes
# (manually update files)
# 2. Validate freshness against git
"validate documentation freshness with git validation"
# 3. Track updated status
"track documentation freshness"
```
### Automated CI/CD Integration
Add freshness checks to your CI/CD pipeline:
```yaml
# .github/workflows/docs-freshness.yml
- name: Check Documentation Freshness
run: |
documcp track_documentation_freshness \
--docsPath ./docs \
--preset monthly \
--failOnStale true
```
## Advanced Usage
### Knowledge Graph Integration
Freshness tracking events are automatically stored in the knowledge graph:
```json
{
"docsPath": "/path/to/docs",
"projectPath": "/path/to/project",
"storeInKG": true
}
```
This enables:
- Historical analysis of documentation updates
- Pattern recognition across projects
- Intelligent recommendations based on past behavior
### Sorting and Filtering
Customize how files are displayed:
```json
{
"docsPath": "/path/to/docs",
"sortBy": "staleness", // Options: "age", "path", "staleness"
"includeFileList": true
}
```
### Git Integration
Validate freshness against git history:
```json
{
"docsPath": "/path/to/docs",
"projectPath": "/path/to/project",
"validateAgainstGit": true
}
```
This compares file modification times with git commit history for more accurate staleness detection.
## Best Practices
### 1. Initialize Early
Set up freshness tracking when you first create documentation:
```bash
"initialize freshness tracking for my new documentation"
```
### 2. Regular Checks
Schedule regular freshness checks:
- Weekly for active projects
- Monthly for stable projects
- Quarterly for archived documentation
### 3. Update Thresholds
Adjust thresholds based on your project's update frequency:
- Active projects: 7/30/90 days
- Stable projects: 30/90/180 days
- Archived docs: 90/180/365 days
### 4. Integrate with Workflows
Combine freshness tracking with other DocuMCP tools:
```bash
# Check freshness → Update stale docs → Validate → Deploy
"track documentation freshness, then update stale files, validate, and deploy"
```
### 5. Monitor Trends
Use knowledge graph insights to identify patterns:
```bash
# Get freshness insights from knowledge graph
"get insights about documentation freshness trends"
```
## Troubleshooting
### Problem: All files show as "unknown"
**Solution**: Run `validate_documentation_freshness` with `initializeMissing: true`
### Problem: Freshness not updating after file changes
**Solution**: Run `validate_documentation_freshness` with `updateExisting: true`
### Problem: Git validation failing
**Solution**: Ensure `projectPath` points to git repository root and git is initialized
### Problem: Thresholds not working as expected
**Solution**: Check that threshold values are positive numbers and units match your needs
## Integration with Other Tools
### With Sitemap Management
```bash
# Track freshness → Generate sitemap → Deploy
"track documentation freshness, then generate sitemap and deploy"
```
### With Content Validation
```bash
# Validate freshness → Validate content → Check links
"validate documentation freshness, then validate content and check links"
```
### With Gap Detection
```bash
# Detect gaps → Track freshness → Update documentation
"detect documentation gaps, track freshness, and update stale files"
```
## Next Steps
- [Site Monitoring](site-monitoring.md) - Monitor your documentation site health
- [SEO Optimization](seo-optimization.md) - Improve search engine visibility
- [Performance Optimization](performance-optimization.md) - Optimize documentation performance
- [MCP Tools Reference](../reference/mcp-tools.md#documentation-freshness-tracking-tools) - Complete API reference
```
--------------------------------------------------------------------------------
/tests/memory/learning.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Basic unit tests for Incremental Learning System
* Tests basic instantiation and core functionality
* Part of Issue #54 - Core Memory System Unit Tests
*/
import { promises as fs } from "fs";
import path from "path";
import os from "os";
import { MemoryManager } from "../../src/memory/manager.js";
import {
IncrementalLearningSystem,
ProjectFeatures,
} from "../../src/memory/learning.js";
describe("IncrementalLearningSystem", () => {
let tempDir: string;
let memoryManager: MemoryManager;
let learning: IncrementalLearningSystem;
beforeEach(async () => {
// Create unique temp directory for each test
tempDir = path.join(
os.tmpdir(),
`memory-learning-test-${Date.now()}-${Math.random()
.toString(36)
.substr(2, 9)}`,
);
await fs.mkdir(tempDir, { recursive: true });
// Create memory manager for learning system
memoryManager = new MemoryManager(tempDir);
await memoryManager.initialize();
learning = new IncrementalLearningSystem(memoryManager);
await learning.initialize();
});
afterEach(async () => {
// Cleanup temp directory
try {
await fs.rm(tempDir, { recursive: true, force: true });
} catch (error) {
// Ignore cleanup errors
}
});
describe("Basic Learning System Tests", () => {
test("should create learning system instance", () => {
expect(learning).toBeDefined();
expect(learning).toBeInstanceOf(IncrementalLearningSystem);
});
test("should be able to enable and disable learning", () => {
learning.setLearningEnabled(false);
learning.setLearningEnabled(true);
// Just test that the methods exist and don't throw
expect(true).toBe(true);
});
test("should have pattern retrieval capabilities", async () => {
// Test pattern retrieval without throwing errors
const patterns = await learning.getPatterns();
expect(Array.isArray(patterns)).toBe(true);
});
test("should provide learning statistics", async () => {
const stats = await learning.getStatistics();
expect(stats).toBeDefined();
expect(typeof stats.totalPatterns).toBe("number");
expect(typeof stats.averageConfidence).toBe("number");
expect(Array.isArray(stats.insights)).toBe(true);
});
test("should handle clearing patterns", async () => {
await learning.clearPatterns();
// Verify patterns are cleared
const patterns = await learning.getPatterns();
expect(Array.isArray(patterns)).toBe(true);
expect(patterns.length).toBe(0);
});
test("should provide improved recommendations", async () => {
const projectFeatures: ProjectFeatures = {
language: "typescript",
framework: "react",
size: "medium" as const,
complexity: "moderate" as const,
hasTests: true,
hasCI: true,
hasDocs: false,
isOpenSource: true,
};
const baseRecommendation = {
recommended: "docusaurus",
confidence: 0.8,
score: 0.85,
};
const improved = await learning.getImprovedRecommendation(
projectFeatures,
baseRecommendation,
);
expect(improved).toBeDefined();
expect(improved.recommendation).toBeDefined();
expect(typeof improved.confidence).toBe("number");
expect(Array.isArray(improved.insights)).toBe(true);
});
test("should handle learning from memory entries", async () => {
const memoryEntry = await memoryManager.remember(
"recommendation",
{
recommended: "docusaurus",
confidence: 0.9,
language: { primary: "typescript" },
framework: { name: "react" },
},
{
projectId: "test-project",
ssg: "docusaurus",
},
);
// Learn from successful outcome
await learning.learn(memoryEntry, "success");
// Verify no errors thrown
expect(true).toBe(true);
});
});
describe("Learning Statistics and Analysis", () => {
test("should provide comprehensive learning statistics", async () => {
const stats = await learning.getStatistics();
expect(stats).toBeDefined();
expect(typeof stats.totalPatterns).toBe("number");
expect(typeof stats.averageConfidence).toBe("number");
expect(typeof stats.learningVelocity).toBe("number");
expect(typeof stats.patternsByType).toBe("object");
expect(Array.isArray(stats.insights)).toBe(true);
});
test("should handle multiple learning iterations", async () => {
const projectFeatures: ProjectFeatures = {
language: "javascript",
framework: "vue",
size: "small" as const,
complexity: "simple" as const,
hasTests: false,
hasCI: false,
hasDocs: true,
isOpenSource: false,
};
const baseRecommendation = {
recommended: "vuepress",
confidence: 0.7,
score: 0.75,
};
// Multiple learning cycles
for (let i = 0; i < 3; i++) {
const improved = await learning.getImprovedRecommendation(
projectFeatures,
baseRecommendation,
);
expect(improved.recommendation).toBeDefined();
}
expect(true).toBe(true);
});
});
describe("Error Handling", () => {
test("should handle empty patterns gracefully", async () => {
// Clear all patterns first
await learning.clearPatterns();
const patterns = await learning.getPatterns();
expect(Array.isArray(patterns)).toBe(true);
expect(patterns.length).toBe(0);
});
test("should handle learning with minimal data", async () => {
const projectFeatures: ProjectFeatures = {
language: "unknown",
size: "small" as const,
complexity: "simple" as const,
hasTests: false,
hasCI: false,
hasDocs: false,
isOpenSource: false,
};
const baseRecommendation = {
recommended: "jekyll",
confidence: 0.5,
};
const improved = await learning.getImprovedRecommendation(
projectFeatures,
baseRecommendation,
);
expect(improved).toBeDefined();
expect(improved.recommendation).toBeDefined();
});
test("should handle concurrent learning operations", async () => {
const promises = Array.from({ length: 3 }, async (_, i) => {
const projectFeatures: ProjectFeatures = {
language: "go",
size: "medium" as const,
complexity: "moderate" as const,
hasTests: true,
hasCI: true,
hasDocs: true,
isOpenSource: true,
};
const baseRecommendation = {
recommended: "hugo",
confidence: 0.8 + i * 0.02,
};
return learning.getImprovedRecommendation(
projectFeatures,
baseRecommendation,
);
});
const results = await Promise.all(promises);
expect(results.length).toBe(3);
results.forEach((result) => {
expect(result.recommendation).toBeDefined();
});
});
});
});
```
--------------------------------------------------------------------------------
/docs/how-to/analytics-setup.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.949Z"
last_validated: "2025-11-20T00:46:21.949Z"
auto_updated: false
update_frequency: monthly
---
# How to Use DocuMCP Deployment Analytics
This guide shows you how to access and use DocuMCP's built-in deployment analytics to track your documentation deployment success and patterns.
## Quick Setup
```bash
# Analyze deployment patterns:
"analyze my deployment history and provide insights"
```
## Analytics Overview
DocuMCP provides comprehensive **deployment analytics** to help you understand and optimize your documentation deployment process:
### Analytics Types
- **Deployment Success Tracking**: Monitor deployment success/failure rates
- **SSG Performance Analytics**: Compare static site generator effectiveness
- **Build Time Metrics**: Track deployment speed and optimization opportunities
- **Project Pattern Analysis**: Understand which configurations work best
### Built-in Analytics Features
- **Deployment Health Scoring**: 0-100 health score for your deployment pipeline
- **SSG Comparison**: Compare success rates across different static site generators
- **Trend Analysis**: Track deployment patterns over time
- **Knowledge Graph Integration**: Learn from deployment history for better recommendations
## Using Deployment Analytics
### Method 1: Generate Full Analytics Report
```bash
# Get comprehensive deployment analytics:
"analyze my deployments and provide a full report"
```
This will provide:
1. Overall deployment success rates
2. SSG performance comparison
3. Build time analysis
4. Project pattern insights
5. Recommendations for optimization
### Method 2: Specific Analytics Queries
#### Get SSG Statistics
```bash
# Analyze specific SSG performance:
"show me statistics for Docusaurus deployments"
```
#### Compare SSG Performance
```bash
# Compare multiple SSGs:
"compare deployment success rates between Hugo and Jekyll"
```
#### Get Deployment Health Score
```bash
# Check deployment pipeline health:
"what is my deployment health score?"
```
#### Analyze Deployment Trends
```bash
# View deployment trends over time:
"show me deployment trends for the last 30 days"
```
## Deployment Analytics Examples
### Sample Analytics Report
```typescript
// Example deployment analytics report structure
{
"summary": {
"totalProjects": 15,
"totalDeployments": 42,
"overallSuccessRate": 0.85,
"mostUsedSSG": "docusaurus",
"mostSuccessfulSSG": "hugo"
},
"patterns": [
{
"ssg": "docusaurus",
"totalDeployments": 18,
"successfulDeployments": 16,
"failedDeployments": 2,
"successRate": 0.89,
"averageBuildTime": 45000,
"projectCount": 8
}
],
"insights": [
{
"type": "success",
"title": "High Success Rate",
"description": "Excellent! 85% of deployments succeed"
}
]
}
```
### Health Score Breakdown
```typescript
// Example health score analysis
{
"score": 78,
"factors": [
{
"name": "Overall Success Rate",
"impact": 34,
"status": "good"
},
{
"name": "Active Projects",
"impact": 20,
"status": "good"
},
{
"name": "Deployment Activity",
"impact": 15,
"status": "warning"
},
{
"name": "SSG Diversity",
"impact": 9,
"status": "warning"
}
]
}
```
### MCP Tool Integration
```typescript
// Using the analyze_deployments MCP tool directly
import { analyzeDeployments } from "./dist/tools/analyze-deployments.js";
// Get full analytics report
const report = await analyzeDeployments({
analysisType: "full_report",
});
// Get specific SSG statistics
const docusaurusStats = await analyzeDeployments({
analysisType: "ssg_stats",
ssg: "docusaurus",
});
// Compare multiple SSGs
const comparison = await analyzeDeployments({
analysisType: "compare",
ssgs: ["hugo", "jekyll", "docusaurus"],
});
// Get deployment health score
const health = await analyzeDeployments({
analysisType: "health",
});
```
## Advanced Deployment Analytics
### Deployment Pattern Analysis
```bash
# Analyze deployment patterns by technology:
"show me deployment success patterns for TypeScript projects"
# Analyze by project size:
"compare deployment success rates for small vs large projects"
# Analyze by team size:
"show deployment patterns for different team sizes"
```
### Knowledge Graph Insights
```bash
# Get insights from deployment history:
"what SSG works best for React projects based on deployment history?"
# Learn from similar projects:
"recommend deployment strategy based on similar successful projects"
# Analyze failure patterns:
"what are the common causes of deployment failures?"
```
### Trend Analysis
```bash
# Analyze deployment trends:
"show me deployment success trends over the last 6 months"
# Compare time periods:
"compare deployment performance between Q3 and Q4"
# Identify improvement opportunities:
"what deployment metrics have improved recently?"
```
## Troubleshooting
### Common Issues
**Problem**: No deployment data available
**Solution**: Deploy at least one project to start collecting analytics data
**Problem**: Analytics tool returns empty results
**Solution**: Ensure knowledge graph storage directory exists and has proper permissions
**Problem**: Health score seems low
**Solution**: Review deployment failures and optimize SSG configurations
**Problem**: Missing deployment history
**Solution**: Check that deployment tracking is enabled in knowledge graph
### Analytics Debugging
```bash
# Debug deployment analytics issues:
"check my deployment analytics configuration and data availability"
```
## Best Practices
### Deployment Analytics Guidelines
1. **Regular Deployments**: Deploy frequently to build meaningful analytics data
2. **Track Failures**: Learn from deployment failures to improve success rates
3. **Monitor Trends**: Review analytics weekly to identify patterns
4. **Compare SSGs**: Use analytics to choose the best SSG for each project type
5. **Health Monitoring**: Keep deployment health score above 70
### Data Quality
1. **Consistent Tracking**: Ensure all deployments are tracked in knowledge graph
2. **Clean Data**: Review and clean up failed deployment records periodically
3. **Regular Analysis**: Run analytics reports monthly to identify trends
4. **Documentation**: Document deployment patterns and insights
5. **Team Sharing**: Share analytics insights with your development team
## Deployment Analytics Tools
### Built-in DocuMCP Analytics
- **Deployment success tracking**: Monitor success/failure rates
- **SSG performance analysis**: Compare static site generator effectiveness
- **Build time metrics**: Track deployment speed and optimization opportunities
- **Knowledge graph insights**: Learn from deployment history patterns
### MCP Tools Available
- `analyze_deployments`: Generate comprehensive deployment analytics
- `deploy_pages`: Track deployment attempts and outcomes
- `recommend_ssg`: Get SSG recommendations based on analytics
## Next Steps
- [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
- [SSG Recommendations](../reference/mcp-tools.md#recommend_ssg)
- [Knowledge Graph](../knowledge-graph.md)
- [Troubleshooting](troubleshooting.md)
```
--------------------------------------------------------------------------------
/src/tools/verify-deployment.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from "zod";
import { promises as fs } from "fs";
import path from "path";
import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
const inputSchema = z.object({
repository: z.string(),
url: z.string().optional(),
});
interface DeploymentCheck {
check: string;
status: "pass" | "fail" | "warning";
message: string;
recommendation?: string;
}
export async function verifyDeployment(
args: unknown,
): Promise<{ content: any[] }> {
const startTime = Date.now();
const { repository, url } = inputSchema.parse(args);
try {
const checks: DeploymentCheck[] = [];
// Determine repository path
const repoPath = repository.startsWith("http") ? "." : repository;
// Check 1: GitHub Actions workflow exists
const workflowPath = path.join(repoPath, ".github", "workflows");
try {
const workflows = await fs.readdir(workflowPath);
const deployWorkflow = workflows.find(
(f) =>
f.includes("deploy") || f.includes("pages") || f.includes("docs"),
);
if (deployWorkflow) {
checks.push({
check: "GitHub Actions Workflow",
status: "pass",
message: `Found deployment workflow: ${deployWorkflow}`,
});
} else {
checks.push({
check: "GitHub Actions Workflow",
status: "fail",
message: "No deployment workflow found",
recommendation: "Run deploy_pages tool to create a workflow",
});
}
} catch {
checks.push({
check: "GitHub Actions Workflow",
status: "fail",
message: "No .github/workflows directory found",
recommendation: "Run deploy_pages tool to set up GitHub Actions",
});
}
// Check 2: Documentation source files exist
const docsPaths = ["docs", "documentation", "site", "content"];
let docsFound = false;
for (const docsPath of docsPaths) {
try {
const fullPath = path.join(repoPath, docsPath);
const stats = await fs.stat(fullPath);
if (stats.isDirectory()) {
const files = await fs.readdir(fullPath);
const mdFiles = files.filter(
(f) => f.endsWith(".md") || f.endsWith(".mdx"),
);
if (mdFiles.length > 0) {
docsFound = true;
checks.push({
check: "Documentation Source Files",
status: "pass",
message: `Found ${mdFiles.length} documentation files in ${docsPath}/`,
});
break;
}
}
} catch {
// Directory doesn't exist, continue checking
}
}
if (!docsFound) {
checks.push({
check: "Documentation Source Files",
status: "warning",
message: "No documentation files found in standard locations",
recommendation:
"Run setup_structure tool to create documentation structure",
});
}
// Check 3: Configuration files
const configPatterns = [
"docusaurus.config.js",
"mkdocs.yml",
"hugo.toml",
"hugo.yaml",
"_config.yml",
".eleventy.js",
];
let configFound = false;
for (const config of configPatterns) {
try {
await fs.access(path.join(repoPath, config));
configFound = true;
checks.push({
check: "SSG Configuration",
status: "pass",
message: `Found configuration file: ${config}`,
});
break;
} catch {
// File doesn't exist, continue
}
}
if (!configFound) {
checks.push({
check: "SSG Configuration",
status: "fail",
message: "No static site generator configuration found",
recommendation: "Run generate_config tool to create SSG configuration",
});
}
// Check 4: Build output directory
const buildDirs = ["_site", "build", "dist", "public", "out"];
let buildFound = false;
for (const buildDir of buildDirs) {
try {
const buildPath = path.join(repoPath, buildDir);
const stats = await fs.stat(buildPath);
if (stats.isDirectory()) {
buildFound = true;
checks.push({
check: "Build Output",
status: "pass",
message: `Found build output directory: ${buildDir}/`,
});
break;
}
} catch {
// Directory doesn't exist
}
}
if (!buildFound) {
checks.push({
check: "Build Output",
status: "warning",
message: "No build output directory found",
recommendation: "Run your SSG build command to generate the site",
});
}
// Check 5: GitHub Pages settings (if URL provided)
if (url) {
checks.push({
check: "Deployment URL",
status: "warning",
message: `Expected URL: ${url}`,
recommendation: "Verify GitHub Pages is enabled in repository settings",
});
}
// Generate summary
const passCount = checks.filter((c) => c.status === "pass").length;
const failCount = checks.filter((c) => c.status === "fail").length;
const warningCount = checks.filter((c) => c.status === "warning").length;
let overallStatus = "Ready for deployment";
if (failCount > 0) {
overallStatus = "Configuration required";
} else if (warningCount > 0) {
overallStatus = "Minor issues detected";
}
const verificationResult = {
repository,
url,
overallStatus,
checks,
summary: {
passed: passCount,
warnings: warningCount,
failed: failCount,
total: checks.length,
},
};
const response: MCPToolResponse<typeof verificationResult> = {
success: true,
data: verificationResult,
metadata: {
toolVersion: "1.0.0",
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString(),
},
recommendations: [
{
type:
failCount > 0 ? "critical" : warningCount > 0 ? "warning" : "info",
title: "Deployment Verification Complete",
description: `${overallStatus}. ${passCount} checks passed, ${warningCount} warnings, ${failCount} failures.`,
},
],
nextSteps: checks
.filter((check) => check.recommendation)
.map((check) => ({
action: check.recommendation!,
toolRequired: check.recommendation!.includes("deploy_pages")
? "deploy_pages"
: check.recommendation!.includes("setup_structure")
? "setup_structure"
: check.recommendation!.includes("generate_config")
? "generate_config"
: "manual",
description: check.message,
priority: check.status === "fail" ? "high" : ("medium" as const),
})),
};
return formatMCPResponse(response);
} catch (error) {
const errorResponse: MCPToolResponse = {
success: false,
error: {
code: "VERIFICATION_FAILED",
message: `Failed to verify deployment: ${error}`,
resolution: "Ensure repository path is accessible",
},
metadata: {
toolVersion: "1.0.0",
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString(),
},
};
return formatMCPResponse(errorResponse);
}
}
// Removed unused getStatusEmoji function - status indicators now handled in formatMCPResponse
```
--------------------------------------------------------------------------------
/.github/copilot-instructions.md:
--------------------------------------------------------------------------------
```markdown
# DocuMCP AI Coding Agent Instructions
DocuMCP is an intelligent MCP server for GitHub Pages documentation deployment with 45+ tools, Knowledge Graph memory system, and AST-based code analysis.
## Architecture Essentials
### MCP Server Design (src/index.ts)
- **Stateless operation**: Each tool analyzes current state; no persistent session data
- **Resource storage**: Temporary session context in `resourceStore` Map with URIs like `documcp://analysis/{id}`
- **Response format**: ALL tools MUST use `formatMCPResponse()` from `src/types/api.ts` returning `MCPToolResponse`
- **Memory integration**: Tools auto-store results in JSONL (`.documcp/memory/`) and query historical data
### Tool Implementation Pattern
Every tool follows this structure:
1. Zod schema for input validation (e.g., `inputSchema.parse()`)
2. Business logic with error handling
3. Return via `formatMCPResponse({ success, data, metadata, recommendations?, nextSteps? })`
4. Store result as resource: `storeResourceFromToolResult(result, 'analysis', analysis.id)`
**Example** (see `src/tools/analyze-repository.ts`):
```typescript
const inputSchema = z.object({
path: z.string(),
depth: z.enum(["quick", "standard", "deep"]).optional(),
});
export async function analyzeRepository(
args: unknown,
): Promise<MCPToolResponse> {
const input = inputSchema.parse(args);
// ... logic ...
return formatMCPResponse({
success: true,
data: analysis,
metadata: { toolVersion, executionTime, timestamp },
});
}
```
### Knowledge Graph Memory (src/memory/)
- **Entities**: Project, User, Configuration, Technology, CodeFile, DocumentationSection (see `src/memory/schemas.ts`)
- **Relationships**: `project_uses_technology`, `project_deployed_with`, `similar_to`, `documents`, etc.
- **Storage**: `.documcp/memory/knowledge-graph-entities.jsonl` and `knowledge-graph-relationships.jsonl`
- **Integration**: Use `createOrUpdateProject()`, `getProjectContext()`, `trackDeployment()` from `src/memory/kg-integration.ts`
**analyze_repository enhancement**: Retrieves project history before analysis, shows previous analysis count, similar projects
## Development Workflows
### Essential Commands
```bash
npm run build # Compile TypeScript → dist/
npm run dev # Development watch mode with tsx
npm test # Run Jest test suite
npm run test:coverage # Coverage report (80% threshold)
npm run build:inspect # Launch MCP Inspector for interactive testing
npm run ci # Full CI pipeline: typecheck + lint + test + build
make qa # Quality assurance: lint + types + test + coverage
```
### Testing Strategy
- **Location**: `tests/` mirroring `src/` structure
- **Coverage**: 80% global (branches/functions/lines), 60% for `recommend-ssg.ts` (complex logic)
- **Excluded**: Experimental memory features, `src/index.ts` entry point
- **Pattern**: Use `formatMCPResponse()` for consistent response validation
- **Integration**: Multi-tool workflow tests in `tests/integration/`
### MCP Inspector Workflow
1. `npm run build:inspect` opens browser at `http://localhost:5173`
2. Click "Connect" to attach to server
3. Test tools with custom parameters interactively
4. Verify resources/prompts without full integration
## Project-Specific Conventions
### ESM Module Requirements
- **ALL imports** must end with `.js` (even for `.ts` files): `import { foo } from './utils.js'`
- Use `import type` for type-only imports: `import type { MyType } from './types.js'`
- File URLs: `fileURLToPath(import.meta.url)` and `dirname()`
### Path & Permission Handling
- **Security**: Use `isPathAllowed(path, allowedRoots)` from `src/utils/permission-checker.ts` before file operations
- **Async FS**: Always use `fs.promises` API, never sync methods
- **Cross-platform**: Use `path` module for joining/resolving
### Git Integration
- Use `simple-git` library for repository operations
- Handle missing `.git` directories gracefully (check `hasGit` flag)
- Always validate repo state before analysis
### Diataxis Framework
Documentation structured as:
- **Tutorials**: Learning-oriented (getting started)
- **How-To Guides**: Problem-solving (specific tasks)
- **Reference**: Information-oriented (API docs)
- **Explanation**: Understanding-oriented (architecture, concepts)
Tools like `setup-structure` and `populate-content` enforce this structure.
## Critical Implementation Details
### Phase 3: AST-Based Code Analysis
- **AST Parser** (`src/utils/ast-analyzer.ts`): Multi-language support via Tree-sitter (TypeScript, Python, Go, Rust, Java, Ruby, Bash)
- **Drift Detection** (`src/utils/drift-detector.ts`): Snapshot-based comparison, categorizes changes (breaking/major/minor/patch)
- **Sync Tool** (`src/tools/sync-code-to-docs.ts`): Modes: detect/preview/apply/auto, confidence threshold (default 0.8)
- **Content Generator** (`src/tools/generate-contextual-content.ts`): Creates Diataxis-compliant docs from actual code structure
**Example drift detection**:
```typescript
// Detects function signature changes, new/removed classes, breaking changes
const drift = await detectDrift({ projectPath, docsPath, snapshotDir });
drift.affectedFiles.forEach((f) => console.log(f.driftType, f.severity));
```
### Error Handling Pattern
```typescript
try {
// tool logic
return formatMCPResponse({ success: true, data: result, metadata });
} catch (error) {
return formatMCPResponse({
success: false,
error: {
code: "TOOL_ERROR",
message: error.message,
resolution: "Check inputs and try again",
},
metadata,
});
}
```
### Adding New Tools Checklist
1. Create `src/tools/my-tool.ts` with Zod schema and logic
2. Export tool function returning `MCPToolResponse`
3. Add to `TOOLS` array in `src/index.ts` with name, description, inputSchema
4. Add handler in `CallToolRequestSchema` switch case
5. Store result: `storeResourceFromToolResult(result, 'type', id)`
6. Create tests: `tests/tools/my-tool.test.ts`
7. Run `npm run ci` to validate
## Key Integration Points
### Memory Query Patterns
```typescript
// Query similar projects by analysis results
const similar = await getSimilarProjects(analysisResult, limit);
// Get project insights with historical context
const insights = await getProjectInsights(projectPath);
// Export/import memory for backup
await exportMemories({ outputPath: "./backup.json" });
await importMemories({ inputPath: "./backup.json" });
```
### Resource Storage Pattern
```typescript
// Tools create resources for cross-tool reference
resourceStore.set(`documcp://analysis/${id}`, {
uri: `documcp://analysis/${id}`,
name: `Repository Analysis ${id}`,
mimeType: "application/json",
text: JSON.stringify(result, null, 2),
});
```
### ADR References
- **ADR-001**: TypeScript MCP SDK chosen over Python/Go for ecosystem maturity
- **ADR-002**: Multi-layered repository analysis (structure + dependencies + documentation)
- **ADR-003**: Algorithmic SSG recommendation with confidence scoring
- **ADR-006**: Consistent tool API design with Zod validation
- **ADR-010**: Resource pattern redesign for session-based storage
Full ADRs: `docs/adrs/`
## Common Pitfalls
- ❌ Forgetting `.js` extension in imports → Module resolution fails
- ❌ Using `formatMCPResponse()` incorrectly → Response validation errors
- ❌ Missing Zod schema validation → Runtime type errors
- ❌ Synchronous file operations → Blocking operations
- ❌ Not checking path permissions → Security vulnerabilities
- ❌ Returning raw objects instead of `MCPToolResponse` → Protocol violations
## Quick Reference
**Node.js**: ≥20.0.0 | **Module**: ESM | **Test Framework**: Jest (ts-jest) | **Storage**: `.documcp/memory/` (JSONL)
**MCP Inspector**: `npm run build:inspect` | **Full test suite**: `npm run ci` | **Docs**: `docs/` (Docusaurus)
```
--------------------------------------------------------------------------------
/docs/guides/link-validation.md:
--------------------------------------------------------------------------------
```markdown
---
documcp:
last_updated: "2025-11-20T00:46:21.947Z"
last_validated: "2025-11-20T00:46:21.947Z"
auto_updated: false
update_frequency: monthly
---
# Link Validation in Knowledge Graph
## Overview
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.
## Architecture
### Components
1. **kg-link-validator.ts** - Core link validation module
2. **kg-code-integration.ts** - Automatic validation during doc analysis
3. **Knowledge Graph** - Stores validation results as entities
### Entity Type: `link_validation`
```typescript
{
totalLinks: number; // Total links found
validLinks: number; // Links that returned HTTP 200
brokenLinks: number; // Links that failed (404, timeout, etc.)
warningLinks: number; // Links that were skipped
unknownLinks: number; // Links that couldn't be validated
healthScore: number; // 0-100 score based on valid/total
lastValidated: string; // ISO 8601 timestamp
brokenLinksList: string[]; // Array of broken link URLs
}
```
### Relationships
1. **has_link_validation**: `documentation_section` → `link_validation`
- Connects docs to their validation results
2. **requires_fix**: `link_validation` → `documentation_section`
- Created when broken links are detected
- Properties:
- `severity`: "high" (>5 broken) or "medium" (1-5 broken)
- `brokenLinkCount`: Number of broken links
- `detectedAt`: ISO timestamp
## How It Works
### 1. Automatic Validation During Analysis
When `analyze_repository` runs, it:
1. Extracts documentation content
2. Creates documentation entities in KG
3. **Automatically validates external links** (async, non-blocking)
4. Stores validation results in KG
```typescript
// In kg-code-integration.ts
for (const doc of extractedContent.existingDocs) {
const docNode = createDocSectionEntity(
projectId,
doc.path,
doc.title,
doc.content,
);
kg.addNode(docNode);
// Validate links in background
validateAndStoreDocumentationLinks(docNode.id, doc.content).catch((error) =>
console.warn(`Failed to validate links: ${error.message}`),
);
}
```
### 2. Link Extraction
Supports both Markdown and HTML formats:
```markdown
<!-- Markdown links -->
[GitHub](https://github.com)
<!-- HTML links -->
<a href="https://example.com">Link</a>
```
### 3. Validation Strategy
Uses native Node.js `fetch` API with:
- **HTTP HEAD requests** (faster than GET)
- **5-second timeout** (configurable)
- **Retry logic** (2 retries by default)
- **Concurrent checking** (up to 10 simultaneous)
```typescript
const result = await validateExternalLinks(urls, {
timeout: 5000, // 5 seconds
retryCount: 2, // Retry failed links
concurrency: 10, // Check 10 links at once
});
```
### 4. Storage in Knowledge Graph
Results are stored as entities and can be queried:
```typescript
// Get validation history for a doc section
const history = await getLinkValidationHistory(docSectionId);
// Latest validation
const latest = history[0];
console.log(`Health Score: ${latest.properties.healthScore}%`);
console.log(`Broken Links: ${latest.properties.brokenLinks}`);
```
## Usage Examples
### Query Broken Links
```typescript
import { getKnowledgeGraph } from "./memory/kg-integration.js";
const kg = await getKnowledgeGraph();
// Find all link validation entities with broken links
const allNodes = await kg.getAllNodes();
const validations = allNodes.filter(
(n) => n.type === "link_validation" && n.properties.brokenLinks > 0,
);
validations.forEach((v) => {
console.log(`Found ${v.properties.brokenLinks} broken links:`);
v.properties.brokenLinksList.forEach((url) => console.log(` - ${url}`));
});
```
### Get Documentation Health Report
```typescript
import { getKnowledgeGraph } from "./memory/kg-integration.js";
const kg = await getKnowledgeGraph();
// Find all documentation sections
const docSections = (await kg.getAllNodes()).filter(
(n) => n.type === "documentation_section",
);
for (const doc of docSections) {
// Get validation results
const edges = await kg.findEdges({
source: doc.id,
type: "has_link_validation",
});
if (edges.length > 0) {
const validationId = edges[0].target;
const validation = (await kg.getAllNodes()).find(
(n) => n.id === validationId,
);
if (validation) {
console.log(`\n${doc.properties.filePath}:`);
console.log(` Health: ${validation.properties.healthScore}%`);
console.log(` Valid: ${validation.properties.validLinks}`);
console.log(` Broken: ${validation.properties.brokenLinks}`);
}
}
}
```
### Manual Validation
```typescript
import {
validateExternalLinks,
storeLinkValidationInKG,
} from "./memory/kg-link-validator.js";
// Validate specific URLs
const result = await validateExternalLinks([
"https://github.com",
"https://example.com/404",
]);
console.log(result);
// {
// totalLinks: 2,
// validLinks: 1,
// brokenLinks: 1,
// results: [...]
// }
// Store in KG
await storeLinkValidationInKG(docSectionId, result);
```
## Integration with analyze_repository
The `analyze_repository` tool now includes link validation data:
```json
{
"success": true,
"data": {
"intelligentAnalysis": {
"documentationHealth": {
"outdatedCount": 2,
"coveragePercent": 85,
"totalCodeFiles": 20,
"documentedFiles": 17,
"linkHealth": {
"totalLinks": 45,
"brokenLinks": 3,
"healthScore": 93
}
}
}
}
}
```
## Configuration
### Environment Variables
```bash
# Link validation timeout (milliseconds)
DOCUMCP_LINK_TIMEOUT=5000
# Maximum retries for failed links
DOCUMCP_LINK_RETRIES=2
# Concurrent link checks
DOCUMCP_LINK_CONCURRENCY=10
```
### Skip Link Validation
Link validation is non-blocking and runs in the background. If it fails, it logs a warning but doesn't stop the analysis.
## Performance Considerations
1. **Non-blocking**: Validation runs asynchronously after doc entities are created
2. **Cached Results**: Results stored in KG, no re-validation on subsequent reads
3. **Concurrent Checking**: Validates up to 10 links simultaneously
4. **Smart Timeouts**: 5-second timeout prevents hanging on slow servers
## Troubleshooting
### Links Not Being Validated
**Issue**: Documentation sections have no validation results
**Check**:
1. Are there external links in the content?
2. Check console for warnings: `Failed to validate links in...`
3. Verify network connectivity
### False Positives
**Issue**: Valid links marked as broken
**Solutions**:
1. Increase timeout: Some servers respond slowly
2. Check if server blocks HEAD requests (rare)
3. Verify URL is publicly accessible (not behind auth)
### Memory Storage Not Updated
**Issue**: KG doesn't show validation results
**Check**:
```typescript
import { saveKnowledgeGraph } from "./memory/kg-integration.js";
// Manually save KG
await saveKnowledgeGraph();
```
## Future Enhancements
1. **AST-based Internal Link Validation**
- Verify internal file references exist
- Check anchor links (`#section-id`)
2. **Link Health Trends**
- Track link health over time
- Alert on degrading link quality
3. **Batch Re-validation**
- MCP tool to re-check all links
- Scheduled validation for long-lived projects
4. **Link Recommendation**
- Suggest fixing broken links
- Recommend archive.org alternatives for dead links
## Dependencies
- **linkinator** (v6.1.4) - Link validation library (installed)
- **native fetch** - Node.js 20+ built-in HTTP client
## Related Documentation
- [Architecture Decision Records](../adrs/)
- [Phase 2: Intelligence & Learning System](../phase-2-intelligence.md)
- [Memory Workflows Tutorial](../tutorials/memory-workflows.md)
```
--------------------------------------------------------------------------------
/src/memory/kg-link-validator.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Knowledge Graph Link Validator
* Validates external and internal links in documentation and stores results in KG
*/
import crypto from "crypto";
import { getKnowledgeGraph } from "./kg-integration.js";
import { GraphNode } from "./knowledge-graph.js";
export interface LinkValidationResult {
url: string;
status: "valid" | "broken" | "warning" | "unknown";
statusCode?: number;
errorMessage?: string;
lastChecked: string;
responseTime?: number;
}
export interface LinkValidationSummary {
totalLinks: number;
validLinks: number;
brokenLinks: number;
warningLinks: number;
unknownLinks: number;
results: LinkValidationResult[];
}
/**
* Validate external links in documentation content
*/
export async function validateExternalLinks(
urls: string[],
options?: {
timeout?: number;
retryCount?: number;
concurrency?: number;
},
): Promise<LinkValidationSummary> {
const _timeout = options?.timeout || 5000;
// const _retryCount = options?.retryCount || 2;
// const _concurrency = options?.concurrency || 10;
const results: LinkValidationResult[] = [];
const summary: LinkValidationSummary = {
totalLinks: urls.length,
validLinks: 0,
brokenLinks: 0,
warningLinks: 0,
unknownLinks: 0,
results: [],
};
// Create a temporary HTML file with all links to validate
// const _tempHtml = `<html><body>${urls
// .map((url) => `<a href="${url}">${url}</a>`)
// .join("\n")}</body></html>`;
try {
// Use individual validation for now (linkinator API is complex)
// TODO: Optimize with linkinator's batch checking in future
for (const url of urls) {
try {
const result = await validateSingleLink(url, _timeout);
results.push(result);
if (result.status === "valid") summary.validLinks++;
else if (result.status === "broken") summary.brokenLinks++;
else if (result.status === "warning") summary.warningLinks++;
else summary.unknownLinks++;
} catch {
results.push({
url,
status: "unknown",
errorMessage: "Validation failed",
lastChecked: new Date().toISOString(),
});
summary.unknownLinks++;
}
}
} catch (error) {
console.warn("Link validation error:", error);
}
summary.results = results;
return summary;
}
/**
* Validate a single link with HTTP HEAD request
*/
async function validateSingleLink(
url: string,
timeout: number,
): Promise<LinkValidationResult> {
const startTime = Date.now();
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);
const response = await fetch(url, {
method: "HEAD",
signal: controller.signal,
redirect: "follow",
});
clearTimeout(timeoutId);
const responseTime = Date.now() - startTime;
if (response.ok) {
return {
url,
status: "valid",
statusCode: response.status,
lastChecked: new Date().toISOString(),
responseTime,
};
} else {
return {
url,
status: "broken",
statusCode: response.status,
errorMessage: `HTTP ${response.status}: ${response.statusText}`,
lastChecked: new Date().toISOString(),
responseTime,
};
}
} catch (error: any) {
return {
url,
status: "broken",
errorMessage: error.message || "Network error",
lastChecked: new Date().toISOString(),
};
}
}
/**
* Store link validation results in Knowledge Graph
*/
export async function storeLinkValidationInKG(
docSectionId: string,
validationSummary: LinkValidationSummary,
): Promise<void> {
const kg = await getKnowledgeGraph();
// Create link validation entity
const validationId = `link_validation:${crypto
.randomBytes(8)
.toString("hex")}`;
const validationNode: GraphNode = {
id: validationId,
type: "link_validation",
label: "Link Validation Result",
properties: {
totalLinks: validationSummary.totalLinks,
validLinks: validationSummary.validLinks,
brokenLinks: validationSummary.brokenLinks,
warningLinks: validationSummary.warningLinks,
unknownLinks: validationSummary.unknownLinks,
healthScore:
validationSummary.totalLinks > 0
? (validationSummary.validLinks / validationSummary.totalLinks) * 100
: 100,
lastValidated: new Date().toISOString(),
brokenLinksList: validationSummary.results
.filter((r) => r.status === "broken")
.map((r) => r.url),
},
weight: 1.0,
lastUpdated: new Date().toISOString(),
};
kg.addNode(validationNode);
// Create relationship: documentation_section -> link_validation
kg.addEdge({
source: docSectionId,
target: validationId,
type: "has_link_validation",
weight: 1.0,
confidence: 1.0,
properties: {
validatedAt: new Date().toISOString(),
hasBrokenLinks: validationSummary.brokenLinks > 0,
needsAttention: validationSummary.brokenLinks > 0,
},
});
// If there are broken links, create "requires_fix" edges
if (validationSummary.brokenLinks > 0) {
kg.addEdge({
source: validationId,
target: docSectionId,
type: "requires_fix",
weight: validationSummary.brokenLinks / validationSummary.totalLinks,
confidence: 1.0,
properties: {
severity: validationSummary.brokenLinks > 5 ? "high" : "medium",
brokenLinkCount: validationSummary.brokenLinks,
detectedAt: new Date().toISOString(),
},
});
}
}
/**
* Get link validation history from Knowledge Graph
*/
export async function getLinkValidationHistory(
docSectionId: string,
): Promise<GraphNode[]> {
const kg = await getKnowledgeGraph();
const edges = await kg.findEdges({
source: docSectionId,
type: "has_link_validation",
});
const validationNodes: GraphNode[] = [];
const allNodes = await kg.getAllNodes();
for (const edge of edges) {
const validationNode = allNodes.find((n) => n.id === edge.target);
if (validationNode) {
validationNodes.push(validationNode);
}
}
// Sort by lastValidated (newest first)
return validationNodes.sort(
(a, b) =>
new Date(b.properties.lastValidated).getTime() -
new Date(a.properties.lastValidated).getTime(),
);
}
/**
* Extract links from documentation content
*/
export function extractLinksFromContent(content: string): {
externalLinks: string[];
internalLinks: string[];
} {
const externalLinks: string[] = [];
const internalLinks: string[] = [];
// Markdown links: [text](url)
const markdownLinkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
let match;
while ((match = markdownLinkRegex.exec(content)) !== null) {
const url = match[2];
if (url.startsWith("http://") || url.startsWith("https://")) {
externalLinks.push(url);
} else {
internalLinks.push(url);
}
}
// HTML links: <a href="url">
const htmlLinkRegex = /<a\s+(?:[^>]*?\s+)?href=(["'])(.*?)\1/gi;
while ((match = htmlLinkRegex.exec(content)) !== null) {
const url = match[2];
if (url.startsWith("http://") || url.startsWith("https://")) {
externalLinks.push(url);
} else {
internalLinks.push(url);
}
}
return {
externalLinks: [...new Set(externalLinks)], // Remove duplicates
internalLinks: [...new Set(internalLinks)],
};
}
/**
* Validate all links in a documentation section and store in KG
*/
export async function validateAndStoreDocumentationLinks(
docSectionId: string,
content: string,
): Promise<LinkValidationSummary> {
const { externalLinks } = extractLinksFromContent(content);
if (externalLinks.length === 0) {
return {
totalLinks: 0,
validLinks: 0,
brokenLinks: 0,
warningLinks: 0,
unknownLinks: 0,
results: [],
};
}
const validationSummary = await validateExternalLinks(externalLinks);
await storeLinkValidationInKG(docSectionId, validationSummary);
return validationSummary;
}
```