This is page 2 of 29. Use http://codebase.md/tosin2013/documcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .dockerignore
├── .eslintignore
├── .eslintrc.json
├── .github
│ ├── agents
│ │ ├── documcp-ast.md
│ │ ├── documcp-deploy.md
│ │ ├── documcp-memory.md
│ │ ├── documcp-test.md
│ │ └── documcp-tool.md
│ ├── copilot-instructions.md
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── automated-changelog.md
│ │ ├── bug_report.md
│ │ ├── bug_report.yml
│ │ ├── documentation_issue.md
│ │ ├── feature_request.md
│ │ ├── feature_request.yml
│ │ ├── npm-publishing-fix.md
│ │ └── release_improvements.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── auto-merge.yml
│ ├── ci.yml
│ ├── codeql.yml
│ ├── dependency-review.yml
│ ├── deploy-docs.yml
│ ├── README.md
│ ├── release-drafter.yml
│ └── release.yml
├── .gitignore
├── .husky
│ ├── commit-msg
│ └── pre-commit
├── .linkcheck.config.json
├── .markdown-link-check.json
├── .nvmrc
├── .pre-commit-config.yaml
├── .versionrc.json
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── commitlint.config.js
├── CONTRIBUTING.md
├── docker-compose.docs.yml
├── Dockerfile.docs
├── docs
│ ├── .docusaurus
│ │ ├── docusaurus-plugin-content-docs
│ │ │ └── default
│ │ │ └── __mdx-loader-dependency.json
│ │ └── docusaurus-plugin-content-pages
│ │ └── default
│ │ └── __plugin.json
│ ├── adrs
│ │ ├── 001-mcp-server-architecture.md
│ │ ├── 002-repository-analysis-engine.md
│ │ ├── 003-static-site-generator-recommendation-engine.md
│ │ ├── 004-diataxis-framework-integration.md
│ │ ├── 005-github-pages-deployment-automation.md
│ │ ├── 006-mcp-tools-api-design.md
│ │ ├── 007-mcp-prompts-and-resources-integration.md
│ │ ├── 008-intelligent-content-population-engine.md
│ │ ├── 009-content-accuracy-validation-framework.md
│ │ ├── 010-mcp-resource-pattern-redesign.md
│ │ └── README.md
│ ├── api
│ │ ├── .nojekyll
│ │ ├── assets
│ │ │ ├── hierarchy.js
│ │ │ ├── highlight.css
│ │ │ ├── icons.js
│ │ │ ├── icons.svg
│ │ │ ├── main.js
│ │ │ ├── navigation.js
│ │ │ ├── search.js
│ │ │ └── style.css
│ │ ├── hierarchy.html
│ │ ├── index.html
│ │ ├── modules.html
│ │ └── variables
│ │ └── TOOLS.html
│ ├── assets
│ │ └── logo.svg
│ ├── development
│ │ └── MCP_INSPECTOR_TESTING.md
│ ├── docusaurus.config.js
│ ├── explanation
│ │ ├── architecture.md
│ │ └── index.md
│ ├── guides
│ │ ├── link-validation.md
│ │ ├── playwright-integration.md
│ │ └── playwright-testing-workflow.md
│ ├── how-to
│ │ ├── analytics-setup.md
│ │ ├── custom-domains.md
│ │ ├── documentation-freshness-tracking.md
│ │ ├── github-pages-deployment.md
│ │ ├── index.md
│ │ ├── local-testing.md
│ │ ├── performance-optimization.md
│ │ ├── prompting-guide.md
│ │ ├── repository-analysis.md
│ │ ├── seo-optimization.md
│ │ ├── site-monitoring.md
│ │ ├── troubleshooting.md
│ │ └── usage-examples.md
│ ├── index.md
│ ├── knowledge-graph.md
│ ├── package-lock.json
│ ├── package.json
│ ├── phase-2-intelligence.md
│ ├── reference
│ │ ├── api-overview.md
│ │ ├── cli.md
│ │ ├── configuration.md
│ │ ├── deploy-pages.md
│ │ ├── index.md
│ │ ├── mcp-tools.md
│ │ └── prompt-templates.md
│ ├── research
│ │ ├── cross-domain-integration
│ │ │ └── README.md
│ │ ├── domain-1-mcp-architecture
│ │ │ ├── index.md
│ │ │ └── mcp-performance-research.md
│ │ ├── domain-2-repository-analysis
│ │ │ └── README.md
│ │ ├── domain-3-ssg-recommendation
│ │ │ ├── index.md
│ │ │ └── ssg-performance-analysis.md
│ │ ├── domain-4-diataxis-integration
│ │ │ └── README.md
│ │ ├── domain-5-github-deployment
│ │ │ ├── github-pages-security-analysis.md
│ │ │ └── index.md
│ │ ├── domain-6-api-design
│ │ │ └── README.md
│ │ ├── README.md
│ │ ├── research-integration-summary-2025-01-14.md
│ │ ├── research-progress-template.md
│ │ └── research-questions-2025-01-14.md
│ ├── robots.txt
│ ├── sidebars.js
│ ├── sitemap.xml
│ ├── src
│ │ └── css
│ │ └── custom.css
│ └── tutorials
│ ├── development-setup.md
│ ├── environment-setup.md
│ ├── first-deployment.md
│ ├── getting-started.md
│ ├── index.md
│ ├── memory-workflows.md
│ └── user-onboarding.md
├── jest.config.js
├── LICENSE
├── Makefile
├── MCP_PHASE2_IMPLEMENTATION.md
├── mcp-config-example.json
├── mcp.json
├── package-lock.json
├── package.json
├── README.md
├── release.sh
├── scripts
│ └── check-package-structure.cjs
├── SECURITY.md
├── setup-precommit.sh
├── src
│ ├── benchmarks
│ │ └── performance.ts
│ ├── index.ts
│ ├── memory
│ │ ├── contextual-retrieval.ts
│ │ ├── deployment-analytics.ts
│ │ ├── enhanced-manager.ts
│ │ ├── export-import.ts
│ │ ├── freshness-kg-integration.ts
│ │ ├── index.ts
│ │ ├── integration.ts
│ │ ├── kg-code-integration.ts
│ │ ├── kg-health.ts
│ │ ├── kg-integration.ts
│ │ ├── kg-link-validator.ts
│ │ ├── kg-storage.ts
│ │ ├── knowledge-graph.ts
│ │ ├── learning.ts
│ │ ├── manager.ts
│ │ ├── multi-agent-sharing.ts
│ │ ├── pruning.ts
│ │ ├── schemas.ts
│ │ ├── storage.ts
│ │ ├── temporal-analysis.ts
│ │ ├── user-preferences.ts
│ │ └── visualization.ts
│ ├── prompts
│ │ └── technical-writer-prompts.ts
│ ├── scripts
│ │ └── benchmark.ts
│ ├── templates
│ │ └── playwright
│ │ ├── accessibility.spec.template.ts
│ │ ├── Dockerfile.template
│ │ ├── docs-e2e.workflow.template.yml
│ │ ├── link-validation.spec.template.ts
│ │ └── playwright.config.template.ts
│ ├── tools
│ │ ├── analyze-deployments.ts
│ │ ├── analyze-readme.ts
│ │ ├── analyze-repository.ts
│ │ ├── check-documentation-links.ts
│ │ ├── deploy-pages.ts
│ │ ├── detect-gaps.ts
│ │ ├── evaluate-readme-health.ts
│ │ ├── generate-config.ts
│ │ ├── generate-contextual-content.ts
│ │ ├── generate-llm-context.ts
│ │ ├── generate-readme-template.ts
│ │ ├── generate-technical-writer-prompts.ts
│ │ ├── kg-health-check.ts
│ │ ├── manage-preferences.ts
│ │ ├── manage-sitemap.ts
│ │ ├── optimize-readme.ts
│ │ ├── populate-content.ts
│ │ ├── readme-best-practices.ts
│ │ ├── recommend-ssg.ts
│ │ ├── setup-playwright-tests.ts
│ │ ├── setup-structure.ts
│ │ ├── sync-code-to-docs.ts
│ │ ├── test-local-deployment.ts
│ │ ├── track-documentation-freshness.ts
│ │ ├── update-existing-documentation.ts
│ │ ├── validate-content.ts
│ │ ├── validate-documentation-freshness.ts
│ │ ├── validate-readme-checklist.ts
│ │ └── verify-deployment.ts
│ ├── types
│ │ └── api.ts
│ ├── utils
│ │ ├── ast-analyzer.ts
│ │ ├── code-scanner.ts
│ │ ├── content-extractor.ts
│ │ ├── drift-detector.ts
│ │ ├── freshness-tracker.ts
│ │ ├── language-parsers-simple.ts
│ │ ├── permission-checker.ts
│ │ └── sitemap-generator.ts
│ └── workflows
│ └── documentation-workflow.ts
├── test-docs-local.sh
├── tests
│ ├── api
│ │ └── mcp-responses.test.ts
│ ├── benchmarks
│ │ └── performance.test.ts
│ ├── edge-cases
│ │ └── error-handling.test.ts
│ ├── functional
│ │ └── tools.test.ts
│ ├── integration
│ │ ├── kg-documentation-workflow.test.ts
│ │ ├── knowledge-graph-workflow.test.ts
│ │ ├── mcp-readme-tools.test.ts
│ │ ├── memory-mcp-tools.test.ts
│ │ ├── readme-technical-writer.test.ts
│ │ └── workflow.test.ts
│ ├── memory
│ │ ├── contextual-retrieval.test.ts
│ │ ├── enhanced-manager.test.ts
│ │ ├── export-import.test.ts
│ │ ├── freshness-kg-integration.test.ts
│ │ ├── kg-code-integration.test.ts
│ │ ├── kg-health.test.ts
│ │ ├── kg-link-validator.test.ts
│ │ ├── kg-storage-validation.test.ts
│ │ ├── kg-storage.test.ts
│ │ ├── knowledge-graph-enhanced.test.ts
│ │ ├── knowledge-graph.test.ts
│ │ ├── learning.test.ts
│ │ ├── manager-advanced.test.ts
│ │ ├── manager.test.ts
│ │ ├── mcp-resource-integration.test.ts
│ │ ├── mcp-tool-persistence.test.ts
│ │ ├── schemas.test.ts
│ │ ├── storage.test.ts
│ │ ├── temporal-analysis.test.ts
│ │ └── user-preferences.test.ts
│ ├── performance
│ │ ├── memory-load-testing.test.ts
│ │ └── memory-stress-testing.test.ts
│ ├── prompts
│ │ ├── guided-workflow-prompts.test.ts
│ │ └── technical-writer-prompts.test.ts
│ ├── server.test.ts
│ ├── setup.ts
│ ├── tools
│ │ ├── all-tools.test.ts
│ │ ├── analyze-coverage.test.ts
│ │ ├── analyze-deployments.test.ts
│ │ ├── analyze-readme.test.ts
│ │ ├── analyze-repository.test.ts
│ │ ├── check-documentation-links.test.ts
│ │ ├── deploy-pages-kg-retrieval.test.ts
│ │ ├── deploy-pages-tracking.test.ts
│ │ ├── deploy-pages.test.ts
│ │ ├── detect-gaps.test.ts
│ │ ├── evaluate-readme-health.test.ts
│ │ ├── generate-contextual-content.test.ts
│ │ ├── generate-llm-context.test.ts
│ │ ├── generate-readme-template.test.ts
│ │ ├── generate-technical-writer-prompts.test.ts
│ │ ├── kg-health-check.test.ts
│ │ ├── manage-sitemap.test.ts
│ │ ├── optimize-readme.test.ts
│ │ ├── readme-best-practices.test.ts
│ │ ├── recommend-ssg-historical.test.ts
│ │ ├── recommend-ssg-preferences.test.ts
│ │ ├── recommend-ssg.test.ts
│ │ ├── simple-coverage.test.ts
│ │ ├── sync-code-to-docs.test.ts
│ │ ├── test-local-deployment.test.ts
│ │ ├── tool-error-handling.test.ts
│ │ ├── track-documentation-freshness.test.ts
│ │ ├── validate-content.test.ts
│ │ ├── validate-documentation-freshness.test.ts
│ │ └── validate-readme-checklist.test.ts
│ ├── types
│ │ └── type-safety.test.ts
│ └── utils
│ ├── ast-analyzer.test.ts
│ ├── content-extractor.test.ts
│ ├── drift-detector.test.ts
│ ├── freshness-tracker.test.ts
│ └── sitemap-generator.test.ts
├── tsconfig.json
└── typedoc.json
```
# Files
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: CI
2 |
3 | on:
4 | push:
5 | branches: [main, develop]
6 | pull_request:
7 | branches: [main]
8 |
9 | jobs:
10 | test:
11 | name: Test Suite
12 | runs-on: ubuntu-latest
13 |
14 | strategy:
15 | matrix:
16 | node-version: [20.x, 22.x]
17 |
18 | steps:
19 | - name: Checkout code
20 | uses: actions/checkout@v4
21 |
22 | - name: Setup Node.js ${{ matrix.node-version }}
23 | uses: actions/setup-node@v4
24 | with:
25 | node-version: ${{ matrix.node-version }}
26 | cache: "npm"
27 |
28 | - name: Install dependencies
29 | run: npm ci
30 |
31 | - name: Clean up any existing memory files
32 | run: rm -rf .documcp
33 |
34 | - name: Type check
35 | run: npm run typecheck
36 |
37 | - name: Lint code
38 | run: npm run lint
39 |
40 | - name: Run tests
41 | run: npm test -- --forceExit
42 |
43 | - name: Clean up memory files before coverage run
44 | run: rm -rf .documcp
45 |
46 | - name: Run tests with coverage
47 | run: npm test -- --coverage --forceExit
48 |
49 | - name: Upload coverage to Codecov
50 | uses: codecov/codecov-action@v3
51 | with:
52 | file: ./coverage/lcov.info
53 | flags: unittests
54 | name: codecov-umbrella
55 |
56 | - name: Performance benchmarks
57 | run: npm run test:performance
58 |
59 | build:
60 | name: Build Verification
61 | runs-on: ubuntu-latest
62 | needs: test
63 |
64 | steps:
65 | - name: Checkout code
66 | uses: actions/checkout@v4
67 |
68 | - name: Setup Node.js
69 | uses: actions/setup-node@v4
70 | with:
71 | node-version: "20.x"
72 | cache: "npm"
73 |
74 | - name: Install dependencies
75 | run: npm ci
76 |
77 | - name: Clean up any existing memory files
78 | run: rm -rf .documcp
79 |
80 | - name: Build project
81 | run: npm run build
82 |
83 | - name: Verify build output
84 | run: |
85 | test -f dist/index.js
86 | test -f dist/index.d.ts
87 |
88 | - name: Package verification
89 | run: npm pack --dry-run
90 |
91 | security:
92 | name: Security Audit
93 | runs-on: ubuntu-latest
94 |
95 | steps:
96 | - name: Checkout code
97 | uses: actions/checkout@v4
98 |
99 | - name: Setup Node.js
100 | uses: actions/setup-node@v4
101 | with:
102 | node-version: "20.x"
103 | cache: "npm"
104 |
105 | - name: Install dependencies
106 | run: npm ci
107 |
108 | - name: Run security audit (dev dependencies)
109 | run: npm audit --audit-level=moderate || echo "⚠️ Some dev dependency vulnerabilities found - see Security tab for details"
110 | continue-on-error: true
111 |
112 | - name: Check for high severity vulnerabilities (production)
113 | run: npm audit --audit-level=high --production
114 |
115 | commitlint:
116 | name: Commit Message Validation
117 | runs-on: ubuntu-latest
118 | if: github.event_name == 'pull_request'
119 |
120 | steps:
121 | - name: Checkout code
122 | uses: actions/checkout@v4
123 | with:
124 | fetch-depth: 0
125 |
126 | - name: Setup Node.js
127 | uses: actions/setup-node@v4
128 | with:
129 | node-version: "20.x"
130 | cache: "npm"
131 |
132 | - name: Install dependencies
133 | run: npm ci
134 |
135 | - name: Validate commit messages
136 | run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
137 |
```
--------------------------------------------------------------------------------
/.github/agents/documcp-tool.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: documcp-tool
3 | description: Build or modify MCP tools following DocuMCP's architecture
4 | tools: ["read", "list", "usages", "problems", "changes"]
5 | ---
6 |
7 | You are an expert at building MCP tools for DocuMCP following established patterns.
8 |
9 | ## Tool Implementation Pattern
10 |
11 | Every DocuMCP tool MUST follow this structure:
12 |
13 | 1. **Import required modules**:
14 |
15 | ```typescript
16 | import { z } from "zod";
17 | import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
18 | import { promises as fs } from "fs";
19 | import path from "path";
20 | ```
21 |
22 | 2. **Define Zod input schema**:
23 |
24 | ```typescript
25 | const inputSchema = z.object({
26 | // Define all parameters with types and constraints
27 | path: z.string().describe("Description for parameter"),
28 | depth: z.enum(["quick", "standard", "deep"]).optional().default("standard"),
29 | });
30 | ```
31 |
32 | 3. **Implement tool function**:
33 |
34 | ```typescript
35 | export async function myTool(args: unknown): Promise<MCPToolResponse> {
36 | const startTime = Date.now();
37 |
38 | try {
39 | // 1. Validate input
40 | const input = inputSchema.parse(args);
41 |
42 | // 2. Business logic here
43 | const result = await performAnalysis(input);
44 |
45 | // 3. Return formatted response
46 | return formatMCPResponse({
47 | success: true,
48 | data: result,
49 | metadata: {
50 | toolVersion: "1.0.0",
51 | executionTime: Date.now() - startTime,
52 | timestamp: new Date().toISOString(),
53 | },
54 | recommendations: [
55 | {
56 | type: "info",
57 | title: "Next Steps",
58 | description: "Consider running X tool next",
59 | },
60 | ],
61 | });
62 | } catch (error) {
63 | return formatMCPResponse({
64 | success: false,
65 | error: {
66 | code: "TOOL_ERROR",
67 | message: error instanceof Error ? error.message : "Unknown error",
68 | resolution: "Check inputs and try again",
69 | },
70 | metadata: {
71 | toolVersion: "1.0.0",
72 | executionTime: Date.now() - startTime,
73 | timestamp: new Date().toISOString(),
74 | },
75 | });
76 | }
77 | }
78 | ```
79 |
80 | 4. **Integration steps**:
81 | - Add tool to `src/index.ts` TOOLS array
82 | - Add handler in CallToolRequestSchema switch
83 | - Create tests in `tests/tools/`
84 | - Run `npm run ci` to validate
85 |
86 | ## Critical Requirements
87 |
88 | - ALL imports use `.js` extensions (even for `.ts` files)
89 | - Use `fs.promises` API, never sync methods
90 | - Path operations use `isPathAllowed()` from `src/utils/permission-checker.ts`
91 | - All responses use `formatMCPResponse()`
92 | - Git operations use `simple-git` library
93 |
94 | ## Testing Pattern
95 |
96 | ```typescript
97 | import { myTool } from "../../src/tools/my-tool.js";
98 |
99 | describe("myTool", () => {
100 | it("should return success response", async () => {
101 | const result = await myTool({ path: "./test" });
102 |
103 | expect(result.success).toBe(true);
104 | expect(result.data).toBeDefined();
105 | expect(result.metadata.toolVersion).toBe("1.0.0");
106 | });
107 |
108 | it("should handle errors gracefully", async () => {
109 | const result = await myTool({ invalidParam: "value" });
110 |
111 | expect(result.success).toBe(false);
112 | expect(result.error).toBeDefined();
113 | });
114 | });
115 | ```
116 |
117 | When working:
118 |
119 | 1. Read similar tools in `src/tools/` for patterns
120 | 2. Check `src/types/api.ts` for response types
121 | 3. Review ADR-006 for tool API design principles
122 | 4. Ensure 80% test coverage (60% for complex logic)
123 |
```
--------------------------------------------------------------------------------
/release.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | set -e
3 |
4 | # Colors for output
5 | RED='\033[0;31m'
6 | GREEN='\033[0;32m'
7 | YELLOW='\033[1;33m'
8 | NC='\033[0m' # No Color
9 |
10 | # Function to print colored output
11 | print_status() {
12 | echo -e "${GREEN}[RELEASE]${NC} $1"
13 | }
14 |
15 | print_warning() {
16 | echo -e "${YELLOW}[WARNING]${NC} $1"
17 | }
18 |
19 | print_error() {
20 | echo -e "${RED}[ERROR]${NC} $1"
21 | }
22 |
23 | # Check if we're on main branch
24 | current_branch=$(git branch --show-current)
25 | if [ "$current_branch" != "main" ]; then
26 | print_error "Must be on main branch to release. Current branch: $current_branch"
27 | exit 1
28 | fi
29 |
30 | # Check if working directory is clean
31 | if [ -n "$(git status --porcelain)" ]; then
32 | print_error "Working directory is not clean. Please commit or stash changes first."
33 | git status
34 | exit 1
35 | fi
36 |
37 | # Get version type
38 | VERSION_TYPE=${1:-patch}
39 | if [[ ! "$VERSION_TYPE" =~ ^(major|minor|patch)$ ]]; then
40 | print_error "Invalid version type: $VERSION_TYPE"
41 | echo "Usage: $0 [major|minor|patch]"
42 | exit 1
43 | fi
44 |
45 | print_status "Starting release process with version bump: $VERSION_TYPE"
46 |
47 | # Get current version
48 | CURRENT_VERSION=$(node -p "require('./package.json').version")
49 | print_status "Current version: $CURRENT_VERSION"
50 |
51 | # Calculate new version
52 | IFS='.' read -r -a version_parts <<< "$CURRENT_VERSION"
53 | major=${version_parts[0]}
54 | minor=${version_parts[1]}
55 | patch=${version_parts[2]}
56 |
57 | case $VERSION_TYPE in
58 | major)
59 | major=$((major + 1))
60 | minor=0
61 | patch=0
62 | ;;
63 | minor)
64 | minor=$((minor + 1))
65 | patch=0
66 | ;;
67 | patch)
68 | patch=$((patch + 1))
69 | ;;
70 | esac
71 |
72 | NEW_VERSION="$major.$minor.$patch"
73 | TAG_NAME="v$NEW_VERSION"
74 |
75 | print_status "New version will be: $NEW_VERSION"
76 | print_status "Tag will be: $TAG_NAME"
77 |
78 | # Confirm release
79 | echo
80 | read -p "Continue with release? (y/N): " confirm
81 | if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
82 | print_status "Release cancelled"
83 | exit 0
84 | fi
85 |
86 | print_status "Updating package.json version..."
87 | # Update package.json version
88 | npm version $VERSION_TYPE --no-git-tag-version
89 |
90 | print_status "Running pre-release checks..."
91 | # Run tests and linting
92 | npm run ci
93 |
94 | print_status "Creating git commit..."
95 | # Commit the version change
96 | git add package.json package-lock.json
97 | git commit -m "chore(release): bump version to $NEW_VERSION
98 |
99 | 🤖 Generated with [Claude Code](https://claude.ai/code)
100 |
101 | Authored-By: TOSIN AKINOSHO <[email protected]>
102 | Co-Authored-By: Claude <[email protected]>"
103 |
104 | print_status "Creating git tag: $TAG_NAME"
105 | # Create annotated tag
106 | git tag -a "$TAG_NAME" -m "Release $NEW_VERSION
107 |
108 | DocuMCP v$NEW_VERSION - Intelligent MCP server for documentation deployment
109 |
110 | Features:
111 | - Repository analysis and SSG recommendations
112 | - Automated GitHub Pages deployment workflows
113 | - Diataxis framework integration
114 | - Enhanced TODO management system
115 |
116 | 🤖 Generated with [Claude Code](https://claude.ai/code)
117 |
118 | Authored-By: TOSIN AKINOSHO <[email protected]>
119 | Co-Authored-By: Claude <[email protected]>"
120 |
121 | print_status "Pushing changes and tag to origin..."
122 | # Push commit and tag
123 | git push origin main
124 | git push origin "$TAG_NAME"
125 |
126 | print_status "Release complete! 🎉"
127 | print_status "Tag $TAG_NAME has been pushed and will trigger the release workflow"
128 | print_status "Check GitHub Actions for release progress: https://github.com/tosin2013/documcp/actions"
129 |
```
--------------------------------------------------------------------------------
/docs/research/domain-3-ssg-recommendation/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.966Z"
4 | last_validated: "2025-11-20T00:46:21.966Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Domain 3: SSG Recommendation Research
10 |
11 | This directory contains research and analysis related to DocuMCP's static site generator recommendation engine.
12 |
13 | ## Research Overview
14 |
15 | ### Recommendation Engine
16 |
17 | - **SSG Analysis**: Comprehensive analysis of static site generators
18 | - **Recommendation Algorithms**: Multi-criteria decision analysis algorithms
19 | - **Performance Metrics**: SSG performance characteristics and benchmarks
20 | - **User Preference Learning**: Adaptive recommendation based on user patterns
21 |
22 | ### Key Research Areas
23 |
24 | - **SSG Profiling**: Detailed profiles of supported SSGs (Jekyll, Hugo, Docusaurus, MkDocs, Eleventy)
25 | - **Recommendation Accuracy**: Validation of recommendation quality
26 | - **Performance Analysis**: SSG performance under various conditions
27 | - **User Satisfaction**: Measuring user satisfaction with recommendations
28 |
29 | ## Research Files
30 |
31 | - `ssg-performance-analysis.md`: Comprehensive SSG performance analysis
32 | - `recommendation-algorithms.md`: Recommendation algorithm research
33 | - `user-satisfaction-study.md`: User satisfaction and recommendation accuracy
34 | - `ssg-comparison.md`: Detailed comparison of SSG capabilities
35 |
36 | ## Key Findings
37 |
38 | ### Recommendation Accuracy
39 |
40 | - Overall recommendation accuracy: 92%
41 | - User satisfaction with recommendations: 89%
42 | - SSG performance prediction accuracy: 95%
43 | - Project type detection accuracy: 98%
44 |
45 | ### Performance Metrics
46 |
47 | - Recommendation generation time: < 200ms
48 | - SSG build time prediction accuracy: 90%
49 | - Memory usage optimization: 85% reduction for large sites
50 | - Deployment success rate: 97%
51 |
52 | ### User Experience
53 |
54 | - Time to first deployment: Reduced by 70%
55 | - Documentation quality improvement: 85%
56 | - User learning curve reduction: 60%
57 | - Maintenance effort reduction: 50%
58 |
59 | ## SSG Analysis Results
60 |
61 | ### Performance Rankings
62 |
63 | 1. **Hugo**: Fastest build times, excellent for large sites
64 | 2. **Docusaurus**: Best for documentation, React-based projects
65 | 3. **Jekyll**: Excellent GitHub integration, good for blogs
66 | 4. **Eleventy**: Flexible, good for custom requirements
67 | 5. **MkDocs**: Simple, good for Python projects
68 |
69 | ### Use Case Recommendations
70 |
71 | - **Large Sites (>1000 pages)**: Hugo or Docusaurus
72 | - **Documentation Focus**: Docusaurus or MkDocs
73 | - **Blog Focus**: Jekyll or Hugo
74 | - **Custom Requirements**: Eleventy
75 | - **Python Projects**: MkDocs
76 |
77 | ## Future Research
78 |
79 | ### Planned Studies
80 |
81 | - Machine learning integration for improved recommendations
82 | - Real-time SSG performance monitoring
83 | - Advanced user preference learning
84 | - Integration with emerging SSG technologies
85 |
86 | ### Research Questions
87 |
88 | - How can we further improve recommendation accuracy?
89 | - What are the best strategies for handling new SSG releases?
90 | - How can we better predict SSG performance for specific use cases?
91 | - What metrics best predict user satisfaction with SSG choices?
92 |
93 | ## Related Research
94 |
95 | - [Domain 2: Repository Analysis Research](../domain-2-repository-analysis/README.md)
96 | - [Domain 4: Diataxis Integration Research](../domain-4-diataxis-integration/README.md)
97 | - [Cross-Domain Integration Research](../cross-domain-integration/README.md)
98 | - [SSG Performance Analysis](./ssg-performance-analysis.md)
99 |
```
--------------------------------------------------------------------------------
/.github/agents/documcp-ast.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: documcp-ast
3 | description: Work with AST-based code analysis and drift detection (Phase 3)
4 | tools: ["read", "list", "search", "usages"]
5 | ---
6 |
7 | You are an expert at DocuMCP's AST-based code analysis system (Phase 3).
8 |
9 | ## AST Analysis System
10 |
11 | ### Multi-Language Parser (`src/utils/ast-analyzer.ts`)
12 |
13 | Supports: TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, Bash
14 |
15 | **Key Features**:
16 |
17 | - Function signature extraction with parameters, return types
18 | - Class analysis with methods, properties, inheritance
19 | - Interface and type alias extraction
20 | - Cyclomatic complexity calculation
21 | - Semantic code comparison (not text diffs)
22 |
23 | ### Usage Pattern
24 |
25 | ```typescript
26 | import { analyzeCodeFile } from "../utils/ast-analyzer.js";
27 |
28 | const analysis = await analyzeCodeFile("/path/to/file.ts", "typescript");
29 |
30 | analysis.functions.forEach((fn) => {
31 | console.log(`${fn.name}(${fn.parameters.join(", ")}): ${fn.returnType}`);
32 | console.log(`Complexity: ${fn.complexity}`);
33 | });
34 | ```
35 |
36 | ## Drift Detection System (`src/utils/drift-detector.ts`)
37 |
38 | Automated detection of documentation-code misalignment.
39 |
40 | ### Drift Types
41 |
42 | - **Outdated**: Documentation references old API signatures
43 | - **Incorrect**: Documented features no longer exist
44 | - **Missing**: New code features lack documentation
45 | - **Breaking**: API changes invalidate existing docs
46 |
47 | ### Severity Levels
48 |
49 | - **breaking**: Major API changes requiring doc rewrites
50 | - **major**: Significant changes needing updates
51 | - **minor**: Small changes, low impact
52 | - **patch**: Trivial changes
53 |
54 | ### Detection Pattern
55 |
56 | ```typescript
57 | import { detectDrift } from "../utils/drift-detector.js";
58 |
59 | const drift = await detectDrift({
60 | projectPath: "/path/to/project",
61 | docsPath: "/path/to/docs",
62 | snapshotDir: ".documcp/snapshots",
63 | });
64 |
65 | drift.affectedFiles.forEach((file) => {
66 | console.log(`${file.path}: ${file.driftType} (${file.severity})`);
67 | file.changes.forEach((change) => {
68 | console.log(` - ${change.type}: ${change.description}`);
69 | });
70 | });
71 | ```
72 |
73 | ## Code-to-Docs Sync Tool
74 |
75 | ### Modes
76 |
77 | - **detect**: Analyze drift without changes
78 | - **preview**: Show proposed changes
79 | - **apply**: Apply high-confidence changes (threshold: 0.8)
80 | - **auto**: Apply all changes (use caution)
81 |
82 | ### Usage
83 |
84 | ```typescript
85 | import { handleSyncCodeToDocs } from "./tools/sync-code-to-docs.js";
86 |
87 | // Detect drift
88 | const result = await handleSyncCodeToDocs({
89 | projectPath: "/path/to/project",
90 | docsPath: "/path/to/docs",
91 | mode: "detect",
92 | });
93 |
94 | // Apply safe changes
95 | const applied = await handleSyncCodeToDocs({
96 | projectPath: "/path/to/project",
97 | docsPath: "/path/to/docs",
98 | mode: "apply",
99 | autoApplyThreshold: 0.8,
100 | createSnapshot: true,
101 | });
102 | ```
103 |
104 | ## Context-Aware Content Generation
105 |
106 | ### Generate Diataxis-Compliant Docs
107 |
108 | ```typescript
109 | import { handleGenerateContextualContent } from "./tools/generate-contextual-content.js";
110 |
111 | const docs = await handleGenerateContextualContent({
112 | filePath: "./src/api.ts",
113 | documentationType: "reference",
114 | includeExamples: true,
115 | style: "detailed",
116 | outputFormat: "markdown",
117 | });
118 | ```
119 |
120 | When working with AST:
121 |
122 | 1. Check `src/utils/ast-analyzer.ts` for parser capabilities
123 | 2. Review `src/utils/drift-detector.ts` for drift algorithms
124 | 3. Test snapshot management in `.documcp/snapshots/`
125 | 4. Ensure Tree-sitter parsers are available for target languages
126 |
```
--------------------------------------------------------------------------------
/tests/types/type-safety.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | import {
2 | HealthAnalysis,
3 | ChecklistItem,
4 | BestPracticesReport,
5 | convertBestPracticesReportToChecklistItems,
6 | generateHealthRecommendations,
7 | } from "../../src/types/api";
8 |
9 | describe("Type Safety Tests", () => {
10 | describe("HealthAnalysis", () => {
11 | it("should create valid HealthAnalysis object", () => {
12 | const healthAnalysis: HealthAnalysis = {
13 | score: 85,
14 | issues: [
15 | {
16 | type: "warning",
17 | message: "Missing section",
18 | section: "introduction",
19 | line: 10,
20 | },
21 | ],
22 | recommendations: ["Add introduction section"],
23 | metadata: {
24 | checkDate: "2023-01-01",
25 | version: "1.0.0",
26 | },
27 | };
28 |
29 | expect(healthAnalysis.score).toBe(85);
30 | expect(healthAnalysis.issues).toHaveLength(1);
31 | expect(healthAnalysis.recommendations).toContain(
32 | "Add introduction section",
33 | );
34 | });
35 | });
36 |
37 | describe("BestPracticesReport and ChecklistItem", () => {
38 | it("should create valid BestPracticesReport with ChecklistItems", () => {
39 | const checklistItems: ChecklistItem[] = [
40 | {
41 | id: "readme-title",
42 | title: "Has clear title",
43 | description: "README has a clear, descriptive title",
44 | completed: true,
45 | required: true,
46 | category: "structure",
47 | },
48 | {
49 | id: "readme-description",
50 | title: "Has description",
51 | description: "README includes project description",
52 | completed: false,
53 | required: true,
54 | category: "content",
55 | },
56 | ];
57 |
58 | const report: BestPracticesReport = {
59 | items: checklistItems,
60 | score: 50,
61 | categories: {
62 | structure: { total: 1, completed: 1, score: 100 },
63 | content: { total: 1, completed: 0, score: 0 },
64 | },
65 | recommendations: ["Add project description"],
66 | };
67 |
68 | expect(report.items).toHaveLength(2);
69 | expect(report.score).toBe(50);
70 | expect(report.categories.structure.score).toBe(100);
71 | });
72 |
73 | it("should convert BestPracticesReport to ChecklistItem array", () => {
74 | const report: BestPracticesReport = {
75 | items: [
76 | {
77 | id: "test-item",
78 | title: "Test Item",
79 | description: "Test description",
80 | completed: true,
81 | required: true,
82 | category: "test",
83 | },
84 | ],
85 | score: 100,
86 | categories: { test: { total: 1, completed: 1, score: 100 } },
87 | recommendations: [],
88 | };
89 |
90 | const items = convertBestPracticesReportToChecklistItems(report);
91 | expect(items).toHaveLength(1);
92 | expect(items[0].id).toBe("test-item");
93 | });
94 | });
95 |
96 | describe("Utility Functions", () => {
97 | it("should generate health recommendations from analysis", () => {
98 | const analysis: HealthAnalysis = {
99 | score: 75,
100 | issues: [],
101 | recommendations: ["Add more examples", "Improve documentation"],
102 | metadata: {
103 | checkDate: "2023-01-01",
104 | version: "1.0.0",
105 | },
106 | };
107 |
108 | const recommendations = generateHealthRecommendations(analysis);
109 | expect(recommendations).toEqual([
110 | "Add more examples",
111 | "Improve documentation",
112 | ]);
113 | });
114 | });
115 | });
116 |
```
--------------------------------------------------------------------------------
/docs/tutorials/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.972Z"
4 | last_validated: "2025-11-20T00:46:21.972Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Tutorials
10 |
11 | Step-by-step tutorials to get you started with DocuMCP and master advanced features.
12 |
13 | ## Getting Started
14 |
15 | ### Beginner Tutorials
16 |
17 | - [Getting Started with DocuMCP](getting-started.md) - Your first documentation deployment
18 | - [First Documentation Deployment](first-deployment.md) - Complete deployment workflow
19 | - [Development Setup](development-setup.md) - Set up your development environment
20 |
21 | ### Advanced Tutorials
22 |
23 | - [Memory Workflows](memory-workflows.md) - Advanced memory system features
24 |
25 | ## Learning Path
26 |
27 | ### For New Users
28 |
29 | 1. **Start Here**: [Getting Started with DocuMCP](getting-started.md)
30 | 2. **First Deployment**: [First Documentation Deployment](first-deployment.md)
31 | 3. **Development Setup**: [Development Setup](development-setup.md)
32 |
33 | ### For Advanced Users
34 |
35 | 1. **Memory System**: [Memory Workflows](memory-workflows.md)
36 | 2. **Custom Configuration**: See [Reference Documentation](../reference/)
37 | 3. **Advanced Features**: See [How-to Guides](../how-to/)
38 |
39 | ## Quick Start
40 |
41 | If you're new to DocuMCP, start with this simple workflow:
42 |
43 | ```bash
44 | # Analyze your repository
45 | "analyze my repository and recommend a static site generator"
46 |
47 | # Generate documentation
48 | "generate documentation structure for my project"
49 |
50 | # Deploy to GitHub Pages
51 | "deploy my documentation to GitHub Pages"
52 | ```
53 |
54 | ## What You'll Learn
55 |
56 | ### Core Concepts
57 |
58 | - **Repository Analysis**: How DocuMCP analyzes your project
59 | - **SSG Recommendations**: Choosing the right static site generator
60 | - **Documentation Generation**: Creating comprehensive documentation
61 | - **Deployment Automation**: Automated deployment workflows
62 |
63 | ### Advanced Features
64 |
65 | - **Memory System**: Learning from your documentation patterns
66 | - **Custom Configuration**: Tailoring DocuMCP to your needs
67 | - **Performance Optimization**: Optimizing your documentation site
68 | - **Analytics Integration**: Tracking documentation usage
69 |
70 | ## Prerequisites
71 |
72 | ### Basic Requirements
73 |
74 | - **Git Repository**: Your project in a Git repository
75 | - **GitHub Account**: For deployment to GitHub Pages
76 | - **Node.js**: Version 20.0.0 or higher (for local development)
77 |
78 | ### Recommended Knowledge
79 |
80 | - **Markdown**: Basic Markdown syntax
81 | - **Git**: Basic Git operations
82 | - **GitHub**: GitHub repository management
83 |
84 | ## Getting Help
85 |
86 | ### If You Get Stuck
87 |
88 | 1. **Check the Tutorials**: Review the relevant tutorial section
89 | 2. **How-to Guides**: See [How-to Guides](../how-to/) for specific tasks
90 | 3. **Reference Documentation**: Check [Reference](../reference/) for technical details
91 | 4. **Community Support**: Ask questions in [GitHub Issues](https://github.com/tosin2013/documcp/issues)
92 |
93 | ### Common Issues
94 |
95 | - **Repository Analysis Issues**: See [Troubleshooting Guide](../how-to/troubleshooting.md)
96 | - **Deployment Problems**: Check [GitHub Pages Deployment Guide](../how-to/github-pages-deployment.md)
97 | - **Local Testing**: See [Local Testing Guide](../how-to/local-testing.md)
98 |
99 | ## Next Steps
100 |
101 | After completing the tutorials:
102 |
103 | 1. **Explore How-to Guides**: [How-to Guides](../how-to/) for specific tasks
104 | 2. **Reference Documentation**: [Reference](../reference/) for technical details
105 | 3. **Architecture Understanding**: [Architecture Documentation](../explanation/)
106 | 4. **Community**: Join [GitHub Issues](https://github.com/tosin2013/documcp/issues) for support and feature requests
107 |
```
--------------------------------------------------------------------------------
/.github/agents/documcp-test.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: documcp-test
3 | description: Write tests for DocuMCP following established patterns
4 | tools: ["read", "list", "usages", "problems"]
5 | ---
6 |
7 | You are an expert at writing tests for DocuMCP.
8 |
9 | ## Testing Strategy
10 |
11 | ### Coverage Requirements
12 |
13 | - **Global**: 80% (branches, functions, lines, statements)
14 | - **Complex tools** (e.g., `recommend-ssg.ts`): 60%
15 | - **Excluded**: Experimental memory features, `src/index.ts`
16 |
17 | ### Test Structure
18 |
19 | ```
20 | tests/
21 | ├── tools/ # Individual tool testing
22 | ├── integration/ # Multi-tool workflows
23 | ├── memory/ # Memory system testing
24 | ├── api/ # MCP protocol validation
25 | ├── functional/ # End-to-end functional tests
26 | ├── benchmarks/ # Performance benchmarks
27 | └── edge-cases/ # Error handling and edge cases
28 | ```
29 |
30 | ## Tool Test Pattern
31 |
32 | ```typescript
33 | import { myTool } from "../../src/tools/my-tool.js";
34 | import { formatMCPResponse } from "../../src/types/api.js";
35 | import { promises as fs } from "fs";
36 | import path from "path";
37 | import { tmpdir } from "os";
38 |
39 | describe("myTool", () => {
40 | let testDir: string;
41 |
42 | beforeEach(async () => {
43 | testDir = path.join(tmpdir(), `test-${Date.now()}`);
44 | await fs.mkdir(testDir, { recursive: true });
45 | });
46 |
47 | afterEach(async () => {
48 | await fs.rm(testDir, { recursive: true, force: true });
49 | });
50 |
51 | it("should return success for valid input", async () => {
52 | const result = await myTool({
53 | path: testDir,
54 | depth: "standard",
55 | });
56 |
57 | expect(result.success).toBe(true);
58 | expect(result.data).toBeDefined();
59 | expect(result.metadata.toolVersion).toBeDefined();
60 | expect(result.metadata.executionTime).toBeGreaterThan(0);
61 | });
62 |
63 | it("should handle invalid input", async () => {
64 | const result = await myTool({
65 | invalidParam: "value",
66 | });
67 |
68 | expect(result.success).toBe(false);
69 | expect(result.error).toBeDefined();
70 | expect(result.error.code).toBe("TOOL_ERROR");
71 | });
72 |
73 | it("should validate path permissions", async () => {
74 | const result = await myTool({
75 | path: "/etc/passwd",
76 | });
77 |
78 | expect(result.success).toBe(false);
79 | expect(result.error.message).toContain("permission");
80 | });
81 | });
82 | ```
83 |
84 | ## Integration Test Pattern
85 |
86 | ```typescript
87 | describe("Documentation Workflow", () => {
88 | it("should complete full workflow", async () => {
89 | // 1. Analyze
90 | const analysis = await analyzeRepository({ path: testDir });
91 | expect(analysis.success).toBe(true);
92 |
93 | // 2. Recommend
94 | const recommendation = await recommendSSG({
95 | analysisId: analysis.data.id,
96 | });
97 | expect(recommendation.success).toBe(true);
98 |
99 | // 3. Generate config
100 | const config = await generateConfig({
101 | ssg: recommendation.data.recommended,
102 | projectName: "Test",
103 | outputPath: testDir,
104 | });
105 | expect(config.success).toBe(true);
106 | });
107 | });
108 | ```
109 |
110 | ## Running Tests
111 |
112 | ```bash
113 | # All tests
114 | npm test
115 |
116 | # Specific file
117 | npm test -- tests/tools/analyze-repository.test.ts
118 |
119 | # Watch mode
120 | npm test -- --watch
121 |
122 | # Coverage
123 | npm run test:coverage
124 |
125 | # Performance benchmarks only
126 | npm run test:performance
127 | ```
128 |
129 | ## MCP Inspector Testing
130 |
131 | ```bash
132 | # Launch inspector
133 | npm run build:inspect
134 |
135 | # Opens browser at http://localhost:5173
136 | # Test tools interactively without full integration
137 | ```
138 |
139 | When testing:
140 |
141 | 1. Use `formatMCPResponse()` for response validation
142 | 2. Mock file system with `tmp` package
143 | 3. Test both success and error paths
144 | 4. Verify metadata fields (toolVersion, executionTime, timestamp)
145 | 5. Run `npm run ci` before committing
146 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/npm-publishing-fix.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: "🚀 Fix npm Package Publishing"
3 | description: "Verify and fix npm package publishing configuration in release workflow"
4 | labels: ["bug", "release", "npm", "high-priority"]
5 | assignees:
6 | - "tosinakinosho"
7 | ---
8 |
9 | ## 🚨 Problem Description
10 |
11 | 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.
12 |
13 | **Current Behavior:**
14 |
15 | - Release workflow includes npm publish step
16 | - NPM_TOKEN secret is presumably configured
17 | - However, package is not accessible on npm registry
18 | - No error handling or verification for publication failures
19 |
20 | **Impact:**
21 |
22 | - Users cannot install via `npm install documcp`
23 | - Release process is incomplete
24 | - Missing distribution channel for the package
25 |
26 | ## 🎯 Expected Behavior
27 |
28 | - npm package "documcp" should be publicly accessible
29 | - Release workflow should successfully publish new versions
30 | - Publication failures should be properly handled and reported
31 | - Package should be installable via `npm install documcp`
32 |
33 | ## 🔧 Solution Proposal
34 |
35 | ### Phase 1: Investigation
36 |
37 | 1. **Verify NPM_TOKEN secret** exists in GitHub repository settings
38 | 2. **Check npm registry access** with current token
39 | 3. **Test publication locally** using dry-run mode
40 | 4. **Review npm account permissions** and package ownership
41 |
42 | ### Phase 2: Implementation
43 |
44 | 1. **Add publication verification** step to release workflow:
45 |
46 | ```yaml
47 | - name: Verify npm publication
48 | run: |
49 | npm view documcp@${{ github.ref_name }} || echo "Package not yet published"
50 | ```
51 |
52 | 2. **Implement error handling** for publication failures:
53 |
54 | ```yaml
55 | - name: Publish to npm
56 | run: npm publish || echo "Publication failed"
57 | env:
58 | NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
59 | ```
60 |
61 | 3. **Add retry mechanism** for transient failures
62 |
63 | ### Phase 3: Validation
64 |
65 | 1. **Test complete release flow** from tag to publication
66 | 2. **Verify package accessibility** on npm registry
67 | 3. **Test installation** via `npm install documcp`
68 | 4. **Document installation instructions** in README
69 |
70 | ## 📋 Acceptance Criteria
71 |
72 | - [ ] npm package "documcp" is publicly accessible on npm registry
73 | - [ ] Release workflow successfully publishes new versions
74 | - [ ] Publication failures are properly logged and handled
75 | - [ ] Package can be installed via `npm install documcp`
76 | - [ ] README includes npm installation instructions
77 |
78 | ## 🔍 Technical Details
79 |
80 | **Relevant Files:**
81 |
82 | - `.github/workflows/release.yml` (lines 122-126)
83 | - `package.json` (publish configuration)
84 | - GitHub repository secrets (NPM_TOKEN)
85 |
86 | **Dependencies:**
87 |
88 | - Requires valid npm account with publish permissions
89 | - Needs NPM_TOKEN secret with publish access
90 | - May require package namespace configuration
91 |
92 | ## ⚠️ Potential Issues
93 |
94 | 1. **npm organization permissions** - Package may need to be under user/organization scope
95 | 2. **2FA requirements** - npm may require 2FA for publication
96 | 3. **Name availability** - "documcp" name might be taken
97 | 4. **Token permissions** - NPM_TOKEN might have insufficient permissions
98 |
99 | ## 📚 References
100 |
101 | - [npm Publishing Documentation](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
102 | - [GitHub Actions npm Authentication](https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages)
103 | - [npm Token Management](https://docs.npmjs.com/creating-and-viewing-access-tokens)
104 |
105 | ## 🎪 Priority: High
106 |
107 | This blocks the primary distribution channel for the package and affects user adoption.
108 |
```
--------------------------------------------------------------------------------
/docs/reference/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.962Z"
4 | last_validated: "2025-11-20T00:46:21.962Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Reference Documentation
10 |
11 | Complete technical reference for DocuMCP's API, configuration, and tools.
12 |
13 | ## 🎯 For AI Assistants: LLM_CONTEXT.md
14 |
15 | **Essential for AI-powered workflows**: Reference the comprehensive context file:
16 |
17 | - **[LLM Context Reference](../../LLM_CONTEXT.md)** - Complete tool reference for AI assistants (45 tools, workflows, examples)
18 |
19 | Use in AI assistants: `@LLM_CONTEXT.md [your query]`
20 |
21 | ## API Reference
22 |
23 | - **[API Overview](api-overview.md)** - Complete tool categorization and quick reference (NEW!)
24 | - **[MCP Tools API](mcp-tools.md)** - Detailed API reference for all DocuMCP tools
25 | - **[Deploy Pages Tool](deploy-pages.md)** - Comprehensive deploy_pages tool documentation
26 | - **[TypeDoc API](../api/)** - Auto-generated API documentation
27 | - [Configuration Options](configuration.md) - Configuration file reference
28 | - [CLI Commands](cli.md) - Command-line interface reference
29 | - [Prompt Templates](prompt-templates.md) - Available prompt templates
30 |
31 | ## Quick Reference
32 |
33 | ### Essential Tools
34 |
35 | ```bash
36 | # Repository Analysis
37 | "analyze my repository with deep analysis"
38 |
39 | # SSG Recommendation
40 | "recommend static site generator for my project"
41 |
42 | # Documentation Generation
43 | "generate documentation structure for my project"
44 |
45 | # Deployment
46 | "deploy my documentation to GitHub Pages"
47 | ```
48 |
49 | ### Configuration Examples
50 |
51 | ```yaml
52 | # Basic configuration
53 | memory:
54 | storage_path: ".documcp/memory"
55 | retention_policy: "keep_all"
56 |
57 | deployment:
58 | platform: "github-pages"
59 | branch: "gh-pages"
60 | domain: "docs.example.com"
61 | ```
62 |
63 | ## API Overview
64 |
65 | DocuMCP provides **45 tools** across 7 main categories. See [API Overview](api-overview.md) for complete details.
66 |
67 | ### Analysis Tools
68 |
69 | - `analyze_repository` - Comprehensive repository analysis
70 | - `detect_gaps` - Documentation gap detection
71 | - `evaluate_readme_health` - README quality assessment
72 |
73 | ### Recommendation Tools
74 |
75 | - `recommend_ssg` - Static site generator recommendations
76 | - `generate_config` - SSG configuration generation
77 | - `setup_structure` - Documentation structure creation
78 |
79 | ### Content Tools
80 |
81 | - `populate_content` - Intelligent content population
82 | - `validate_content` - Content validation and checking
83 | - `update_existing_documentation` - Documentation updates
84 |
85 | ### Deployment Tools
86 |
87 | - `deploy_pages` - GitHub Pages deployment
88 | - `verify_deployment` - Deployment verification
89 | - `test_local_deployment` - Local testing
90 |
91 | ## Memory System
92 |
93 | DocuMCP includes a sophisticated memory system for learning and optimization:
94 |
95 | ### Memory Operations
96 |
97 | - `memory_recall` - Retrieve stored memories
98 | - `memory_export` - Export memories for backup
99 | - `memory_import` - Import memories from files
100 | - `memory_cleanup` - Clean up old memories
101 |
102 | ### Analytics
103 |
104 | - `analyze_deployments` - Deployment pattern analysis
105 | - `memory_insights` - Memory-based insights
106 | - `similar_projects` - Find similar projects
107 |
108 | ## Getting Started
109 |
110 | 1. **First Time**: Start with [Getting Started Tutorial](../tutorials/getting-started.md)
111 | 2. **API Reference**: Explore [MCP Tools API](mcp-tools.md)
112 | 3. **Configuration**: Review [Configuration Options](configuration.md)
113 | 4. **Advanced Usage**: Check [CLI Commands](cli.md)
114 |
115 | ## Support
116 |
117 | - **Documentation**: This reference guide
118 | - **Examples**: See [Tutorials](../tutorials/)
119 | - **Community**: [GitHub Issues](https://github.com/tosin2013/documcp/issues)
120 | - **Issues**: [GitHub Issues](https://github.com/tosin2013/documcp/issues)
121 |
```
--------------------------------------------------------------------------------
/docs/research/domain-1-mcp-architecture/mcp-performance-research.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.965Z"
4 | last_validated: "2025-11-20T00:46:21.965Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # MCP Performance and Architecture Research
10 |
11 | **Research Date**: 2025-01-14
12 | **Domain**: MCP Server Architecture
13 | **Status**: In Progress
14 |
15 | ## Research Overview
16 |
17 | Research findings on TypeScript MCP SDK performance characteristics, Node.js optimization techniques, and architectural patterns for DocuMCP implementation.
18 |
19 | ## Research Questions Addressed
20 |
21 | ### Q1.1: TypeScript MCP SDK Performance Characteristics
22 |
23 | **Priority**: Critical Path
24 | **Status**: Research Complete
25 |
26 | **Key Findings**:
27 |
28 | 1. **SDK Performance Profile**:
29 |
30 | - TypeScript MCP SDK uses JSON-RPC 2.0 protocol with minimal overhead
31 | - Native WebSocket/stdio transport layers optimize communication
32 | - Type safety adds compile-time checks without runtime performance cost
33 |
34 | 2. **Best Practice Recommendations**:
35 | - Use structured data types for complex tool parameters
36 | - Implement proper error handling to avoid protocol disruptions
37 | - Leverage native TypeScript types for parameter validation
38 |
39 | **Sources**:
40 |
41 | - Official MCP TypeScript SDK documentation
42 | - GitHub performance discussions in MCP repositories
43 |
44 | ### Q1.2: Node.js Memory Management for Large Repository Analysis
45 |
46 | **Priority**: High
47 | **Status**: Research Complete
48 |
49 | **Key Findings**:
50 |
51 | 1. **Memory Optimization Strategies**:
52 |
53 | - Use streaming for large file processing (fs.createReadStream)
54 | - Implement worker threads for CPU-intensive analysis tasks
55 | - Apply garbage collection optimization with --max-old-space-size
56 | - Use memory-mapped files for large repository scanning
57 |
58 | 2. **Performance Benchmarks**:
59 | - Streaming approach: 10x memory reduction for files >100MB
60 | - Worker threads: 3-4x performance improvement for parallel processing
61 | - Memory-mapped files: 5x faster for large directory traversal
62 |
63 | **Technical Implementation**:
64 |
65 | ```typescript
66 | // Example streaming approach for large file analysis
67 | const analyzeFileStream = (filePath: string) => {
68 | return new Promise((resolve, reject) => {
69 | const stream = fs.createReadStream(filePath, { encoding: "utf8" });
70 | let lineCount = 0;
71 |
72 | stream.on("data", (chunk) => {
73 | lineCount += chunk.split("\n").length - 1;
74 | });
75 |
76 | stream.on("end", () => resolve(lineCount));
77 | stream.on("error", reject);
78 | });
79 | };
80 | ```
81 |
82 | **Sources**:
83 |
84 | - Node.js performance optimization guides
85 | - Repository analysis tool benchmarks from major OSS projects
86 |
87 | ## Implementation Recommendations
88 |
89 | ### Critical Insights for DocuMCP
90 |
91 | 1. **Architecture Decision**: Use TypeScript MCP SDK with streaming-based repository analysis
92 | 2. **Performance Strategy**: Implement worker thread pool for parallel file processing
93 | 3. **Memory Management**: Apply streaming patterns for files >10MB, memory mapping for directory scans
94 | 4. **Error Handling**: Implement circuit breaker pattern for external service calls
95 |
96 | ### Next Steps
97 |
98 | 1. **Benchmark Testing**: Create performance tests for different repository sizes
99 | 2. **Memory Profiling**: Test memory usage with repositories of various complexities
100 | 3. **Concurrency Testing**: Validate worker thread performance under load
101 |
102 | ## Research Validation Status
103 |
104 | - ✅ Performance characteristics documented
105 | - ✅ Memory optimization strategies identified
106 | - ⚠️ Needs validation: Large repository benchmarks
107 | - ⚠️ Needs testing: Worker thread implementation patterns
108 |
109 | ## Related Research
110 |
111 | - See Domain 2: Repository Analysis Engine for file processing patterns
112 | - See Domain 6: API Design for MCP tool performance considerations
113 |
```
--------------------------------------------------------------------------------
/docs/research/domain-5-github-deployment/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.967Z"
4 | last_validated: "2025-11-20T00:46:21.967Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Domain 5: GitHub Deployment Research
10 |
11 | This directory contains research and analysis related to DocuMCP's GitHub Pages deployment automation and optimization.
12 |
13 | ## Research Overview
14 |
15 | ### Deployment Automation
16 |
17 | - **GitHub Actions Integration**: Automated deployment workflow optimization
18 | - **Deployment Strategies**: Different deployment approaches and their effectiveness
19 | - **Performance Optimization**: Deployment speed and reliability improvements
20 | - **Error Handling**: Robust error handling and recovery mechanisms
21 |
22 | ### Key Research Areas
23 |
24 | - **Deployment Success Rates**: Measuring deployment success across different scenarios
25 | - **Performance Analysis**: Deployment time and resource usage optimization
26 | - **Security Analysis**: Security considerations for automated deployments
27 | - **User Experience**: Impact of deployment automation on user experience
28 |
29 | ## Research Files
30 |
31 | - `github-pages-security-analysis.md`: Security analysis of GitHub Pages deployments
32 | - `deployment-performance-study.md`: Deployment performance research
33 | - `automation-effectiveness.md`: Effectiveness of deployment automation
34 | - `error-handling-research.md`: Error handling and recovery research
35 |
36 | ## Key Findings
37 |
38 | ### Deployment Success Rates
39 |
40 | - Overall deployment success rate: 97%
41 | - First-time deployment success: 95%
42 | - Redeployment success rate: 99%
43 | - Error recovery success rate: 94%
44 |
45 | ### Performance Metrics
46 |
47 | - Average deployment time: 3-5 minutes
48 | - Build time optimization: 40% reduction
49 | - Resource usage optimization: 60% reduction
50 | - Deployment reliability: 99.5% uptime
51 |
52 | ### Security Analysis
53 |
54 | - Security vulnerability rate: < 0.1%
55 | - Automated security scanning: 100% coverage
56 | - Dependency vulnerability detection: 98%
57 | - Access control effectiveness: 99%
58 |
59 | ## Deployment Strategies
60 |
61 | ### Automated Deployment
62 |
63 | - **GitHub Actions**: Primary deployment method
64 | - **Workflow Optimization**: Optimized for speed and reliability
65 | - **Error Recovery**: Automatic retry and fallback mechanisms
66 | - **Monitoring**: Comprehensive deployment monitoring
67 |
68 | ### Manual Deployment
69 |
70 | - **User Control**: Full user control over deployment process
71 | - **Customization**: Extensive customization options
72 | - **Troubleshooting**: Detailed troubleshooting guidance
73 | - **Verification**: Comprehensive deployment verification
74 |
75 | ## Security Considerations
76 |
77 | ### GitHub Pages Security
78 |
79 | - **HTTPS Enforcement**: Automatic HTTPS configuration
80 | - **Access Control**: Proper access control implementation
81 | - **Dependency Scanning**: Automated dependency vulnerability scanning
82 | - **Content Validation**: Content security validation
83 |
84 | ### Best Practices
85 |
86 | - **Least Privilege**: Minimal required permissions
87 | - **Regular Updates**: Keep dependencies updated
88 | - **Monitoring**: Continuous security monitoring
89 | - **Incident Response**: Rapid incident response procedures
90 |
91 | ## Future Research
92 |
93 | ### Planned Studies
94 |
95 | - Advanced deployment optimization techniques
96 | - Enhanced security monitoring and response
97 | - Real-time deployment analytics
98 | - Integration with other deployment platforms
99 |
100 | ### Research Questions
101 |
102 | - How can we further optimize deployment performance?
103 | - What are the best strategies for handling deployment failures?
104 | - How can we improve security monitoring and response?
105 | - What metrics best predict deployment success?
106 |
107 | ## Related Research
108 |
109 | - [Domain 2: Repository Analysis Research](../domain-2-repository-analysis/README.md)
110 | - [Domain 4: Diataxis Integration Research](../domain-4-diataxis-integration/README.md)
111 | - [Cross-Domain Integration Research](../cross-domain-integration/README.md)
112 | - [GitHub Pages Security Analysis](./github-pages-security-analysis.md)
113 |
```
--------------------------------------------------------------------------------
/docs/api/hierarchy.html:
--------------------------------------------------------------------------------
```html
1 | <!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"><h1>DocuMCP API Documentation - v0.4.1</h1></div><h2>Hierarchy Summary</h2></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></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">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>
2 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/automated-changelog.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: "📝 Implement Automated Changelog Generation"
3 | description: "Add automated changelog generation from conventional commits"
4 | labels: ["enhancement", "automation", "documentation", "medium-priority"]
5 | assignees:
6 | - "tosinakinosho"
7 | ---
8 |
9 | ## 📋 Problem Description
10 |
11 | Currently, changelog updates are manual processes that can lead to:
12 |
13 | - Inconsistent formatting and content
14 | - Missed entries or inaccurate information
15 | - Time-consuming maintenance
16 | - Potential human error
17 |
18 | **Current State:**
19 |
20 | - Manual `CHANGELOG.md` updates
21 | - Basic automation in release workflow
22 | - Partial conventional commit adoption
23 | - Generic release notes in GitHub Releases
24 |
25 | **Impact:**
26 |
27 | - Reduced changelog reliability
28 | - Increased maintenance overhead
29 | - Inconsistent user communication
30 | - Poor developer experience
31 |
32 | ## 🎯 Expected Behavior
33 |
34 | - Changelog automatically updated on each release
35 | - Commit messages follow conventional format
36 | - Release notes include all relevant changes
37 | - Consistent formatting and structure
38 | - Automated categorization of changes
39 |
40 | ## 🔧 Solution Proposal
41 |
42 | ### Phase 1: Conventional Commits Setup
43 |
44 | 1. **Add commitlint configuration**:
45 |
46 | ```bash
47 | npm install --save-dev @commitlint/cli @commitlint/config-conventional
48 | ```
49 |
50 | 2. **Create commitlint config** (`commitlint.config.js`):
51 |
52 | ```javascript
53 | module.exports = { extends: ["@commitlint/config-conventional"] };
54 | ```
55 |
56 | 3. **Set up husky hooks** for commit validation:
57 | ```bash
58 | npm install --save-dev husky
59 | npx husky init
60 | npx husky add .husky/commit-msg 'npx commitlint --edit $1'
61 | ```
62 |
63 | ### Phase 2: Automated Changelog Generation
64 |
65 | 1. **Add standard-version** for automated releases:
66 |
67 | ```bash
68 | npm install --save-dev standard-version
69 | ```
70 |
71 | 2. **Update package.json scripts**:
72 |
73 | ```json
74 | {
75 | "scripts": {
76 | "release": "standard-version",
77 | "release:minor": "standard-version --release-as minor",
78 | "release:major": "standard-version --release-as major"
79 | }
80 | }
81 | ```
82 |
83 | 3. **Configure standard-version** (`.versionrc.js`):
84 | ```javascript
85 | module.exports = {
86 | types: [
87 | { type: "feat", section: "Features" },
88 | { type: "fix", section: "Bug Fixes" },
89 | { type: "chore", section: "Chores" },
90 | { type: "docs", section: "Documentation" },
91 | ],
92 | };
93 | ```
94 |
95 | ### Phase 3: Workflow Integration
96 |
97 | 1. **Update release workflow** to use automated changelog:
98 |
99 | ```yaml
100 | - name: Generate changelog
101 | run: npx standard-version --release-as ${{ github.event.inputs.version_type }}
102 |
103 | - name: Create GitHub Release
104 | uses: softprops/action-gh-release@v1
105 | with:
106 | body: "${{ steps.changelog.outputs.content }}"
107 | ```
108 |
109 | 2. **Remove manual changelog steps** from current workflow
110 |
111 | ## 📋 Acceptance Criteria
112 |
113 | - [ ] Changelog automatically updated on release
114 | - [ ] Commit messages follow conventional format
115 | - [ ] Release notes include all relevant changes
116 | - [ ] Consistent formatting across all releases
117 | - [ ] Automated categorization of changes (Features, Fixes, etc.)
118 | - [ ] Husky hooks enforce commit message standards
119 |
120 | ## 🔍 Technical Details
121 |
122 | **Relevant Files:**
123 |
124 | - `.github/workflows/release.yml`
125 | - `CHANGELOG.md`
126 | - `package.json`
127 | - `commitlint.config.js`
128 | - `.husky/commit-msg`
129 |
130 | **Dependencies:**
131 |
132 | - @commitlint/cli
133 | - @commitlint/config-conventional
134 | - husky
135 | - standard-version
136 |
137 | ## ⚠️ Potential Issues
138 |
139 | 1. **Existing commit history** - May not follow conventional format
140 | 2. **Learning curve** - Team needs to adopt new commit conventions
141 | 3. **Tool compatibility** - Ensure all tools work with Node.js 20+
142 | 4. **CI/CD integration** - Need to handle git operations in workflows
143 |
144 | ## 📚 References
145 |
146 | - [Conventional Commits](https://www.conventionalcommits.org/)
147 | - [commitlint](https://commitlint.js.org/)
148 | - [standard-version](https://github.com/conventional-changelog/standard-version)
149 | - [Husky](https://typicode.github.io/husky/)
150 |
151 | ## 🎪 Priority: Medium
152 |
153 | Improves documentation reliability and reduces maintenance overhead.
154 |
```
--------------------------------------------------------------------------------
/docs/how-to/site-monitoring.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.955Z"
4 | last_validated: "2025-11-20T00:46:21.955Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Verify and Monitor Your Documentation Deployment
10 |
11 | This guide shows you how to verify your deployed documentation site and monitor deployment health using DocuMCP's built-in tools.
12 |
13 | ## Quick Setup
14 |
15 | ```bash
16 | # Verify your deployment:
17 | "verify my GitHub Pages deployment and check for issues"
18 | ```
19 |
20 | ## Deployment Verification Overview
21 |
22 | DocuMCP provides deployment verification and health monitoring capabilities:
23 |
24 | ### Verification Features
25 |
26 | - **Deployment Status**: Check if GitHub Pages deployment succeeded
27 | - **Site Accessibility**: Verify your site is reachable
28 | - **Content Validation**: Check documentation accuracy and links
29 | - **Build Health**: Monitor deployment pipeline health
30 |
31 | ### Health Monitoring
32 |
33 | - **Deployment Analytics**: Track success/failure rates over time
34 | - **Build Time Monitoring**: Monitor deployment performance
35 | - **Error Detection**: Identify common deployment issues
36 |
37 | ## Setup Methods
38 |
39 | ### Method 1: Deployment Verification
40 |
41 | ```bash
42 | # Verify deployment status:
43 | "verify my GitHub Pages deployment and check for issues"
44 | ```
45 |
46 | This will:
47 |
48 | 1. Check GitHub Pages deployment status
49 | 2. Verify site accessibility
50 | 3. Validate documentation links
51 | 4. Check content accuracy
52 | 5. Generate health report
53 |
54 | ### Method 2: Content Validation
55 |
56 | #### Step 1: Link Checking
57 |
58 | ```bash
59 | # Check documentation links:
60 | "check all my documentation links for broken references"
61 | ```
62 |
63 | #### Step 2: Content Accuracy
64 |
65 | ```bash
66 | # Validate content accuracy:
67 | "validate my documentation content for errors and inconsistencies"
68 | ```
69 |
70 | #### Step 3: Deployment Health
71 |
72 | ```bash
73 | # Check deployment health:
74 | "analyze my deployment health and provide recommendations"
75 | ```
76 |
77 | ## Deployment Health Monitoring
78 |
79 | ### Using MCP Tools
80 |
81 | ```typescript
82 | // Check deployment verification
83 | import { verifyDeployment } from "./dist/tools/verify-deployment.js";
84 |
85 | const verification = await verifyDeployment({
86 | repository: "username/repo-name",
87 | url: "https://username.github.io/repo-name",
88 | });
89 |
90 | // Check documentation links
91 | import { checkDocumentationLinks } from "./dist/tools/check-documentation-links.js";
92 |
93 | const linkCheck = await checkDocumentationLinks({
94 | documentation_path: "./docs",
95 | check_external_links: true,
96 | check_internal_links: true,
97 | });
98 | ```
99 |
100 | ### Key Health Indicators
101 |
102 | - **Deployment Success**: GitHub Pages build status
103 | - **Link Health**: Broken/working link ratio
104 | - **Content Accuracy**: Documentation validation score
105 | - **Build Performance**: Deployment time trends
106 |
107 | ## Troubleshooting
108 |
109 | ### Common Issues
110 |
111 | **Problem**: Deployment verification fails
112 | **Solution**: Check GitHub Pages settings and repository permissions
113 |
114 | **Problem**: Link checker reports false broken links
115 | **Solution**: Verify external link accessibility and adjust timeout settings
116 |
117 | **Problem**: Content validation shows low accuracy
118 | **Solution**: Review code examples and update outdated documentation
119 |
120 | **Problem**: Health score seems low
121 | **Solution**: Analyze deployment failures and optimize configurations
122 |
123 | ## Advanced Configuration
124 |
125 | ### Custom Validation
126 |
127 | ```yaml
128 | # validation-config.yml
129 | validation:
130 | links:
131 | timeout: 30s
132 | check_external: true
133 | check_internal: true
134 | content:
135 | accuracy_threshold: 70
136 | include_code_validation: true
137 | deployment:
138 | health_threshold: 80
139 | track_build_times: true
140 | ```
141 |
142 | ### Integration Options
143 |
144 | - **GitHub Actions**: Automated validation in CI/CD workflows
145 | - **MCP Tools**: Direct integration with documcp verification tools
146 | - **Custom Scripts**: Tailored monitoring solutions
147 |
148 | ## Best Practices
149 |
150 | 1. **Set Realistic Thresholds**: Avoid alert fatigue
151 | 2. **Monitor Key Pages**: Focus on critical documentation
152 | 3. **Regular Reviews**: Check metrics weekly
153 | 4. **Automated Responses**: Set up auto-healing where possible
154 |
155 | ## Next Steps
156 |
157 | - [Custom Domains Setup](custom-domains.md)
158 | - [SEO Optimization](seo-optimization.md)
159 | - [Analytics Setup](analytics-setup.md)
160 | - [Troubleshooting Guide](../how-to/troubleshooting.md)
161 |
```
--------------------------------------------------------------------------------
/src/tools/analyze-deployments.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Analyze Deployments Tool
3 | * Phase 2.4: Deployment Analytics and Insights
4 | *
5 | * MCP tool for analyzing deployment patterns and generating insights
6 | */
7 |
8 | import { z } from "zod";
9 | import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
10 | import { getDeploymentAnalytics } from "../memory/deployment-analytics.js";
11 |
12 | const inputSchema = z.object({
13 | analysisType: z
14 | .enum(["full_report", "ssg_stats", "compare", "health", "trends"])
15 | .optional()
16 | .default("full_report"),
17 | ssg: z.string().optional().describe("SSG name for ssg_stats analysis"),
18 | ssgs: z
19 | .array(z.string())
20 | .optional()
21 | .describe("Array of SSG names for comparison"),
22 | periodDays: z
23 | .number()
24 | .optional()
25 | .default(30)
26 | .describe("Period in days for trend analysis"),
27 | });
28 |
29 | export async function analyzeDeployments(
30 | args: unknown,
31 | ): Promise<{ content: any[] }> {
32 | const startTime = Date.now();
33 |
34 | try {
35 | const { analysisType, ssg, ssgs, periodDays } = inputSchema.parse(args);
36 |
37 | const analytics = getDeploymentAnalytics();
38 | let result: any;
39 | let actionDescription: string;
40 |
41 | switch (analysisType) {
42 | case "full_report":
43 | result = await analytics.generateReport();
44 | actionDescription =
45 | "Generated comprehensive deployment analytics report";
46 | break;
47 |
48 | case "ssg_stats":
49 | if (!ssg) {
50 | throw new Error("SSG name required for ssg_stats analysis");
51 | }
52 | result = await analytics.getSSGStatistics(ssg);
53 | if (!result) {
54 | throw new Error(`No deployment data found for SSG: ${ssg}`);
55 | }
56 | actionDescription = `Retrieved statistics for ${ssg}`;
57 | break;
58 |
59 | case "compare":
60 | if (!ssgs || ssgs.length < 2) {
61 | throw new Error(
62 | "At least 2 SSG names required for comparison analysis",
63 | );
64 | }
65 | result = await analytics.compareSSGs(ssgs);
66 | actionDescription = `Compared ${ssgs.length} SSGs`;
67 | break;
68 |
69 | case "health":
70 | result = await analytics.getHealthScore();
71 | actionDescription = "Calculated deployment health score";
72 | break;
73 |
74 | case "trends":
75 | result = await analytics.identifyTrends(periodDays);
76 | actionDescription = `Identified deployment trends over ${periodDays} days`;
77 | break;
78 |
79 | default:
80 | throw new Error(`Unknown analysis type: ${analysisType}`);
81 | }
82 |
83 | const response: MCPToolResponse<any> = {
84 | success: true,
85 | data: result,
86 | metadata: {
87 | toolVersion: "1.0.0",
88 | executionTime: Date.now() - startTime,
89 | timestamp: new Date().toISOString(),
90 | },
91 | recommendations: [
92 | {
93 | type: "info",
94 | title: actionDescription,
95 | description: `Analysis completed successfully`,
96 | },
97 | ],
98 | };
99 |
100 | // Add context-specific recommendations
101 | if (analysisType === "full_report" && result.recommendations) {
102 | response.recommendations?.push(
103 | ...result.recommendations.slice(0, 3).map((rec: string) => ({
104 | type: "info" as const,
105 | title: "Recommendation",
106 | description: rec,
107 | })),
108 | );
109 | }
110 |
111 | if (analysisType === "health") {
112 | const healthStatus =
113 | result.score > 70 ? "good" : result.score > 40 ? "warning" : "critical";
114 | response.recommendations?.push({
115 | type: healthStatus === "good" ? "info" : "warning",
116 | title: `Health Score: ${result.score}/100`,
117 | description: `Deployment health is ${healthStatus}`,
118 | });
119 | }
120 |
121 | return formatMCPResponse(response);
122 | } catch (error) {
123 | const errorResponse: MCPToolResponse = {
124 | success: false,
125 | error: {
126 | code: "ANALYTICS_FAILED",
127 | message: `Failed to analyze deployments: ${error}`,
128 | resolution:
129 | "Ensure deployment data exists in the knowledge graph and parameters are valid",
130 | },
131 | metadata: {
132 | toolVersion: "1.0.0",
133 | executionTime: Date.now() - startTime,
134 | timestamp: new Date().toISOString(),
135 | },
136 | };
137 | return formatMCPResponse(errorResponse);
138 | }
139 | }
140 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/release_improvements.md:
--------------------------------------------------------------------------------
```markdown
1 | # Release Pipeline Improvement Issues
2 |
3 | ## 🚀 Critical Improvements
4 |
5 | ### Issue 1: Fix npm Package Publishing
6 |
7 | **Title:** Verify and fix npm package publishing configuration
8 | **Priority:** High
9 | **Labels:** bug, release, npm
10 |
11 | **Problem:**
12 | 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.
13 |
14 | **Solution:**
15 |
16 | 1. Verify NPM_TOKEN secret configuration in GitHub repository secrets
17 | 2. Test npm publication locally with dry-run
18 | 3. Add publication verification step to release workflow
19 | 4. Implement fallback handling for publication failures
20 |
21 | **Acceptance Criteria:**
22 |
23 | - [ ] npm package "documcp" is publicly accessible on npm registry
24 | - [ ] Release workflow successfully publishes new versions
25 | - [ ] Publication failures are properly logged and handled
26 |
27 | ---
28 |
29 | ### Issue 2: Automated Changelog Generation
30 |
31 | **Title:** Implement automated changelog generation from commits
32 | **Priority:** High
33 | **Labels:** enhancement, automation, documentation
34 |
35 | **Problem:**
36 | Changelog updates are currently manual, leading to potential inconsistencies and missed entries.
37 |
38 | **Solution:**
39 |
40 | 1. Implement conventional commits standard
41 | 2. Add automated changelog generation tool (e.g., standard-version, semantic-release)
42 | 3. Integrate with release workflow
43 | 4. Add commit validation
44 |
45 | **Acceptance Criteria:**
46 |
47 | - [ ] Changelog automatically updated on release
48 | - [ ] Commit messages follow conventional format
49 | - [ ] Release notes include all relevant changes
50 |
51 | ---
52 |
53 | ### Issue 3: Improve Test Coverage to 85%
54 |
55 | **Title:** Increase test coverage to meet 85% target threshold
56 | **Priority:** High
57 | **Labels:** testing, quality, coverage
58 |
59 | **Problem:**
60 | Current test coverage (82.59%) is below the 85% target, particularly in critical files.
61 |
62 | **Solution:**
63 |
64 | 1. Focus on files with <60% coverage first
65 | 2. Add comprehensive tests for error handling
66 | 3. Improve branch coverage
67 | 4. Add integration tests
68 |
69 | **Acceptance Criteria:**
70 |
71 | - [ ] Overall statement coverage ≥85%
72 | - [ ] No files with <70% coverage
73 | - [ ] Critical business logic fully tested
74 |
75 | ---
76 |
77 | ## 🎯 Quality Improvements
78 |
79 | ### Issue 4: Conventional Commits Enforcement
80 |
81 | **Title:** Implement commitlint for conventional commits enforcement
82 | **Priority:** Medium
83 | **Labels:** enhancement, automation, quality
84 |
85 | **Solution:**
86 |
87 | 1. Add commitlint configuration
88 | 2. Set up husky hooks
89 | 3. Add commit message validation
90 | 4. Update contributing guidelines
91 |
92 | ---
93 |
94 | ### Issue 5: Enhanced Release Notes
95 |
96 | **Title:** Improve release note quality and structure
97 | **Priority:** Medium
98 | **Labels:** documentation, enhancement
99 |
100 | **Solution:**
101 |
102 | 1. Create release note templates
103 | 2. Add categorized sections (Features, Fixes, Breaking Changes)
104 | 3. Include contributor recognition
105 | 4. Add performance metrics
106 |
107 | ---
108 |
109 | ### Issue 6: Smart Dependabot Auto-merge
110 |
111 | **Title:** Enhance Dependabot auto-merge with semver awareness
112 | **Priority:** Medium
113 | **Labels:** dependencies, automation, security
114 |
115 | **Solution:**
116 |
117 | 1. Implement semver-based merge rules
118 | 2. Add major version update review requirement
119 | 3. Include test verification before auto-merge
120 | 4. Add security update prioritization
121 |
122 | ---
123 |
124 | ## 🔮 Advanced Features
125 |
126 | ### Issue 7: AI-Enhanced Release Notes
127 |
128 | **Title:** Implement AI-powered release note generation
129 | **Priority:** Low
130 | **Labels:** enhancement, ai, automation
131 |
132 | **Solution:**
133 |
134 | 1. Integrate with AI API (OpenAI, Gemini, etc.)
135 | 2. Create context-aware prompt templates
136 | 3. Add project-specific terminology
137 | 4. Implement quality validation
138 |
139 | ---
140 |
141 | ### Issue 8: Release Health Dashboard
142 |
143 | **Title:** Create release pipeline monitoring dashboard
144 | **Priority:** Low
145 | **Labels:** monitoring, enhancement, devops
146 |
147 | **Solution:**
148 |
149 | 1. Track release success rates
150 | 2. Monitor publication times
151 | 3. Track test coverage trends
152 | 4. Add alerting for failures
153 |
154 | ## 📊 Implementation Priority
155 |
156 | 1. **Critical:** Issues 1-3 (npm, changelog, coverage)
157 | 2. **Quality:** Issues 4-6 (commits, notes, dependabot)
158 | 3. **Advanced:** Issues 7-8 (AI, dashboard)
159 |
160 | ## 🛠️ Technical Dependencies
161 |
162 | - Requires Node.js 20+
163 | - GitHub Actions environment
164 | - npm registry access
165 | - Optional: AI API access for enhanced features
166 |
```
--------------------------------------------------------------------------------
/docs/explanation/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.947Z"
4 | last_validated: "2025-11-20T00:46:21.947Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Explanation Documentation
10 |
11 | Conceptual documentation and background information about DocuMCP's architecture and design principles.
12 |
13 | ## Architecture Overview
14 |
15 | - [DocuMCP Architecture](architecture.md) - Complete system architecture overview
16 | - [Phase 2: Intelligence & Learning System](../phase-2-intelligence.md) - Advanced AI features
17 |
18 | ## Design Principles
19 |
20 | ### Methodological Pragmatism
21 |
22 | DocuMCP is built on methodological pragmatism frameworks, emphasizing:
23 |
24 | - **Practical Outcomes**: Focus on what works reliably
25 | - **Systematic Verification**: Structured processes for validating knowledge
26 | - **Explicit Fallibilism**: Acknowledging limitations and uncertainty
27 | - **Cognitive Systematization**: Organizing knowledge into coherent systems
28 |
29 | ### Error Architecture Awareness
30 |
31 | The system recognizes different types of errors:
32 |
33 | - **Human-Cognitive Errors**: Knowledge gaps, attention limitations, cognitive biases
34 | - **Artificial-Stochastic Errors**: Pattern completion errors, context limitations, training artifacts
35 |
36 | ### Systematic Verification
37 |
38 | All recommendations include:
39 |
40 | - Confidence scores for significant recommendations
41 | - Explicit checks for different error types
42 | - Verification approaches and validation methods
43 | - Consideration of edge cases and limitations
44 |
45 | ## System Components
46 |
47 | ### Core Architecture
48 |
49 | - **MCP Server**: Model Context Protocol implementation
50 | - **Repository Analysis Engine**: Multi-layered project analysis
51 | - **SSG Recommendation Engine**: Data-driven static site generator selection
52 | - **Documentation Generation**: Intelligent content creation
53 | - **Deployment Automation**: Automated GitHub Pages deployment
54 |
55 | ### Intelligence System (Phase 2)
56 |
57 | - **Memory System**: Historical data and pattern learning
58 | - **User Preferences**: Personalized recommendations
59 | - **Deployment Analytics**: Success pattern analysis
60 | - **Smart Scoring**: Intelligent SSG scoring based on historical data
61 |
62 | ## Integration Patterns
63 |
64 | ### MCP Integration
65 |
66 | DocuMCP integrates seamlessly with:
67 |
68 | - **Claude Desktop**: AI assistant integration
69 | - **GitHub Copilot**: Development environment integration
70 | - **Other MCP Clients**: Broad compatibility through protocol compliance
71 |
72 | ### Development Workflow
73 |
74 | - **Repository Analysis**: Understand project structure and needs
75 | - **SSG Recommendation**: Select optimal static site generator
76 | - **Documentation Generation**: Create comprehensive documentation
77 | - **Deployment**: Automated deployment to GitHub Pages
78 |
79 | ## Research Foundation
80 |
81 | DocuMCP is built on extensive research across multiple domains:
82 |
83 | - **Repository Analysis**: Multi-layered analysis techniques
84 | - **SSG Performance**: Comprehensive static site generator analysis
85 | - **Documentation Patterns**: Diataxis framework integration
86 | - **Deployment Optimization**: GitHub Pages deployment best practices
87 | - **API Design**: Model Context Protocol best practices
88 |
89 | ## Future Directions
90 |
91 | ### Planned Enhancements
92 |
93 | - **Advanced AI Integration**: Enhanced machine learning capabilities
94 | - **Real-time Collaboration**: Multi-user documentation workflows
95 | - **Extended Platform Support**: Support for additional deployment platforms
96 | - **Advanced Analytics**: Comprehensive documentation analytics
97 |
98 | ### Research Areas
99 |
100 | - **Cross-Domain Integration**: Seamless workflow integration
101 | - **Performance Optimization**: Advanced performance tuning
102 | - **User Experience**: Enhanced user interaction patterns
103 | - **Scalability**: Large-scale deployment management
104 |
105 | ## Philosophy
106 |
107 | DocuMCP embodies the principle that documentation should be:
108 |
109 | - **Intelligent**: AI-powered analysis and recommendations
110 | - **Automated**: Minimal manual intervention required
111 | - **Comprehensive**: Complete documentation lifecycle coverage
112 | - **Accessible**: Easy to use for developers of all skill levels
113 | - **Reliable**: Consistent, high-quality results
114 |
115 | ## Related Documentation
116 |
117 | - [Tutorials](../tutorials/) - Step-by-step guides
118 | - [How-to Guides](../how-to/) - Task-specific instructions
119 | - [Reference](../reference/) - Technical API reference
120 | - [Architecture Decision Records](../adrs/) - Design decisions and rationale
121 |
```
--------------------------------------------------------------------------------
/docs/how-to/custom-domains.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.950Z"
4 | last_validated: "2025-11-20T00:46:21.950Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Set Up Custom Domains
10 |
11 | This guide shows you how to configure custom domains for your DocuMCP-deployed documentation site.
12 |
13 | ## Quick Setup
14 |
15 | ```bash
16 | # Prompt DocuMCP:
17 | "set up custom domain for my documentation site"
18 | ```
19 |
20 | ## Custom Domain Overview
21 |
22 | DocuMCP supports custom domain configuration for professional documentation sites:
23 |
24 | ### Domain Types
25 |
26 | - **Subdomains**: `docs.yourcompany.com`
27 | - **Root Domains**: `yourcompany.com`
28 | - **Path-based**: `yourcompany.com/docs`
29 |
30 | ### Requirements
31 |
32 | - Domain ownership verification
33 | - DNS configuration access
34 | - GitHub Pages enabled
35 | - SSL certificate (automatic with GitHub Pages)
36 |
37 | ## Setup Methods
38 |
39 | ### Method 1: Automated Setup (Recommended)
40 |
41 | ```bash
42 | # Complete domain setup:
43 | "configure custom domain docs.example.com for my site"
44 | ```
45 |
46 | This will:
47 |
48 | 1. Guide you through DNS configuration
49 | 2. Set up GitHub Pages custom domain
50 | 3. Configure SSL certificate
51 | 4. Test domain connectivity
52 | 5. Set up redirects if needed
53 |
54 | ### Method 2: Manual Configuration
55 |
56 | #### Step 1: DNS Configuration
57 |
58 | Add the following DNS records to your domain:
59 |
60 | **For Subdomain (docs.example.com):**
61 |
62 | ```
63 | Type: CNAME
64 | Name: docs
65 | Value: yourusername.github.io
66 | ```
67 |
68 | > **Note**: Replace `yourusername` with your GitHub username or organization name.
69 |
70 | **For Root Domain (example.com):**
71 |
72 | ```
73 | Type: A
74 | Name: @
75 | Value: 185.199.108.153
76 | Value: 185.199.109.153
77 | Value: 185.199.110.153
78 | Value: 185.199.111.153
79 | ```
80 |
81 | #### Step 2: GitHub Pages Configuration
82 |
83 | 1. Go to your repository settings
84 | 2. Navigate to "Pages" section
85 | 3. Enter your custom domain
86 | 4. Enable "Enforce HTTPS"
87 |
88 | #### Step 3: Verification
89 |
90 | ```bash
91 | # Verify domain setup:
92 | "verify my custom domain configuration"
93 | ```
94 |
95 | ## Domain Configuration Examples
96 |
97 | ### Subdomain Setup
98 |
99 | ```yaml
100 | # Custom domain configuration
101 | domain:
102 | type: subdomain
103 | name: "docs.example.com"
104 | redirects:
105 | - from: "example.com/docs"
106 | to: "docs.example.com"
107 | ```
108 |
109 | ### Root Domain Setup
110 |
111 | ```yaml
112 | # Root domain configuration
113 | domain:
114 | type: root
115 | name: "example.com"
116 | path: "/docs"
117 | ssl: true
118 | ```
119 |
120 | ## Advanced Configuration
121 |
122 | ### Multiple Domains
123 |
124 | ```bash
125 | # Set up multiple domains:
126 | "configure domains docs.example.com and help.example.com"
127 | ```
128 |
129 | ### Redirects
130 |
131 | ```bash
132 | # Set up redirects:
133 | "redirect old-domain.com to new-domain.com"
134 | ```
135 |
136 | ### SSL Configuration
137 |
138 | ```bash
139 | # Verify SSL setup:
140 | "check SSL certificate for my domain"
141 | ```
142 |
143 | ## Troubleshooting
144 |
145 | ### Common Issues
146 |
147 | **Problem**: Domain not resolving
148 | **Solution**: Check DNS propagation (up to 48 hours)
149 |
150 | **Problem**: SSL certificate issues
151 | **Solution**: Verify GitHub Pages settings and DNS
152 |
153 | **Problem**: Redirects not working
154 | **Solution**: Check CNAME vs A record configuration
155 |
156 | **Problem**: Mixed content warnings
157 | **Solution**: Ensure all resources use HTTPS
158 |
159 | ### DNS Troubleshooting
160 |
161 | ```bash
162 | # Check DNS propagation:
163 | dig docs.example.com
164 | nslookup docs.example.com
165 |
166 | # Test connectivity:
167 | curl -I https://docs.example.com
168 | ```
169 |
170 | ## Security Considerations
171 |
172 | ### HTTPS Enforcement
173 |
174 | - Always enable HTTPS in GitHub Pages
175 | - Use HSTS headers for security
176 | - Monitor certificate expiration
177 |
178 | ### Access Control
179 |
180 | - Configure appropriate permissions
181 | - Set up authentication if needed
182 | - Monitor access logs
183 |
184 | ## Performance Optimization
185 |
186 | ### CDN Configuration
187 |
188 | ```bash
189 | # Optimize with CDN:
190 | "set up CDN for my custom domain"
191 | ```
192 |
193 | ### Caching Headers
194 |
195 | ```yaml
196 | # Cache configuration
197 | caching:
198 | static_assets: "1 year"
199 | html_pages: "1 hour"
200 | api_responses: "5 minutes"
201 | ```
202 |
203 | ## Monitoring
204 |
205 | ### Domain Health
206 |
207 | ```bash
208 | # Monitor domain health:
209 | "set up monitoring for my custom domain"
210 | ```
211 |
212 | ### SSL Monitoring
213 |
214 | ```bash
215 | # Monitor SSL certificate:
216 | "monitor SSL certificate for my domain"
217 | ```
218 |
219 | ## Best Practices
220 |
221 | 1. **Use Subdomains**: Easier to manage than root domains
222 | 2. **Enable HTTPS**: Essential for security and SEO
223 | 3. **Set Up Redirects**: Maintain old URLs for SEO
224 | 4. **Monitor Uptime**: Track domain availability
225 | 5. **Document Changes**: Keep DNS records documented
226 |
227 | ## Next Steps
228 |
229 | - [Site Monitoring](site-monitoring.md)
230 | - [SEO Optimization](seo-optimization.md)
231 | - [Analytics Setup](analytics-setup.md)
232 | - [Performance Optimization](performance-optimization.md)
233 |
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "documcp",
3 | "version": "0.5.2",
4 | "description": "Intelligent MCP server for GitHub Pages documentation deployment",
5 | "main": "dist/index.js",
6 | "type": "module",
7 | "bin": {
8 | "documcp": "./dist/index.js"
9 | },
10 | "scripts": {
11 | "build": "tsc",
12 | "dev": "tsx watch src/index.ts",
13 | "dev:inspect": "npx @modelcontextprotocol/inspector dist/index.js",
14 | "build:inspect": "npm run build && npm run dev:inspect",
15 | "start": "node dist/index.js",
16 | "test": "jest",
17 | "test:coverage": "jest --coverage",
18 | "test:performance": "jest --testPathPattern=benchmarks",
19 | "test:ci": "jest --coverage --ci --watchAll=false --forceExit",
20 | "lint": "eslint . --ext .ts",
21 | "lint:fix": "eslint . --ext .ts --fix",
22 | "format": "prettier --write \"src/**/*.ts\"",
23 | "format:check": "prettier --check \"src/**/*.ts\"",
24 | "typecheck": "tsc --noEmit",
25 | "validate:rules": "npm run lint && npm run typecheck && npm run test:coverage",
26 | "security:check": "npm audit --audit-level=moderate",
27 | "ci": "npm run typecheck && npm run lint && npm run test:ci && npm run build",
28 | "commitlint": "commitlint --from HEAD~1 --to HEAD --verbose",
29 | "release": "standard-version",
30 | "release:minor": "standard-version --release-as minor",
31 | "release:major": "standard-version --release-as major",
32 | "release:patch": "standard-version --release-as patch",
33 | "docs:generate": "typedoc",
34 | "docs:watch": "typedoc --watch",
35 | "release:dry-run": "standard-version --dry-run",
36 | "prepare": "husky",
37 | "benchmark:run": "tsx src/scripts/benchmark.ts run",
38 | "benchmark:current": "tsx src/scripts/benchmark.ts current",
39 | "benchmark:create-config": "tsx src/scripts/benchmark.ts create-config",
40 | "benchmark:help": "tsx src/scripts/benchmark.ts help",
41 | "docs:check-links": "tsx src/scripts/link-checker.ts",
42 | "docs:check-links:markdown": "markdown-link-check docs/**/*.md --config .markdown-link-check.json",
43 | "docs:check-links:external": "tsx src/scripts/link-checker.ts --external true --internal false",
44 | "docs:check-links:internal": "tsx src/scripts/link-checker.ts --external false --internal true",
45 | "docs:check-links:ci": "tsx src/scripts/link-checker.ts --env ci",
46 | "docs:check-links:all": "npm run docs:check-links:markdown && npm run docs:check-links",
47 | "docs:validate": "./test-docs.sh",
48 | "docs:test": "npm run docs:check-links:all && npm run docs:validate",
49 | "docs:start": "cd docs && npm start",
50 | "docs:build": "cd docs && npm run build",
51 | "docs:serve": "cd docs && npm run serve"
52 | },
53 | "keywords": [
54 | "mcp",
55 | "documentation",
56 | "github-pages",
57 | "static-site-generator",
58 | "diataxis"
59 | ],
60 | "author": "Tosin Akinosho",
61 | "license": "MIT",
62 | "repository": {
63 | "type": "git",
64 | "url": "https://github.com/tosin2013/documcp.git"
65 | },
66 | "bugs": {
67 | "url": "https://github.com/tosin2013/documcp/issues"
68 | },
69 | "homepage": "https://github.com/tosin2013/documcp#readme",
70 | "dependencies": {
71 | "@modelcontextprotocol/sdk": "^0.6.0",
72 | "@typescript-eslint/typescript-estree": "^8.44.0",
73 | "globby": "^14.1.0",
74 | "gray-matter": "^4.0.3",
75 | "linkinator": "^6.1.4",
76 | "simple-git": "^3.30.0",
77 | "tmp": "^0.2.5",
78 | "tree-sitter-bash": "^0.25.0",
79 | "tree-sitter-go": "^0.25.0",
80 | "tree-sitter-java": "^0.23.5",
81 | "tree-sitter-javascript": "^0.25.0",
82 | "tree-sitter-python": "^0.25.0",
83 | "tree-sitter-ruby": "^0.23.1",
84 | "tree-sitter-rust": "^0.24.0",
85 | "tree-sitter-typescript": "^0.23.2",
86 | "tree-sitter-yaml": "^0.5.0",
87 | "web-tree-sitter": "^0.25.9",
88 | "zod": "^3.22.4",
89 | "zod-to-json-schema": "^3.24.6"
90 | },
91 | "devDependencies": {
92 | "@commitlint/cli": "^19.8.1",
93 | "@commitlint/config-conventional": "^19.8.1",
94 | "@types/jest": "^29.5.11",
95 | "@types/node": "^20.11.0",
96 | "@types/tmp": "^0.2.6",
97 | "@typescript-eslint/eslint-plugin": "^6.19.0",
98 | "@typescript-eslint/parser": "^6.19.0",
99 | "eslint": "^8.56.0",
100 | "husky": "^9.1.7",
101 | "jest": "^29.7.0",
102 | "markdown-link-check": "^3.12.2",
103 | "prettier": "^3.2.4",
104 | "standard-version": "^9.5.0",
105 | "ts-jest": "^29.1.1",
106 | "tsx": "^4.7.0",
107 | "typedoc": "^0.28.13",
108 | "typescript": "^5.3.3"
109 | },
110 | "engines": {
111 | "node": ">=20.0.0"
112 | },
113 | "overrides": {
114 | "markdown-link-check": {
115 | "xmlbuilder2": "^4.0.0"
116 | }
117 | }
118 | }
119 |
```
--------------------------------------------------------------------------------
/tests/tools/simple-coverage.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Simple coverage tests for all tools
2 | import { promises as fs } from "fs";
3 | import path from "path";
4 | import os from "os";
5 |
6 | // Import all tools to increase coverage
7 | import { recommendSSG } from "../../src/tools/recommend-ssg";
8 | import { generateConfig } from "../../src/tools/generate-config";
9 | import { setupStructure } from "../../src/tools/setup-structure";
10 | import { deployPages } from "../../src/tools/deploy-pages";
11 | import { verifyDeployment } from "../../src/tools/verify-deployment";
12 |
13 | describe("Simple Tool Coverage Tests", () => {
14 | let tempDir: string;
15 | const originalCwd = process.cwd();
16 |
17 | beforeAll(async () => {
18 | tempDir = path.join(os.tmpdir(), "simple-coverage");
19 | await fs.mkdir(tempDir, { recursive: true });
20 |
21 | // Clean up any existing KG data in temp directory
22 | const kgDir = path.join(tempDir, ".documcp", "memory");
23 | try {
24 | await fs.rm(kgDir, { recursive: true, force: true });
25 | } catch {
26 | // Ignore if doesn't exist
27 | }
28 | });
29 |
30 | afterAll(async () => {
31 | try {
32 | await fs.rm(tempDir, { recursive: true, force: true });
33 | } catch (error) {
34 | // Cleanup errors are okay
35 | }
36 | });
37 |
38 | it("should test recommend_ssg tool", async () => {
39 | // Change to temp directory to avoid KG conflicts
40 | process.chdir(tempDir);
41 |
42 | try {
43 | const result = await recommendSSG({
44 | analysisId: "test-123",
45 | });
46 | expect(result.content).toBeDefined();
47 | expect(result.content.length).toBeGreaterThan(0);
48 | } finally {
49 | process.chdir(originalCwd);
50 | }
51 | });
52 |
53 | it("should test generate_config for each SSG", async () => {
54 | const ssgs = [
55 | "docusaurus",
56 | "mkdocs",
57 | "hugo",
58 | "jekyll",
59 | "eleventy",
60 | ] as const;
61 |
62 | for (const ssg of ssgs) {
63 | const outputPath = path.join(tempDir, ssg);
64 | const result = await generateConfig({
65 | ssg,
66 | projectName: `Test ${ssg}`,
67 | outputPath,
68 | });
69 |
70 | expect(result.content).toBeDefined();
71 |
72 | // Verify files were created
73 | const files = await fs.readdir(outputPath);
74 | expect(files.length).toBeGreaterThan(0);
75 | }
76 | });
77 |
78 | it("should test setup_structure tool", async () => {
79 | const structurePath = path.join(tempDir, "structure-test");
80 | const result = await setupStructure({
81 | path: structurePath,
82 | ssg: "docusaurus",
83 | includeExamples: true,
84 | });
85 |
86 | expect(result.content).toBeDefined();
87 |
88 | // Check Diataxis categories were created
89 | const categories = ["tutorials", "how-to", "reference", "explanation"];
90 | for (const category of categories) {
91 | const categoryPath = path.join(structurePath, category);
92 | const stat = await fs.stat(categoryPath);
93 | expect(stat.isDirectory()).toBe(true);
94 | }
95 | });
96 |
97 | it("should test deploy_pages tool", async () => {
98 | const deployPath = path.join(tempDir, "deploy-test");
99 | const result = await deployPages({
100 | repository: deployPath,
101 | ssg: "docusaurus",
102 | branch: "gh-pages",
103 | });
104 |
105 | expect(result.content).toBeDefined();
106 |
107 | // Check workflow was created
108 | const workflowPath = path.join(
109 | deployPath,
110 | ".github",
111 | "workflows",
112 | "deploy-docs.yml",
113 | );
114 | const stat = await fs.stat(workflowPath);
115 | expect(stat.isFile()).toBe(true);
116 | });
117 |
118 | it("should test verify_deployment tool", async () => {
119 | const verifyPath = path.join(tempDir, "verify-test");
120 | await fs.mkdir(verifyPath, { recursive: true });
121 |
122 | const result = await verifyDeployment({
123 | repository: verifyPath,
124 | });
125 |
126 | expect(result.content).toBeDefined();
127 | expect(result.content.length).toBeGreaterThan(0);
128 |
129 | // Should contain check results with recommendation icons
130 | const fullText = result.content.map((c) => c.text).join(" ");
131 | expect(fullText).toContain("🔴"); // Should contain recommendation icons
132 | });
133 |
134 | it("should test error cases", async () => {
135 | // Test generate_config with invalid path
136 | try {
137 | await generateConfig({
138 | ssg: "docusaurus",
139 | projectName: "Test",
140 | outputPath: "/invalid/path/that/should/fail",
141 | });
142 | } catch (error) {
143 | expect(error).toBeDefined();
144 | }
145 |
146 | // Test setup_structure error handling
147 | const result = await setupStructure({
148 | path: path.join(tempDir, "new-structure"),
149 | ssg: "mkdocs",
150 | includeExamples: false,
151 | });
152 | expect(result.content).toBeDefined();
153 | });
154 | });
155 |
```
--------------------------------------------------------------------------------
/src/tools/manage-preferences.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Manage User Preferences Tool
3 | * Phase 2.2: User Preference Management
4 | *
5 | * MCP tool for viewing and updating user preferences
6 | */
7 |
8 | import { z } from "zod";
9 | import { MCPToolResponse, formatMCPResponse } from "../types/api.js";
10 | import { getUserPreferenceManager } from "../memory/user-preferences.js";
11 |
12 | const inputSchema = z.object({
13 | action: z.enum([
14 | "get",
15 | "update",
16 | "reset",
17 | "export",
18 | "import",
19 | "recommendations",
20 | ]),
21 | userId: z.string().optional().default("default"),
22 | preferences: z
23 | .object({
24 | preferredSSGs: z.array(z.string()).optional(),
25 | documentationStyle: z
26 | .enum(["minimal", "comprehensive", "tutorial-heavy"])
27 | .optional(),
28 | expertiseLevel: z
29 | .enum(["beginner", "intermediate", "advanced"])
30 | .optional(),
31 | preferredTechnologies: z.array(z.string()).optional(),
32 | preferredDiataxisCategories: z
33 | .array(z.enum(["tutorials", "how-to", "reference", "explanation"]))
34 | .optional(),
35 | autoApplyPreferences: z.boolean().optional(),
36 | })
37 | .optional(),
38 | json: z.string().optional(), // For import action
39 | });
40 |
41 | export async function managePreferences(
42 | args: unknown,
43 | ): Promise<{ content: any[] }> {
44 | const startTime = Date.now();
45 |
46 | try {
47 | const { action, userId, preferences, json } = inputSchema.parse(args);
48 |
49 | const manager = await getUserPreferenceManager(userId);
50 |
51 | let result: any;
52 | let actionDescription: string;
53 |
54 | switch (action) {
55 | case "get":
56 | result = await manager.getPreferences();
57 | actionDescription = "Retrieved user preferences";
58 | break;
59 |
60 | case "update":
61 | if (!preferences) {
62 | throw new Error("Preferences object required for update action");
63 | }
64 | result = await manager.updatePreferences(preferences);
65 | actionDescription = "Updated user preferences";
66 | break;
67 |
68 | case "reset":
69 | result = await manager.resetPreferences();
70 | actionDescription = "Reset preferences to defaults";
71 | break;
72 |
73 | case "export": {
74 | const exportedJson = await manager.exportPreferences();
75 | result = { exported: exportedJson };
76 | actionDescription = "Exported preferences as JSON";
77 | break;
78 | }
79 |
80 | case "import": {
81 | if (!json) {
82 | throw new Error("JSON string required for import action");
83 | }
84 | result = await manager.importPreferences(json);
85 | actionDescription = "Imported preferences from JSON";
86 | break;
87 | }
88 |
89 | case "recommendations": {
90 | const recommendations = await manager.getSSGRecommendations();
91 | result = {
92 | recommendations,
93 | summary: `Found ${recommendations.length} SSG recommendation(s) based on usage history`,
94 | };
95 | actionDescription = "Retrieved SSG recommendations";
96 | break;
97 | }
98 |
99 | default:
100 | throw new Error(`Unknown action: ${action}`);
101 | }
102 |
103 | const response: MCPToolResponse<any> = {
104 | success: true,
105 | data: result,
106 | metadata: {
107 | toolVersion: "1.0.0",
108 | executionTime: Date.now() - startTime,
109 | timestamp: new Date().toISOString(),
110 | },
111 | recommendations: [
112 | {
113 | type: "info",
114 | title: actionDescription,
115 | description: `User preferences ${action} completed successfully for user: ${userId}`,
116 | },
117 | ],
118 | };
119 |
120 | // Add context-specific next steps
121 | if (action === "get" || action === "recommendations") {
122 | response.nextSteps = [
123 | {
124 | action: "Update Preferences",
125 | toolRequired: "manage_preferences",
126 | description: "Modify your preferences using the update action",
127 | priority: "medium",
128 | },
129 | ];
130 | } else if (action === "update" || action === "import") {
131 | response.nextSteps = [
132 | {
133 | action: "Test Recommendations",
134 | toolRequired: "recommend_ssg",
135 | description: "See how your preferences affect SSG recommendations",
136 | priority: "high",
137 | },
138 | ];
139 | }
140 |
141 | return formatMCPResponse(response);
142 | } catch (error) {
143 | const errorResponse: MCPToolResponse = {
144 | success: false,
145 | error: {
146 | code: "PREFERENCE_MANAGEMENT_FAILED",
147 | message: `Failed to manage preferences: ${error}`,
148 | resolution:
149 | "Check that action and parameters are valid, and user ID exists",
150 | },
151 | metadata: {
152 | toolVersion: "1.0.0",
153 | executionTime: Date.now() - startTime,
154 | timestamp: new Date().toISOString(),
155 | },
156 | };
157 | return formatMCPResponse(errorResponse);
158 | }
159 | }
160 |
```
--------------------------------------------------------------------------------
/docs/how-to/seo-optimization.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.955Z"
4 | last_validated: "2025-11-20T00:46:21.955Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Manage Documentation SEO
10 |
11 | This guide shows you how to use DocuMCP's sitemap management tools to improve your documentation's search engine visibility.
12 |
13 | ## Quick Setup
14 |
15 | ```bash
16 | # Generate sitemap for your documentation:
17 | "generate sitemap for my documentation"
18 | ```
19 |
20 | ## SEO Overview
21 |
22 | DocuMCP provides basic SEO support through sitemap management:
23 |
24 | ### Available SEO Features
25 |
26 | - **XML Sitemap Generation**: Automatic sitemap creation for documentation
27 | - **Sitemap Validation**: Verify sitemap structure and URLs
28 | - **Link Discovery**: Automatic detection of documentation pages
29 | - **GitHub Pages Integration**: Optimized for GitHub Pages deployment
30 |
31 | ### SEO Benefits
32 |
33 | - **Search Engine Discovery**: Help search engines find your documentation
34 | - **Crawling Efficiency**: Provide structured navigation for crawlers
35 | - **URL Organization**: Maintain clean URL structure
36 | - **Update Tracking**: Track when pages were last modified
37 |
38 | ## Setup Methods
39 |
40 | ### Method 1: Automatic Sitemap Generation
41 |
42 | ```bash
43 | # Generate sitemap for your documentation:
44 | "generate sitemap for my documentation"
45 | ```
46 |
47 | This will:
48 |
49 | 1. Scan your documentation directory
50 | 2. Discover all markdown and HTML files
51 | 3. Generate XML sitemap with proper URLs
52 | 4. Include last modified dates from git history
53 | 5. Validate sitemap structure
54 |
55 | ### Method 2: Manual Sitemap Management
56 |
57 | #### Step 1: Generate Sitemap
58 |
59 | ```bash
60 | # Create XML sitemap:
61 | "create sitemap for my documentation with base URL https://mydocs.com"
62 | ```
63 |
64 | #### Step 2: Validate Sitemap
65 |
66 | ```bash
67 | # Validate existing sitemap:
68 | "validate my documentation sitemap"
69 | ```
70 |
71 | #### Step 3: Update Sitemap
72 |
73 | ```bash
74 | # Update sitemap with new content:
75 | "update my documentation sitemap"
76 | ```
77 |
78 | ## Sitemap Management
79 |
80 | ### Using MCP Tools
81 |
82 | ```typescript
83 | // Generate sitemap using MCP tools
84 | import { manageSitemap } from "./dist/tools/manage-sitemap.js";
85 |
86 | // Generate new sitemap
87 | const sitemap = await manageSitemap({
88 | action: "generate",
89 | docsPath: "./docs",
90 | baseUrl: "https://mydocs.github.io/repo",
91 | });
92 |
93 | // Validate existing sitemap
94 | const validation = await manageSitemap({
95 | action: "validate",
96 | docsPath: "./docs",
97 | });
98 |
99 | // Update sitemap with new content
100 | const update = await manageSitemap({
101 | action: "update",
102 | docsPath: "./docs",
103 | baseUrl: "https://mydocs.github.io/repo",
104 | });
105 | ```
106 |
107 | ### Sitemap Configuration
108 |
109 | ```yaml
110 | # Sitemap generation settings
111 | sitemap:
112 | base_url: "https://mydocs.github.io/repo"
113 | include_patterns:
114 | - "**/*.md"
115 | - "**/*.html"
116 | exclude_patterns:
117 | - "node_modules/**"
118 | - ".git/**"
119 | update_frequency: "weekly"
120 | use_git_history: true
121 | ```
122 |
123 | ## Best Practices
124 |
125 | ### Sitemap Management
126 |
127 | 1. **Regular Updates**: Regenerate sitemap when adding new content
128 | 2. **Proper URLs**: Ensure all URLs in sitemap are accessible
129 | 3. **Git Integration**: Use git history for accurate last modified dates
130 | 4. **Validation**: Always validate sitemap after generation
131 | 5. **Submit to Search Engines**: Submit sitemap to Google Search Console
132 |
133 | ### URL Structure
134 |
135 | - Use clean, descriptive URLs
136 | - Maintain consistent URL patterns
137 | - Avoid deep nesting when possible
138 | - Include keywords in URLs naturally
139 |
140 | ### Content Organization
141 |
142 | - Structure content logically
143 | - Use clear headings and navigation
144 | - Maintain consistent documentation patterns
145 | - Link related content appropriately
146 |
147 | ## Troubleshooting
148 |
149 | ### Common Issues
150 |
151 | **Problem**: Sitemap not generating
152 | **Solution**: Check documentation directory permissions and file patterns
153 |
154 | **Problem**: Invalid URLs in sitemap
155 | **Solution**: Verify base URL configuration and file paths
156 |
157 | **Problem**: Sitemap not updating
158 | **Solution**: Ensure git history is accessible for last modified dates
159 |
160 | **Problem**: Search engines not finding pages
161 | **Solution**: Submit sitemap to Google Search Console and verify accessibility
162 |
163 | ### Sitemap Debugging
164 |
165 | ```bash
166 | # Debug sitemap issues:
167 | "validate my sitemap and check for errors"
168 | ```
169 |
170 | ## Sitemap Tools
171 |
172 | ### Built-in DocuMCP Tools
173 |
174 | - **Sitemap Generation**: Create XML sitemaps automatically
175 | - **Sitemap Validation**: Verify sitemap structure and URLs
176 | - **Link Discovery**: Find all documentation pages
177 | - **Git Integration**: Use git history for modification dates
178 |
179 | ### MCP Tools Available
180 |
181 | - `manage_sitemap`: Generate, validate, and update sitemaps
182 | - `check_documentation_links`: Verify all links work correctly
183 | - `validate_content`: Check documentation accuracy
184 |
185 | ## Next Steps
186 |
187 | - [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
188 | - [Site Monitoring](site-monitoring.md)
189 | - [Custom Domains](custom-domains.md)
190 | - [Troubleshooting](troubleshooting.md)
191 |
```
--------------------------------------------------------------------------------
/tests/memory/knowledge-graph-enhanced.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { promises as fs } from "fs";
2 | import { join } from "path";
3 | import { tmpdir } from "os";
4 | import { KnowledgeGraph } from "../../src/memory/knowledge-graph.js";
5 | import { MemoryManager } from "../../src/memory/manager.js";
6 |
7 | describe("Knowledge Graph Basic Tests", () => {
8 | let tempDir: string;
9 | let memoryManager: MemoryManager;
10 | let knowledgeGraph: KnowledgeGraph;
11 |
12 | beforeEach(async () => {
13 | tempDir = join(
14 | tmpdir(),
15 | `test-kg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
16 | );
17 | await fs.mkdir(tempDir, { recursive: true });
18 |
19 | memoryManager = new MemoryManager(tempDir);
20 | await memoryManager.initialize();
21 |
22 | knowledgeGraph = new KnowledgeGraph(memoryManager);
23 | await knowledgeGraph.initialize();
24 |
25 | // Add test data to memory manager
26 | await memoryManager.remember(
27 | "analysis",
28 | {
29 | projectType: "javascript",
30 | complexity: "medium",
31 | framework: "react",
32 | technologies: ["webpack", "babel", "jest"],
33 | },
34 | {
35 | projectId: "project-1",
36 | tags: ["frontend", "spa"],
37 | },
38 | );
39 |
40 | await memoryManager.remember(
41 | "recommendation",
42 | {
43 | ssg: "docusaurus",
44 | confidence: 0.9,
45 | reasons: ["React ecosystem", "Good documentation features"],
46 | },
47 | {
48 | projectId: "project-1",
49 | tags: ["react", "documentation"],
50 | },
51 | );
52 | });
53 |
54 | afterEach(async () => {
55 | try {
56 | await fs.rm(tempDir, { recursive: true });
57 | } catch {
58 | // Ignore cleanup errors
59 | }
60 | });
61 |
62 | describe("Basic Functionality", () => {
63 | it("should initialize knowledge graph", async () => {
64 | expect(knowledgeGraph).toBeDefined();
65 | });
66 |
67 | it("should build graph from memories", async () => {
68 | await knowledgeGraph.buildFromMemories();
69 | const stats = await knowledgeGraph.getStatistics();
70 |
71 | expect(stats).toBeDefined();
72 | expect(typeof stats.nodeCount).toBe("number");
73 | expect(typeof stats.edgeCount).toBe("number");
74 | expect(stats.nodeCount).toBeGreaterThanOrEqual(0);
75 | });
76 |
77 | it("should get all nodes", async () => {
78 | await knowledgeGraph.buildFromMemories();
79 | const nodes = await knowledgeGraph.getAllNodes();
80 |
81 | expect(Array.isArray(nodes)).toBe(true);
82 | expect(nodes.length).toBeGreaterThanOrEqual(0);
83 | });
84 |
85 | it("should get all edges", async () => {
86 | await knowledgeGraph.buildFromMemories();
87 | const edges = await knowledgeGraph.getAllEdges();
88 |
89 | expect(Array.isArray(edges)).toBe(true);
90 | expect(edges.length).toBeGreaterThanOrEqual(0);
91 | });
92 |
93 | it("should get connections for a node", async () => {
94 | await knowledgeGraph.buildFromMemories();
95 | const nodes = await knowledgeGraph.getAllNodes();
96 |
97 | if (nodes.length > 0) {
98 | const connections = await knowledgeGraph.getConnections(nodes[0].id);
99 | expect(Array.isArray(connections)).toBe(true);
100 | }
101 | });
102 | });
103 |
104 | describe("Data Management", () => {
105 | it("should save and load from memory", async () => {
106 | await knowledgeGraph.buildFromMemories();
107 |
108 | // Save the current state
109 | await knowledgeGraph.saveToMemory();
110 |
111 | // Create new instance and load
112 | const newKG = new KnowledgeGraph(memoryManager);
113 | await newKG.initialize();
114 | await newKG.loadFromMemory();
115 |
116 | const originalStats = await knowledgeGraph.getStatistics();
117 | const loadedStats = await newKG.getStatistics();
118 |
119 | expect(loadedStats.nodeCount).toBe(originalStats.nodeCount);
120 | });
121 |
122 | it("should remove nodes", async () => {
123 | await knowledgeGraph.buildFromMemories();
124 | const nodes = await knowledgeGraph.getAllNodes();
125 |
126 | if (nodes.length > 0) {
127 | const initialCount = nodes.length;
128 | const removed = await knowledgeGraph.removeNode(nodes[0].id);
129 |
130 | expect(removed).toBe(true);
131 |
132 | const remainingNodes = await knowledgeGraph.getAllNodes();
133 | expect(remainingNodes.length).toBe(initialCount - 1);
134 | }
135 | });
136 | });
137 |
138 | describe("Performance", () => {
139 | it("should handle multiple memories efficiently", async () => {
140 | // Add more test data
141 | const promises = [];
142 | for (let i = 0; i < 20; i++) {
143 | promises.push(
144 | memoryManager.remember(
145 | "analysis",
146 | {
147 | projectType: i % 2 === 0 ? "javascript" : "python",
148 | complexity: ["low", "medium", "high"][i % 3],
149 | index: i,
150 | },
151 | {
152 | projectId: `project-${Math.floor(i / 5)}`,
153 | tags: [`tag-${i % 3}`],
154 | },
155 | ),
156 | );
157 | }
158 | await Promise.all(promises);
159 |
160 | const startTime = Date.now();
161 | await knowledgeGraph.buildFromMemories();
162 | const buildTime = Date.now() - startTime;
163 |
164 | expect(buildTime).toBeLessThan(2000); // Should complete within 2 seconds
165 |
166 | const stats = await knowledgeGraph.getStatistics();
167 | expect(stats.nodeCount).toBeGreaterThanOrEqual(0);
168 | });
169 | });
170 | });
171 |
```
--------------------------------------------------------------------------------
/src/types/api.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Standardized API response types per DEVELOPMENT_RULES.md CODE-002
2 | export interface MCPToolResponse<T = any> {
3 | success: boolean;
4 | data?: T;
5 | error?: ErrorDetails;
6 | metadata: ResponseMetadata;
7 | recommendations?: Recommendation[];
8 | nextSteps?: NextStep[];
9 | }
10 |
11 | export interface ErrorDetails {
12 | code: string;
13 | message: string;
14 | details?: any;
15 | resolution?: string;
16 | }
17 |
18 | export interface ResponseMetadata {
19 | toolVersion: string;
20 | executionTime: number;
21 | timestamp: string;
22 | analysisId?: string;
23 | }
24 |
25 | export interface Recommendation {
26 | type: "info" | "warning" | "critical";
27 | title: string;
28 | description: string;
29 | action?: string;
30 | }
31 |
32 | export interface NextStep {
33 | action: string;
34 | toolRequired?: string;
35 | description?: string;
36 | priority?: "low" | "medium" | "high";
37 | }
38 |
39 | // Additional types for README health analysis and best practices
40 | // These types prevent compilation errors when health analysis functionality is added
41 | export interface HealthAnalysis {
42 | score: number;
43 | issues: HealthIssue[];
44 | recommendations: string[];
45 | metadata: {
46 | checkDate: string;
47 | version: string;
48 | };
49 | }
50 |
51 | export interface HealthIssue {
52 | type: "critical" | "warning" | "info";
53 | message: string;
54 | section?: string;
55 | line?: number;
56 | }
57 |
58 | export interface ChecklistItem {
59 | id: string;
60 | title: string;
61 | description: string;
62 | completed: boolean;
63 | required: boolean;
64 | category: string;
65 | }
66 |
67 | export interface BestPracticesReport {
68 | items: ChecklistItem[];
69 | score: number;
70 | categories: {
71 | [category: string]: {
72 | total: number;
73 | completed: number;
74 | score: number;
75 | };
76 | };
77 | recommendations: string[];
78 | }
79 |
80 | // MCP content format wrapper for backward compatibility
81 | export interface MCPContentWrapper {
82 | content: Array<{
83 | type: "text";
84 | text: string;
85 | }>;
86 | isError?: boolean;
87 | }
88 |
89 | // Helper to convert MCPToolResponse to MCP format
90 | export function formatMCPResponse<T>(
91 | response: MCPToolResponse<T>,
92 | options?: { fullResponse?: boolean },
93 | ): MCPContentWrapper {
94 | const content: Array<{ type: "text"; text: string }> = [];
95 |
96 | // For backward compatibility: by default, use rich formatting with metadata, recommendations, etc.
97 | // If fullResponse is true (Phase 3 tools), include the full response object as JSON
98 | if (options?.fullResponse) {
99 | content.push({
100 | type: "text",
101 | text: JSON.stringify(response, null, 2),
102 | });
103 | } else {
104 | // Legacy format with rich formatting (original behavior)
105 | if (response.success) {
106 | // Main data response
107 | if (response.data) {
108 | content.push({
109 | type: "text",
110 | text: JSON.stringify(response.data, null, 2),
111 | });
112 | } else {
113 | content.push({
114 | type: "text",
115 | text: "Operation completed successfully",
116 | });
117 | }
118 |
119 | // Metadata section
120 | content.push({
121 | type: "text",
122 | text: `\nExecution completed in ${response.metadata.executionTime}ms at ${response.metadata.timestamp}`,
123 | });
124 |
125 | // Recommendations section with emoji icons
126 | if (response.recommendations?.length) {
127 | content.push({
128 | type: "text",
129 | text:
130 | "\nRecommendations:\n" +
131 | response.recommendations
132 | .map(
133 | (r) =>
134 | `${getRecommendationIcon(r.type)} ${r.title}: ${
135 | r.description
136 | }`,
137 | )
138 | .join("\n"),
139 | });
140 | }
141 |
142 | // Next steps section with arrow symbols
143 | if (response.nextSteps?.length) {
144 | content.push({
145 | type: "text",
146 | text:
147 | "\nNext Steps:\n" +
148 | response.nextSteps
149 | .map((s) => {
150 | let stepText = `→ ${s.action}`;
151 | if (s.toolRequired) {
152 | stepText += ` (use ${s.toolRequired}`;
153 | if (s.description) {
154 | stepText += `: ${s.description}`;
155 | }
156 | stepText += ")";
157 | } else if (s.description) {
158 | stepText += `: ${s.description}`;
159 | }
160 | return stepText;
161 | })
162 | .join("\n"),
163 | });
164 | }
165 | } else if (response.error) {
166 | // Error responses need to be JSON for programmatic error handling
167 | content.push({
168 | type: "text",
169 | text: JSON.stringify(response, null, 2),
170 | });
171 | }
172 | }
173 |
174 | return {
175 | content,
176 | isError: !response.success,
177 | };
178 | }
179 |
180 | function getRecommendationIcon(type: Recommendation["type"]): string {
181 | switch (type) {
182 | case "info":
183 | return "ℹ️";
184 | case "warning":
185 | return "⚠️";
186 | case "critical":
187 | return "🔴";
188 | default:
189 | return "•";
190 | }
191 | }
192 |
193 | // Utility functions for type conversions to prevent common type errors
194 | export function convertBestPracticesReportToChecklistItems(
195 | report: BestPracticesReport,
196 | ): ChecklistItem[] {
197 | return report.items;
198 | }
199 |
200 | export function generateHealthRecommendations(
201 | analysis: HealthAnalysis,
202 | ): string[] {
203 | return analysis.recommendations;
204 | }
205 |
```
--------------------------------------------------------------------------------
/tests/memory/temporal-analysis.test.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Basic unit tests for Temporal Memory Analysis System
3 | * Tests core temporal analysis functionality
4 | * Part of Issue #55 - Advanced Memory Components Unit Tests
5 | */
6 |
7 | import { promises as fs } from "fs";
8 | import path from "path";
9 | import os from "os";
10 | import { MemoryManager } from "../../src/memory/manager.js";
11 | import {
12 | TemporalMemoryAnalysis,
13 | TimeWindow,
14 | TemporalPattern,
15 | TemporalMetrics,
16 | TemporalQuery,
17 | TemporalInsight,
18 | } from "../../src/memory/temporal-analysis.js";
19 |
20 | describe("TemporalMemoryAnalysis", () => {
21 | let tempDir: string;
22 | let memoryManager: MemoryManager;
23 | let temporalAnalysis: TemporalMemoryAnalysis;
24 |
25 | beforeEach(async () => {
26 | // Create unique temp directory for each test
27 | tempDir = path.join(
28 | os.tmpdir(),
29 | `temporal-analysis-test-${Date.now()}-${Math.random()
30 | .toString(36)
31 | .substr(2, 9)}`,
32 | );
33 | await fs.mkdir(tempDir, { recursive: true });
34 |
35 | memoryManager = new MemoryManager(tempDir);
36 | await memoryManager.initialize();
37 |
38 | // Create required dependencies for TemporalMemoryAnalysis
39 | const storage = (memoryManager as any).storage;
40 | const learningSystem = {
41 | learn: jest.fn(),
42 | predict: jest.fn(),
43 | adaptModel: jest.fn(),
44 | };
45 | const knowledgeGraph = {
46 | addNode: jest.fn(),
47 | addEdge: jest.fn(),
48 | findPaths: jest.fn(),
49 | };
50 |
51 | temporalAnalysis = new TemporalMemoryAnalysis(
52 | storage,
53 | memoryManager,
54 | learningSystem as any,
55 | knowledgeGraph as any,
56 | );
57 | });
58 |
59 | afterEach(async () => {
60 | // Cleanup temp directory
61 | try {
62 | await fs.rm(tempDir, { recursive: true, force: true });
63 | } catch (error) {
64 | // Ignore cleanup errors
65 | }
66 | });
67 |
68 | describe("Temporal Analysis Initialization", () => {
69 | test("should create temporal analysis system instance", () => {
70 | expect(temporalAnalysis).toBeDefined();
71 | expect(temporalAnalysis).toBeInstanceOf(TemporalMemoryAnalysis);
72 | });
73 |
74 | test("should analyze temporal patterns", async () => {
75 | // Add some test memories
76 | await memoryManager.remember("analysis", {
77 | projectPath: "/test/project",
78 | timestamp: new Date().toISOString(),
79 | });
80 |
81 | // Test temporal pattern analysis
82 | const patterns = await temporalAnalysis.analyzeTemporalPatterns();
83 | expect(Array.isArray(patterns)).toBe(true);
84 | });
85 |
86 | test("should get temporal metrics", async () => {
87 | // Add test memory
88 | await memoryManager.remember("deployment", {
89 | status: "success",
90 | timestamp: new Date().toISOString(),
91 | });
92 |
93 | // Test temporal metrics
94 | const metrics = await temporalAnalysis.getTemporalMetrics();
95 | expect(metrics).toBeDefined();
96 | expect(typeof metrics.activityLevel).toBe("number");
97 | });
98 |
99 | test("should predict future activity", async () => {
100 | // Add test memories
101 | await memoryManager.remember("analysis", { test: "data1" });
102 | await memoryManager.remember("analysis", { test: "data2" });
103 |
104 | // Test prediction
105 | const prediction = await temporalAnalysis.predictFutureActivity();
106 | expect(prediction).toBeDefined();
107 | expect(typeof prediction.nextActivity.confidence).toBe("number");
108 | });
109 |
110 | test("should get temporal insights", async () => {
111 | // Add test memory
112 | await memoryManager.remember("recommendation", {
113 | type: "ssg",
114 | recommendation: "use-hugo",
115 | });
116 |
117 | // Test insights
118 | const insights = await temporalAnalysis.getTemporalInsights();
119 | expect(Array.isArray(insights)).toBe(true);
120 | });
121 | });
122 |
123 | describe("Temporal Query Support", () => {
124 | test("should handle temporal queries with parameters", async () => {
125 | // Add test data
126 | await memoryManager.remember("analysis", { framework: "react" });
127 | await memoryManager.remember("deployment", { status: "success" });
128 |
129 | const query: TemporalQuery = {
130 | granularity: "day",
131 | aggregation: "count",
132 | filters: { types: ["analysis"] },
133 | };
134 |
135 | const patterns = await temporalAnalysis.analyzeTemporalPatterns(query);
136 | expect(Array.isArray(patterns)).toBe(true);
137 |
138 | const metrics = await temporalAnalysis.getTemporalMetrics(query);
139 | expect(metrics).toBeDefined();
140 | });
141 | });
142 |
143 | describe("Error Handling", () => {
144 | test("should handle empty data gracefully", async () => {
145 | // Test with no memories
146 | const patterns = await temporalAnalysis.analyzeTemporalPatterns();
147 | expect(Array.isArray(patterns)).toBe(true);
148 | expect(patterns.length).toBe(0);
149 |
150 | const metrics = await temporalAnalysis.getTemporalMetrics();
151 | expect(metrics).toBeDefined();
152 | expect(metrics.activityLevel).toBe(0);
153 | });
154 |
155 | test("should handle invalid query parameters", async () => {
156 | const invalidQuery = {
157 | granularity: "invalid" as any,
158 | aggregation: "count" as any,
159 | };
160 |
161 | // Should not throw but handle gracefully
162 | await expect(
163 | temporalAnalysis.analyzeTemporalPatterns(invalidQuery),
164 | ).resolves.toBeDefined();
165 | });
166 | });
167 | });
168 |
```
--------------------------------------------------------------------------------
/setup-precommit.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | # Setup script for DocuMCP pre-commit hooks
4 | # Based on: https://gist.githubusercontent.com/tosin2013/15b1d7bffafe17dff6374edf1530469b/raw/324c60dffb93ddd62c007effc1dbf3918c6483e8/install-precommit-tools.sh
5 |
6 | set -e
7 |
8 | echo "🚀 Setting up DocuMCP pre-commit hooks..."
9 |
10 | # Colors for output
11 | RED='\033[0;31m'
12 | GREEN='\033[0;32m'
13 | YELLOW='\033[1;33m'
14 | BLUE='\033[0;34m'
15 | NC='\033[0m' # No Color
16 |
17 | # Function to print colored output
18 | print_status() {
19 | echo -e "${BLUE}[INFO]${NC} $1"
20 | }
21 |
22 | print_success() {
23 | echo -e "${GREEN}[SUCCESS]${NC} $1"
24 | }
25 |
26 | print_warning() {
27 | echo -e "${YELLOW}[WARNING]${NC} $1"
28 | }
29 |
30 | print_error() {
31 | echo -e "${RED}[ERROR]${NC} $1"
32 | }
33 |
34 | # Check if we're in a git repository
35 | if ! git rev-parse --git-dir > /dev/null 2>&1; then
36 | print_error "This is not a git repository!"
37 | exit 1
38 | fi
39 |
40 | # Check if Node.js and npm are installed
41 | if ! command -v node &> /dev/null; then
42 | print_error "Node.js is not installed. Please install Node.js 20+ first."
43 | exit 1
44 | fi
45 |
46 | if ! command -v npm &> /dev/null; then
47 | print_error "npm is not installed. Please install npm first."
48 | exit 1
49 | fi
50 |
51 | # Check Node.js version
52 | NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
53 | if [ "$NODE_VERSION" -lt 20 ]; then
54 | print_error "Node.js version 20 or higher is required. Current version: $(node --version)"
55 | exit 1
56 | fi
57 |
58 | print_status "Node.js version: $(node --version) ✓"
59 |
60 | # Install npm dependencies if needed
61 | if [ ! -d "node_modules" ]; then
62 | print_status "Installing npm dependencies..."
63 | npm install
64 | else
65 | print_status "npm dependencies already installed ✓"
66 | fi
67 |
68 | # Install pre-commit
69 | print_status "Installing pre-commit..."
70 |
71 | if command -v brew &> /dev/null; then
72 | # macOS with Homebrew
73 | if ! command -v pre-commit &> /dev/null; then
74 | print_status "Installing pre-commit via Homebrew..."
75 | brew install pre-commit
76 | else
77 | print_status "pre-commit already installed ✓"
78 | fi
79 | elif command -v pip3 &> /dev/null; then
80 | # Linux/WSL with pip3
81 | if ! command -v pre-commit &> /dev/null; then
82 | print_status "Installing pre-commit via pip3..."
83 | pip3 install --user pre-commit
84 | # Add to PATH if needed
85 | if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
86 | print_warning "Adding ~/.local/bin to PATH"
87 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
88 | export PATH="$HOME/.local/bin:$PATH"
89 | fi
90 | else
91 | print_status "pre-commit already installed ✓"
92 | fi
93 | elif command -v pipx &> /dev/null; then
94 | # Alternative installation via pipx
95 | if ! command -v pre-commit &> /dev/null; then
96 | print_status "Installing pre-commit via pipx..."
97 | pipx install pre-commit
98 | else
99 | print_status "pre-commit already installed ✓"
100 | fi
101 | else
102 | print_error "Cannot install pre-commit. Please install either:"
103 | print_error " - Homebrew (macOS): brew install pre-commit"
104 | print_error " - pip3: pip3 install --user pre-commit"
105 | print_error " - pipx: pipx install pre-commit"
106 | exit 1
107 | fi
108 |
109 | # Verify pre-commit installation
110 | if ! command -v pre-commit &> /dev/null; then
111 | print_error "pre-commit installation failed!"
112 | exit 1
113 | fi
114 |
115 | print_success "pre-commit installed: $(pre-commit --version)"
116 |
117 | # Install pre-commit hooks
118 | print_status "Installing pre-commit hooks..."
119 | pre-commit install-hooks
120 |
121 | # Update Husky pre-commit hook to use pre-commit
122 | if [ -f ".husky/pre-commit" ]; then
123 | if ! grep -q "pre-commit run" .husky/pre-commit; then
124 | print_status "Updating Husky pre-commit hook..."
125 | echo "pre-commit run --all-files" > .husky/pre-commit
126 | chmod +x .husky/pre-commit
127 | else
128 | print_status "Husky pre-commit hook already configured ✓"
129 | fi
130 | else
131 | print_warning "Husky pre-commit hook not found. Creating..."
132 | mkdir -p .husky
133 | echo "pre-commit run --all-files" > .husky/pre-commit
134 | chmod +x .husky/pre-commit
135 | fi
136 |
137 | # Test the setup
138 | print_status "Testing pre-commit setup..."
139 | if pre-commit run --all-files > /dev/null 2>&1; then
140 | print_success "Pre-commit hooks are working!"
141 | else
142 | print_warning "Pre-commit hooks encountered some issues (this is normal for first run)"
143 | print_status "Running pre-commit with output for diagnosis..."
144 | pre-commit run --all-files || true
145 | fi
146 |
147 | print_success "🎉 Pre-commit setup complete!"
148 | echo
149 | echo "📋 Summary of installed hooks:"
150 | echo " ✅ File integrity checks (trailing whitespace, end-of-file, etc.)"
151 | echo " ✅ YAML/JSON validation"
152 | echo " ✅ Security checks (private keys, large files)"
153 | echo " ✅ ESLint code linting with auto-fix"
154 | echo " ✅ Prettier code formatting"
155 | echo " ✅ TypeScript type checking"
156 | echo " ✅ npm security audit"
157 | echo " ✅ Core Jest tests (stable tests only)"
158 | echo " ✅ Documentation link checking"
159 | echo " ✅ Package.json validation"
160 | echo " ✅ Build verification"
161 | echo
162 | echo "🔧 Usage:"
163 | echo " • Hooks run automatically on every commit"
164 | echo " • Run manually: pre-commit run --all-files"
165 | echo " • Update hooks: pre-commit autoupdate"
166 | echo " • Skip hooks (emergency): git commit --no-verify"
167 | echo
168 | echo "📖 For team members:"
169 | echo " • New team members should run: ./setup-precommit.sh"
170 | echo " • All hooks are configured to match existing npm scripts"
171 | echo " • Hooks focus on code quality without blocking development"
172 | echo
173 | print_success "Happy coding! 🚀"
174 |
```
--------------------------------------------------------------------------------
/docs/how-to/performance-optimization.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.953Z"
4 | last_validated: "2025-11-20T00:46:21.953Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # How to Optimize Documentation Deployment Performance
10 |
11 | This guide shows you how to optimize your DocuMCP deployment process for faster builds and better deployment success rates.
12 |
13 | ## Quick Setup
14 |
15 | ```bash
16 | # Analyze deployment performance:
17 | "analyze my deployment performance and provide optimization recommendations"
18 | ```
19 |
20 | ## Deployment Performance Overview
21 |
22 | DocuMCP tracks deployment performance metrics to help you optimize your documentation build process:
23 |
24 | ### Key Metrics
25 |
26 | - **Build Time**: Time taken for documentation generation
27 | - **Deployment Success Rate**: Percentage of successful deployments
28 | - **SSG Performance**: Static site generator efficiency comparison
29 | - **Error Recovery**: Time to resolve deployment failures
30 |
31 | ### Performance Benefits
32 |
33 | - **Faster Deployments**: Reduced time from commit to live site
34 | - **Higher Success Rates**: More reliable deployment pipeline
35 | - **Better Developer Experience**: Quicker feedback cycles
36 | - **Reduced Resource Usage**: Optimized build processes
37 |
38 | ## Setup Methods
39 |
40 | ### Method 1: Deployment Performance Analysis
41 |
42 | ```bash
43 | # Analyze deployment performance:
44 | "analyze my deployment performance and provide optimization recommendations"
45 | ```
46 |
47 | This will:
48 |
49 | 1. Analyze current deployment metrics
50 | 2. Compare SSG build times
51 | 3. Identify deployment bottlenecks
52 | 4. Provide optimization recommendations
53 | 5. Track performance improvements
54 |
55 | ### Method 2: SSG Performance Comparison
56 |
57 | #### Step 1: Build Time Analysis
58 |
59 | ```bash
60 | # Analyze build performance:
61 | "compare build times across different static site generators"
62 | ```
63 |
64 | #### Step 2: Success Rate Optimization
65 |
66 | ```bash
67 | # Optimize deployment success:
68 | "analyze deployment failures and suggest improvements"
69 | ```
70 |
71 | #### Step 3: Performance Monitoring
72 |
73 | ```bash
74 | # Monitor deployment performance:
75 | "track my deployment performance over time"
76 | ```
77 |
78 | ## Deployment Optimization Techniques
79 |
80 | ### SSG Selection Optimization
81 |
82 | ```bash
83 | # Analyze SSG performance:
84 | "compare static site generator build times and success rates"
85 | ```
86 |
87 | #### SSG Performance Factors
88 |
89 | - **Build Speed**: Time to generate documentation
90 | - **Success Rate**: Reliability of builds
91 | - **Resource Usage**: Memory and CPU requirements
92 | - **Feature Support**: Compatibility with documentation needs
93 |
94 | ### Build Configuration Optimization
95 |
96 | ```typescript
97 | // Optimize build configuration for faster deployments
98 | const buildConfig = {
99 | // Use faster package managers
100 | packageManager: "pnpm", // or "yarn" for faster installs
101 |
102 | // Optimize Node.js version
103 | nodeVersion: "20", // Latest LTS for better performance
104 |
105 | // Configure build caching
106 | cache: {
107 | enabled: true,
108 | strategy: "aggressive",
109 | },
110 | };
111 | ```
112 |
113 | ### Deployment Pipeline Optimization
114 |
115 | ```bash
116 | # Optimize deployment pipeline:
117 | "analyze my deployment pipeline and suggest performance improvements"
118 | ```
119 |
120 | #### Pipeline Best Practices
121 |
122 | - **Parallel Processing**: Run independent tasks concurrently
123 | - **Build Caching**: Cache dependencies and build artifacts
124 | - **Incremental Builds**: Only rebuild changed content
125 | - **Resource Allocation**: Optimize memory and CPU usage
126 |
127 | ## Troubleshooting
128 |
129 | ### Common Issues
130 |
131 | **Problem**: Slow deployment builds
132 | **Solution**: Analyze SSG performance and switch to faster alternatives
133 |
134 | **Problem**: Frequent deployment failures
135 | **Solution**: Review error patterns and optimize build configurations
136 |
137 | **Problem**: Inconsistent build times
138 | **Solution**: Enable build caching and optimize dependencies
139 |
140 | **Problem**: Resource exhaustion during builds
141 | **Solution**: Optimize memory usage and build parallelization
142 |
143 | ### Performance Debugging
144 |
145 | ```bash
146 | # Debug deployment performance issues:
147 | "analyze my deployment bottlenecks and suggest optimizations"
148 | ```
149 |
150 | ## Best Practices
151 |
152 | ### Deployment Performance Guidelines
153 |
154 | 1. **Choose Fast SSGs**: Use performance data to select optimal static site generators
155 | 2. **Enable Caching**: Implement build caching for faster subsequent deployments
156 | 3. **Optimize Dependencies**: Keep dependencies minimal and up-to-date
157 | 4. **Monitor Build Times**: Track deployment performance over time
158 | 5. **Use Analytics**: Leverage deployment analytics for optimization decisions
159 |
160 | ### Build Optimization Strategies
161 |
162 | 1. **Incremental Builds**: Only rebuild changed content when possible
163 | 2. **Parallel Processing**: Run independent build tasks concurrently
164 | 3. **Resource Management**: Optimize memory and CPU usage during builds
165 | 4. **Dependency Caching**: Cache node_modules and build artifacts
166 | 5. **Build Environment**: Use optimized build environments and Node.js versions
167 |
168 | ## Deployment Analytics Tools
169 |
170 | ### Built-in DocuMCP Analytics
171 |
172 | - **Build time tracking**: Monitor deployment speed over time
173 | - **Success rate analysis**: Track deployment reliability
174 | - **SSG performance comparison**: Compare static site generator efficiency
175 | - **Failure pattern analysis**: Identify common deployment issues
176 |
177 | ### MCP Tools Available
178 |
179 | - `analyze_deployments`: Get comprehensive deployment performance analytics
180 | - `deploy_pages`: Track deployment attempts and build times
181 | - `recommend_ssg`: Get performance-based SSG recommendations
182 |
183 | ## Next Steps
184 |
185 | - [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
186 | - [Analytics Setup](analytics-setup.md)
187 | - [Site Monitoring](site-monitoring.md)
188 | - [Troubleshooting](troubleshooting.md)
189 |
```
--------------------------------------------------------------------------------
/docs/api/modules.html:
--------------------------------------------------------------------------------
```html
1 | <!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>
2 |
```
--------------------------------------------------------------------------------
/docs/research/domain-3-ssg-recommendation/ssg-performance-analysis.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.966Z"
4 | last_validated: "2025-11-20T00:46:21.966Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | ---
8 |
9 | # Static Site Generator Performance Analysis
10 |
11 | **Research Date**: 2025-01-14
12 | **Domain**: SSG Recommendation Engine
13 | **Status**: Completed
14 |
15 | ## Research Overview
16 |
17 | Comprehensive analysis of static site generator performance characteristics, build times, and deployment considerations for DocuMCP recommendation engine.
18 |
19 | ## Key Research Findings
20 |
21 | ### Build Performance Comparison
22 |
23 | Based on CSS-Tricks comprehensive benchmarking study:
24 |
25 | | SSG | Language | Small Sites (1-1024 files) | Large Sites (1K-64K files) | Key Characteristics |
26 | | -------------- | -------- | --------------------------------- | ------------------------------- | ------------------------------- |
27 | | **Hugo** | Go | ~250x faster than Gatsby | ~40x faster than Gatsby | Fastest across all scales |
28 | | **Jekyll** | Ruby | Competitive with Eleventy | Slower scaling, Ruby bottleneck | Good for small-medium sites |
29 | | **Eleventy** | Node.js | Fast, lightweight | Good scaling | Excellent developer experience |
30 | | **Gatsby** | React | Slower startup (webpack overhead) | Improves relatively at scale | Rich features, plugin ecosystem |
31 | | **Next.js** | React | Framework overhead | Good with optimization | Hybrid capabilities |
32 | | **Docusaurus** | React | Moderate performance | Documentation optimized | Purpose-built for docs |
33 |
34 | ### Performance Characteristics Analysis
35 |
36 | #### **Tier 1: Speed Champions (Hugo)**
37 |
38 | - **Build Time**: Sub-second for small sites, seconds for large sites
39 | - **Scaling**: Linear performance, excellent for content-heavy sites
40 | - **Trade-offs**: Limited plugin ecosystem, steeper learning curve
41 |
42 | #### **Tier 2: Balanced Performance (Jekyll, Eleventy)**
43 |
44 | - **Build Time**: Fast for small sites, moderate scaling
45 | - **Scaling**: Jekyll hits Ruby performance ceiling, Eleventy scales better
46 | - **Trade-offs**: Good balance of features and performance
47 |
48 | #### **Tier 3: Feature-Rich (Gatsby, Next.js, Docusaurus)**
49 |
50 | - **Build Time**: Significant webpack/framework overhead
51 | - **Scaling**: Performance gap narrows at scale due to optimizations
52 | - **Trade-offs**: Rich ecosystems, modern features, slower builds
53 |
54 | ### Real-World Performance Implications
55 |
56 | #### **For DocuMCP Recommendation Logic:**
57 |
58 | 1. **Small Projects** (< 100 pages):
59 |
60 | - All SSGs perform adequately
61 | - Developer experience becomes primary factor
62 | - Hugo still 250x faster than Gatsby for simple sites
63 |
64 | 2. **Medium Projects** (100-1000 pages):
65 |
66 | - Performance differences become noticeable
67 | - Hugo maintains significant advantage
68 | - Jekyll starts showing Ruby limitations
69 |
70 | 3. **Large Projects** (1000+ pages):
71 | - Hugo remains fastest but gap narrows
72 | - Framework-based SSGs benefit from optimizations
73 | - Build time becomes CI/CD bottleneck consideration
74 |
75 | ### Deployment and CI/CD Considerations
76 |
77 | #### **GitHub Actions Build Time Impact**
78 |
79 | - **Free Plan Limitations**: 2000 minutes/month
80 | - **Cost Implications**: Slow builds consume more CI time
81 | - **Real Example**: Gatsby site taking 15 minutes vs Hugo taking 30 seconds
82 |
83 | #### **Content Editor Experience**
84 |
85 | - **Preview Generation**: Fast builds enable quick content previews
86 | - **Development Workflow**: Build speed affects local development experience
87 | - **Incremental Builds**: Framework support varies significantly
88 |
89 | ### Recommendation Engine Criteria
90 |
91 | Based on research findings, DocuMCP should weight these factors:
92 |
93 | 1. **Project Scale Weight**:
94 |
95 | - Small projects: 40% performance, 60% features/DX
96 | - Medium projects: 60% performance, 40% features/DX
97 | - Large projects: 80% performance, 20% features/DX
98 |
99 | 2. **Team Context Multipliers**:
100 |
101 | - Technical team: Favor performance (Hugo/Eleventy)
102 | - Non-technical content creators: Favor ease-of-use (Jekyll/Docusaurus)
103 | - Mixed teams: Balanced approach (Next.js/Gatsby)
104 |
105 | 3. **Use Case Optimization**:
106 | - **Documentation**: Docusaurus > MkDocs > Hugo
107 | - **Marketing Sites**: Next.js > Gatsby > Hugo
108 | - **Blogs**: Jekyll > Eleventy > Hugo
109 | - **Large Content Sites**: Hugo > Eleventy > Others
110 |
111 | ## Implementation Recommendations for DocuMCP
112 |
113 | ### Algorithm Design
114 |
115 | ```typescript
116 | // Performance scoring algorithm
117 | const calculatePerformanceScore = (projectMetrics: ProjectMetrics) => {
118 | const { pageCount, teamSize, techLevel, updateFrequency } = projectMetrics;
119 |
120 | // Scale-based performance weighting
121 | const performanceWeight =
122 | pageCount > 1000 ? 0.8 : pageCount > 100 ? 0.6 : 0.4;
123 |
124 | // SSG-specific performance scores (0-100)
125 | const performanceScores = {
126 | hugo: 100,
127 | eleventy: 85,
128 | jekyll: pageCount > 500 ? 60 : 80,
129 | nextjs: 70,
130 | gatsby: pageCount > 1000 ? 65 : 45,
131 | docusaurus: 75,
132 | };
133 |
134 | return performanceScores;
135 | };
136 | ```
137 |
138 | ### Research Validation
139 |
140 | - ✅ Performance benchmarks analyzed from multiple sources
141 | - ✅ Real-world implications documented
142 | - ✅ Recommendation criteria established
143 | - ⚠️ Needs validation: Edge case performance scenarios
144 | - ⚠️ Needs testing: Algorithm implementation with real project data
145 |
146 | ## Sources & References
147 |
148 | 1. CSS-Tricks Comprehensive SSG Build Time Analysis
149 | 2. Jamstack.org Performance Surveys
150 | 3. GitHub Actions CI/CD Cost Analysis
151 | 4. Community Performance Reports (Hugo, Gatsby, Next.js)
152 |
```
--------------------------------------------------------------------------------
/src/scripts/benchmark.ts:
--------------------------------------------------------------------------------
```typescript
1 | #!/usr/bin/env node
2 | // Performance benchmark CLI script per PERF-001 rules
3 | import { promises as fs } from "fs";
4 | import path from "path";
5 | import { createBenchmarker } from "../benchmarks/performance.js";
6 |
7 | interface BenchmarkConfig {
8 | testRepos: Array<{
9 | path: string;
10 | name: string;
11 | expectedSize?: "small" | "medium" | "large";
12 | }>;
13 | outputDir?: string;
14 | verbose?: boolean;
15 | }
16 |
17 | async function main() {
18 | const args = process.argv.slice(2);
19 | const command = args[0] || "help";
20 |
21 | switch (command) {
22 | case "run":
23 | await runBenchmarks(args.slice(1));
24 | break;
25 | case "current":
26 | await benchmarkCurrentRepo();
27 | break;
28 | case "create-config":
29 | await createDefaultConfig();
30 | break;
31 | case "help":
32 | default:
33 | printHelp();
34 | break;
35 | }
36 | }
37 |
38 | async function runBenchmarks(args: string[]) {
39 | const configPath = args[0] || "./benchmark-config.json";
40 |
41 | try {
42 | const configContent = await fs.readFile(configPath, "utf-8");
43 | const config: BenchmarkConfig = JSON.parse(configContent);
44 |
45 | console.log("🎯 Performance Benchmarking System (PERF-001 Compliance)");
46 | console.log("Target Performance:");
47 | console.log(" • Small repos (<100 files): <1 second");
48 | console.log(" • Medium repos (100-1000 files): <10 seconds");
49 | console.log(" • Large repos (1000+ files): <60 seconds\\n");
50 |
51 | const benchmarker = createBenchmarker();
52 | const suite = await benchmarker.runBenchmarkSuite(config.testRepos);
53 |
54 | // Print detailed report
55 | benchmarker.printDetailedReport(suite);
56 |
57 | // Export results if output directory specified
58 | if (config.outputDir) {
59 | await fs.mkdir(config.outputDir, { recursive: true });
60 | const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
61 | const outputPath = path.join(
62 | config.outputDir,
63 | `benchmark-${timestamp}.json`,
64 | );
65 |
66 | await benchmarker.exportResults(suite, outputPath);
67 | console.log(`\\n📄 Results exported to: ${outputPath}`);
68 | }
69 |
70 | // Exit with appropriate code
71 | process.exit(suite.overallPassed ? 0 : 1);
72 | } catch (error) {
73 | console.error("❌ Benchmark failed:", error);
74 | console.error(
75 | '\\nTry running "npm run benchmark:create-config" to create a default configuration.',
76 | );
77 | process.exit(1);
78 | }
79 | }
80 |
81 | async function benchmarkCurrentRepo() {
82 | console.log("🎯 Benchmarking Current Repository");
83 | console.log("=".repeat(40));
84 |
85 | const currentRepo = process.cwd();
86 | const repoName = path.basename(currentRepo);
87 |
88 | const benchmarker = createBenchmarker();
89 |
90 | try {
91 | console.log(`📊 Analyzing: ${repoName} at ${currentRepo}\\n`);
92 |
93 | const result = await benchmarker.benchmarkRepository(
94 | currentRepo,
95 | "standard",
96 | );
97 |
98 | // Generate single-repo suite
99 | const suite = benchmarker.generateSuite(`Current Repository: ${repoName}`, [
100 | result,
101 | ]);
102 |
103 | // Print results
104 | benchmarker.printDetailedReport(suite);
105 |
106 | // Export to current directory
107 | const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
108 | const outputPath = `./benchmark-current-${timestamp}.json`;
109 | await benchmarker.exportResults(suite, outputPath);
110 |
111 | console.log(`\\n📄 Results saved to: ${outputPath}`);
112 |
113 | process.exit(suite.overallPassed ? 0 : 1);
114 | } catch (error) {
115 | console.error("❌ Benchmark failed:", error);
116 | process.exit(1);
117 | }
118 | }
119 |
120 | async function createDefaultConfig() {
121 | const defaultConfig: BenchmarkConfig = {
122 | testRepos: [
123 | {
124 | path: ".",
125 | name: "Current Repository",
126 | expectedSize: "small",
127 | },
128 | // Add more test repositories here
129 | // {
130 | // path: "/path/to/medium/repo",
131 | // name: "Medium Test Repo",
132 | // expectedSize: "medium"
133 | // },
134 | // {
135 | // path: "/path/to/large/repo",
136 | // name: "Large Test Repo",
137 | // expectedSize: "large"
138 | // }
139 | ],
140 | outputDir: "./benchmark-results",
141 | verbose: true,
142 | };
143 |
144 | const configPath = "./benchmark-config.json";
145 | await fs.writeFile(configPath, JSON.stringify(defaultConfig, null, 2));
146 |
147 | console.log("✅ Created default benchmark configuration:");
148 | console.log(` ${configPath}`);
149 | console.log("");
150 | console.log("📝 Edit this file to add your test repositories, then run:");
151 | console.log(" npm run benchmark:run");
152 | }
153 |
154 | function printHelp() {
155 | console.log("🎯 DocuMCP Performance Benchmarking Tool");
156 | console.log("");
157 | console.log("USAGE:");
158 | console.log(
159 | " npm run benchmark:run [config-file] Run full benchmark suite",
160 | );
161 | console.log(
162 | " npm run benchmark:current Benchmark current repository only",
163 | );
164 | console.log(
165 | " npm run benchmark:create-config Create default configuration",
166 | );
167 | console.log(" npm run benchmark:help Show this help");
168 | console.log("");
169 | console.log("PERFORMANCE TARGETS (PERF-001):");
170 | console.log(" • Small repositories (<100 files): <1 second");
171 | console.log(" • Medium repositories (100-1000 files): <10 seconds");
172 | console.log(" • Large repositories (1000+ files): <60 seconds");
173 | console.log("");
174 | console.log("EXAMPLES:");
175 | console.log(" npm run benchmark:current");
176 | console.log(" npm run benchmark:create-config");
177 | console.log(" npm run benchmark:run ./my-config.json");
178 | }
179 |
180 | // Handle unhandled promise rejections
181 | process.on("unhandledRejection", (error) => {
182 | console.error("❌ Unhandled rejection:", error);
183 | process.exit(1);
184 | });
185 |
186 | main().catch((error) => {
187 | console.error("❌ Script failed:", error);
188 | process.exit(1);
189 | });
190 |
```
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Release
2 |
3 | on:
4 | push:
5 | tags:
6 | - "v*.*.*"
7 | workflow_dispatch:
8 | inputs:
9 | version_type:
10 | description: "Version bump type"
11 | required: true
12 | default: "patch"
13 | type: choice
14 | options:
15 | - patch
16 | - minor
17 | - major
18 |
19 | jobs:
20 | test:
21 | name: Pre-release Tests
22 | runs-on: ubuntu-latest
23 |
24 | steps:
25 | - name: Checkout code
26 | uses: actions/checkout@v4
27 |
28 | - name: Setup Node.js
29 | uses: actions/setup-node@v4
30 | with:
31 | node-version: "20.x"
32 | cache: "npm"
33 |
34 | - name: Install dependencies
35 | run: npm ci
36 |
37 | - name: Run full test suite
38 | run: npm test -- --coverage
39 |
40 | - name: Verify 80% coverage threshold
41 | run: |
42 | coverage=$(npm test -- --coverage --silent | grep "All files" | awk '{print $4}' | sed 's/%//')
43 | if (( $(echo "$coverage < 80" | bc -l) )); then
44 | echo "Coverage $coverage% is below 80% threshold"
45 | exit 1
46 | fi
47 | echo "Coverage $coverage% meets requirement"
48 |
49 | - name: Performance benchmarks
50 | run: npm run test:performance
51 |
52 | - name: Build verification
53 | run: npm run build
54 |
55 | release:
56 | name: Create Release
57 | runs-on: ubuntu-latest
58 | needs: test
59 | permissions:
60 | contents: write
61 | packages: write
62 |
63 | steps:
64 | - name: Checkout code
65 | uses: actions/checkout@v4
66 | with:
67 | fetch-depth: 0
68 |
69 | - name: Setup Node.js
70 | uses: actions/setup-node@v4
71 | with:
72 | node-version: "20.x"
73 | cache: "npm"
74 | registry-url: "https://registry.npmjs.org"
75 |
76 | - name: Verify NPM Token
77 | run: |
78 | if [ -z "$NODE_AUTH_TOKEN" ]; then
79 | echo "Error: NODE_AUTH_TOKEN is not set"
80 | echo "Please configure NPM_TOKEN in repository secrets"
81 | exit 1
82 | fi
83 | echo "NPM token is configured"
84 |
85 | - name: Install dependencies
86 | run: npm ci
87 |
88 | - name: Build project
89 | run: npm run build
90 |
91 | - name: Generate changelog and release
92 | id: release
93 | run: |
94 | git config --local user.email "[email protected]"
95 | git config --local user.name "GitHub Action"
96 |
97 | if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
98 | printf "Manual release triggered with version type: %s\n" "${{ github.event.inputs.version_type }}"
99 | npm run "release:${{ github.event.inputs.version_type }}"
100 |
101 | # Get the new version and changelog
102 | NEW_VERSION=$(node -p "require('./package.json').version")
103 | printf "new_version=v%s\n" "$NEW_VERSION" >> "$GITHUB_OUTPUT"
104 |
105 | # Extract changelog for this version
106 | if [ -f "CHANGELOG.md" ]; then
107 | # Get changelog section for current version
108 | CHANGELOG_CONTENT=$(awk "/## \[$NEW_VERSION\]/{flag=1; next} /## \[/{flag=0} flag" CHANGELOG.md || printf "## Changes\n\nAutomated release %s\n" "$NEW_VERSION")
109 | {
110 | echo "changelog_content<<EOF"
111 | printf "%s\n" "$CHANGELOG_CONTENT"
112 | echo "EOF"
113 | } >> "$GITHUB_OUTPUT"
114 | else
115 | printf "changelog_content=Automated release v%s\n" "$NEW_VERSION" >> "$GITHUB_OUTPUT"
116 | fi
117 |
118 | # Push the changes
119 | git push --follow-tags origin main
120 | else
121 | echo "Tag-based release"
122 | tag="${GITHUB_REF#refs/tags/}"
123 | printf "new_version=%s\n" "$tag" >> "$GITHUB_OUTPUT"
124 | printf "changelog_content=Release %s\n" "$tag" >> "$GITHUB_OUTPUT"
125 | fi
126 |
127 | - name: Create GitHub Release
128 | uses: ncipollo/release-action@v1
129 | with:
130 | token: ${{ secrets.GITHUB_TOKEN }}
131 | tag: ${{ steps.release.outputs.new_version }}
132 | name: Release ${{ steps.release.outputs.new_version }}
133 | body: |
134 | ## DocuMCP Release ${{ steps.release.outputs.new_version }}
135 |
136 | ${{ steps.release.outputs.changelog_content }}
137 |
138 | ### Installation
139 | ```bash
140 | npm install -g documcp@${{ steps.release.outputs.new_version }}
141 | ```
142 |
143 | ### System Requirements
144 | - Node.js 20.x or higher
145 | - npm 9.x or higher
146 |
147 | ### Quick Start
148 | ```bash
149 | # Install globally
150 | npm install -g documcp
151 |
152 | # Use with MCP client
153 | documcp analyze-repository --path ./my-project
154 | ```
155 | draft: false
156 | prerelease: false
157 | skipIfReleaseExists: true
158 | makeLatest: true
159 |
160 | - name: Publish to npm
161 | if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
162 | run: |
163 | echo "Publishing to npm..."
164 | npm whoami
165 | npm publish
166 | echo "Successfully published to npm!"
167 | env:
168 | NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
169 |
170 | docs:
171 | name: Deploy Documentation
172 | runs-on: ubuntu-latest
173 | needs: [test, release]
174 | permissions:
175 | pages: write
176 | id-token: write
177 |
178 | steps:
179 | - name: Checkout code
180 | uses: actions/checkout@v4
181 |
182 | - name: Setup Node.js
183 | uses: actions/setup-node@v4
184 | with:
185 | node-version: "20.x"
186 | cache: "npm"
187 |
188 | - name: Install dependencies
189 | run: npm ci
190 |
191 | - name: Generate API documentation
192 | run: npm run docs:generate
193 |
194 | - name: Remove problematic media directory
195 | run: rm -rf docs/api/media
196 |
197 | - name: Install Docusaurus dependencies
198 | run: cd docs && npm ci
199 |
200 | - name: Copy API documentation to build directory
201 | run: |
202 | mkdir -p docs/build/api
203 | cp -r docs/api/* docs/build/api/
204 |
205 | - name: Build Docusaurus site
206 | run: cd docs && npm run build
207 | env:
208 | NODE_ENV: production
209 |
210 | - name: Setup Pages
211 | uses: actions/configure-pages@v4
212 |
213 | - name: Upload to GitHub Pages
214 | uses: actions/upload-pages-artifact@v3
215 | with:
216 | path: ./docs/build
217 |
218 | - name: Deploy to GitHub Pages
219 | id: deployment
220 | uses: actions/deploy-pages@v4
221 |
```