This is page 2 of 33. 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
├── ARCHITECTURAL_CHANGES_SUMMARY.md
├── 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
│ │ ├── adr-0001-mcp-server-architecture.md
│ │ ├── adr-0002-repository-analysis-engine.md
│ │ ├── adr-0003-static-site-generator-recommendation-engine.md
│ │ ├── adr-0004-diataxis-framework-integration.md
│ │ ├── adr-0005-github-pages-deployment-automation.md
│ │ ├── adr-0006-mcp-tools-api-design.md
│ │ ├── adr-0007-mcp-prompts-and-resources-integration.md
│ │ ├── adr-0008-intelligent-content-population-engine.md
│ │ ├── adr-0009-content-accuracy-validation-framework.md
│ │ ├── adr-0010-mcp-resource-pattern-redesign.md
│ │ ├── adr-0011-ce-mcp-compatibility.md
│ │ ├── adr-0012-priority-scoring-system-for-documentation-drift.md
│ │ ├── adr-0013-release-pipeline-and-package-distribution.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
│ ├── CE-MCP-FINDINGS.md
│ ├── 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
│ │ ├── change-watcher.md
│ │ ├── custom-domains.md
│ │ ├── documentation-freshness-tracking.md
│ │ ├── drift-priority-scoring.md
│ │ ├── github-pages-deployment.md
│ │ ├── index.md
│ │ ├── llm-integration.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
├── ISSUE_IMPLEMENTATION_SUMMARY.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
│ │ ├── change-watcher.ts
│ │ ├── check-documentation-links.ts
│ │ ├── cleanup-agent-artifacts.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
│ │ ├── simulate-execution.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
│ │ ├── artifact-detector.ts
│ │ ├── ast-analyzer.ts
│ │ ├── change-watcher.ts
│ │ ├── code-scanner.ts
│ │ ├── content-extractor.ts
│ │ ├── drift-detector.ts
│ │ ├── execution-simulator.ts
│ │ ├── freshness-tracker.ts
│ │ ├── language-parsers-simple.ts
│ │ ├── llm-client.ts
│ │ ├── permission-checker.ts
│ │ ├── semantic-analyzer.ts
│ │ ├── sitemap-generator.ts
│ │ ├── usage-metadata.ts
│ │ └── user-feedback-integration.ts
│ └── workflows
│ └── documentation-workflow.ts
├── test-docs-local.sh
├── tests
│ ├── api
│ │ └── mcp-responses.test.ts
│ ├── benchmarks
│ │ └── performance.test.ts
│ ├── call-graph-builder.test.ts
│ ├── change-watcher-priority.integration.test.ts
│ ├── change-watcher.test.ts
│ ├── edge-cases
│ │ └── error-handling.test.ts
│ ├── execution-simulator.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-documentation-examples.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-documentation-examples.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
│ │ ├── cleanup-agent-artifacts.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
│ ├── artifact-detector.test.ts
│ ├── ast-analyzer.test.ts
│ ├── content-extractor.test.ts
│ ├── drift-detector-diataxis.test.ts
│ ├── drift-detector-priority.test.ts
│ ├── drift-detector.test.ts
│ ├── freshness-tracker.test.ts
│ ├── llm-client.test.ts
│ ├── semantic-analyzer.test.ts
│ ├── sitemap-generator.test.ts
│ ├── usage-metadata.test.ts
│ └── user-feedback-integration.test.ts
├── tsconfig.json
└── typedoc.json
```
# Files
--------------------------------------------------------------------------------
/docs/src/css/custom.css:
--------------------------------------------------------------------------------
```css
1 | /**
2 | * Any CSS included here will be global. The classic template
3 | * bundles Infima by default. Infima is a CSS framework designed to
4 | * work well for content-centric websites.
5 | */
6 |
7 | /* You can override the default Infima variables here. */
8 | :root {
9 | --ifm-color-primary: #2e8555;
10 | --ifm-color-primary-dark: #29784c;
11 | --ifm-color-primary-darker: #277148;
12 | --ifm-color-primary-darkest: #205d3b;
13 | --ifm-color-primary-light: #33925d;
14 | --ifm-color-primary-lighter: #359962;
15 | --ifm-color-primary-lightest: #3cad6e;
16 | --ifm-code-font-size: 95%;
17 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
18 | }
19 |
20 | /* For readability improvements */
21 | .markdown > h2 {
22 | --ifm-h2-font-size: 1.5rem;
23 | }
24 |
25 | .markdown > h3 {
26 | --ifm-h3-font-size: 1.25rem;
27 | }
28 |
29 | /* Custom styling for ADR status badges */
30 | .adr-status {
31 | display: inline-block;
32 | padding: 0.25rem 0.5rem;
33 | border-radius: 0.25rem;
34 | font-size: 0.75rem;
35 | font-weight: bold;
36 | text-transform: uppercase;
37 | margin-left: 0.5rem;
38 | }
39 |
40 | .adr-status--accepted {
41 | background-color: #d1f2eb;
42 | color: #0e5232;
43 | }
44 |
45 | .adr-status--proposed {
46 | background-color: #fef9e7;
47 | color: #7d6608;
48 | }
49 |
50 | .adr-status--deprecated {
51 | background-color: #fadbd8;
52 | color: #78281f;
53 | }
54 |
55 | .adr-status--superseded {
56 | background-color: #e8daef;
57 | color: #512e5f;
58 | }
59 |
60 | /* Custom table styling for ADR index */
61 | .adr-table {
62 | width: 100%;
63 | border-collapse: collapse;
64 | margin: 1rem 0;
65 | }
66 |
67 | .adr-table th,
68 | .adr-table td {
69 | padding: 0.75rem;
70 | text-align: left;
71 | border-bottom: 1px solid var(--ifm-table-border-color);
72 | }
73 |
74 | .adr-table th {
75 | background-color: var(--ifm-table-head-background);
76 | font-weight: bold;
77 | }
78 |
79 | .adr-table tbody tr:hover {
80 | background-color: var(--ifm-table-row-hover-background);
81 | }
82 |
83 | /* Dark theme adjustments */
84 | [data-theme='dark'] {
85 | --ifm-color-primary: #25c2a0;
86 | --ifm-color-primary-dark: #21af90;
87 | --ifm-color-primary-darker: #1fa588;
88 | --ifm-color-primary-darkest: #1a8870;
89 | --ifm-color-primary-light: #29d5b0;
90 | --ifm-color-primary-lighter: #32d8b4;
91 | --ifm-color-primary-lightest: #4fddbf;
92 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
93 | }
94 |
95 | [data-theme='dark'] .adr-status--accepted {
96 | background-color: #0e5232;
97 | color: #d1f2eb;
98 | }
99 |
100 | [data-theme='dark'] .adr-status--proposed {
101 | background-color: #7d6608;
102 | color: #fef9e7;
103 | }
104 |
105 | [data-theme='dark'] .adr-status--deprecated {
106 | background-color: #78281f;
107 | color: #fadbd8;
108 | }
109 |
110 | [data-theme='dark'] .adr-status--superseded {
111 | background-color: #512e5f;
112 | color: #e8daef;
113 | }
114 |
115 | /* Code block improvements */
116 | .prism-code {
117 | font-size: 0.9rem;
118 | }
119 |
120 | /* Table of contents improvements */
121 | .table-of-contents {
122 | font-size: 0.8rem;
123 | }
124 |
125 | .table-of-contents__link {
126 | display: block;
127 | margin: 0.125rem 0;
128 | }
129 |
130 | /* Responsive improvements */
131 | @media (max-width: 768px) {
132 | .adr-table {
133 | font-size: 0.8rem;
134 | }
135 |
136 | .adr-table th,
137 | .adr-table td {
138 | padding: 0.5rem;
139 | }
140 | }
141 |
```
--------------------------------------------------------------------------------
/docs/docusaurus.config.js:
--------------------------------------------------------------------------------
```javascript
1 | // Try to load package.json from parent directory, fallback to local if not found
2 | let packageJson;
3 | try {
4 | packageJson = require("../package.json");
5 | } catch (e) {
6 | // Fallback for CI environments where parent package.json might not be accessible
7 | packageJson = { version: "0.5.0" };
8 | }
9 |
10 | module.exports = {
11 | title: "DocuMCP",
12 | tagline: `Intelligent documentation deployment MCP server v${packageJson.version} with AI-powered repository analysis and Diataxis-compliant content generation`,
13 | url: "https://tosin2013.github.io",
14 | baseUrl: "/documcp/",
15 | onBrokenLinks: "warn",
16 | onBrokenMarkdownLinks: "warn",
17 | favicon: "img/favicon.ico",
18 | organizationName: "tosin2013",
19 | projectName: "documcp",
20 | staticDirectories: ["api"],
21 |
22 | presets: [
23 | [
24 | "classic",
25 | {
26 | docs: {
27 | sidebarPath: require.resolve("./sidebars.js"),
28 | editUrl: "https://github.com/tosin2013/documcp/tree/main/docs/",
29 | routeBasePath: "/",
30 | path: ".",
31 | exclude: ["**/node_modules/**", "**/.*", "**/*.{js,jsx,ts,tsx}"],
32 | },
33 | blog: false,
34 | theme: {
35 | customCss: require.resolve("./src/css/custom.css"),
36 | },
37 | },
38 | ],
39 | ],
40 |
41 | themeConfig: {
42 | navbar: {
43 | title: "DocuMCP",
44 | items: [
45 | {
46 | type: "doc",
47 | docId: "index",
48 | position: "left",
49 | label: "Documentation",
50 | },
51 | {
52 | href: "/api/",
53 | position: "left",
54 | label: "API Reference",
55 | },
56 | {
57 | href: "https://github.com/tosin2013/documcp",
58 | label: "GitHub",
59 | position: "right",
60 | },
61 | ],
62 | },
63 | footer: {
64 | style: "dark",
65 | links: [
66 | {
67 | title: "Documentation",
68 | items: [
69 | {
70 | label: "Getting Started",
71 | to: "/tutorials/getting-started",
72 | },
73 | {
74 | label: "API Reference",
75 | to: "/api/",
76 | },
77 | {
78 | label: "Architecture",
79 | to: "/adrs/",
80 | },
81 | ],
82 | },
83 | {
84 | title: "Community",
85 | items: [
86 | {
87 | label: "GitHub Discussions",
88 | href: "https://github.com/tosin2013/documcp/discussions",
89 | },
90 | {
91 | label: "Issues",
92 | href: "https://github.com/tosin2013/documcp/issues",
93 | },
94 | ],
95 | },
96 | {
97 | title: "More",
98 | items: [
99 | {
100 | label: "GitHub",
101 | href: "https://github.com/tosin2013/documcp",
102 | },
103 | {
104 | label: "Model Context Protocol",
105 | href: "https://modelcontextprotocol.io/",
106 | },
107 | ],
108 | },
109 | ],
110 | copyright: `Copyright ${new Date().getFullYear()} DocuMCP. Built with Docusaurus.`,
111 | },
112 | prism: {
113 | theme: require("prism-react-renderer").themes.github,
114 | darkTheme: require("prism-react-renderer").themes.dracula,
115 | additionalLanguages: ["bash", "json", "yaml"],
116 | },
117 | },
118 | };
119 |
```
--------------------------------------------------------------------------------
/.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/sidebars.js:
--------------------------------------------------------------------------------
```javascript
1 | /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
2 | const sidebars = {
3 | // Main documentation sidebar
4 | docsSidebar: [
5 | "index",
6 | {
7 | type: "category",
8 | label: "📚 Tutorials",
9 | items: [
10 | "tutorials/getting-started",
11 | "tutorials/development-setup",
12 | "tutorials/environment-setup",
13 | "tutorials/first-deployment",
14 | "tutorials/user-onboarding",
15 | "tutorials/memory-workflows",
16 | ],
17 | },
18 | {
19 | type: "category",
20 | label: "🔧 How-To Guides",
21 | items: [
22 | "how-to/repository-analysis",
23 | "how-to/drift-priority-scoring",
24 | "how-to/github-pages-deployment",
25 | "how-to/local-testing",
26 | "how-to/prompting-guide",
27 | "how-to/usage-examples",
28 | "how-to/analytics-setup",
29 | "how-to/custom-domains",
30 | "how-to/performance-optimization",
31 | "how-to/seo-optimization",
32 | "how-to/site-monitoring",
33 | "how-to/troubleshooting",
34 | ],
35 | },
36 | {
37 | type: "category",
38 | label: "📖 Reference",
39 | items: [
40 | "reference/api-overview",
41 | "reference/cli",
42 | "reference/mcp-tools",
43 | "reference/deploy-pages",
44 | "reference/configuration",
45 | "reference/prompt-templates",
46 | ],
47 | },
48 | {
49 | type: "category",
50 | label: "💡 Explanation",
51 | items: [
52 | "explanation/architecture",
53 | "phase-2-intelligence",
54 | "knowledge-graph",
55 | ],
56 | },
57 | {
58 | type: "category",
59 | label: "🔬 Research",
60 | link: {
61 | type: "doc",
62 | id: "research/README",
63 | },
64 | items: [
65 | "research/research-questions-2025-01-14",
66 | "research/research-integration-summary-2025-01-14",
67 | "research/research-progress-template",
68 | "research/domain-1-mcp-architecture/mcp-performance-research",
69 | "research/domain-3-ssg-recommendation/ssg-performance-analysis",
70 | "research/domain-5-github-deployment/github-pages-security-analysis",
71 | ],
72 | },
73 | {
74 | type: "category",
75 | label: "🏛️ Architecture Decisions",
76 | link: {
77 | type: "doc",
78 | id: "adrs/README",
79 | },
80 | items: [
81 | "adrs/adr-1-mcp-server-architecture",
82 | "adrs/adr-2-repository-analysis-engine",
83 | "adrs/adr-3-static-site-generator-recommendation-engine",
84 | "adrs/adr-4-diataxis-framework-integration",
85 | "adrs/adr-5-github-pages-deployment-automation",
86 | "adrs/adr-6-mcp-tools-api-design",
87 | "adrs/adr-7-mcp-prompts-and-resources-integration",
88 | "adrs/adr-8-intelligent-content-population-engine",
89 | "adrs/adr-9-content-accuracy-validation-framework",
90 | "adrs/adr-10-mcp-resource-pattern-redesign",
91 | "adrs/adr-11-ce-mcp-compatibility",
92 | "adrs/adr-12-priority-scoring-system-for-documentation-drift",
93 | "adrs/adr-13-release-pipeline-and-package-distribution",
94 | ],
95 | },
96 | {
97 | type: "category",
98 | label: "🛠️ Development",
99 | items: ["development/MCP_INSPECTOR_TESTING"],
100 | },
101 | {
102 | type: "category",
103 | label: "📘 Guides",
104 | items: [
105 | "guides/link-validation",
106 | "guides/playwright-integration",
107 | "guides/playwright-testing-workflow",
108 | ],
109 | },
110 | ],
111 | };
112 |
113 | module.exports = sidebars;
114 |
```
--------------------------------------------------------------------------------
/.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/research/domain-3-ssg-recommendation/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.966Z"
4 | last_validated: "2025-12-09T19:41:38.596Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # Domain 3: SSG Recommendation Research
11 |
12 | This directory contains research and analysis related to DocuMCP's static site generator recommendation engine.
13 |
14 | ## Research Overview
15 |
16 | ### Recommendation Engine
17 |
18 | - **SSG Analysis**: Comprehensive analysis of static site generators
19 | - **Recommendation Algorithms**: Multi-criteria decision analysis algorithms
20 | - **Performance Metrics**: SSG performance characteristics and benchmarks
21 | - **User Preference Learning**: Adaptive recommendation based on user patterns
22 |
23 | ### Key Research Areas
24 |
25 | - **SSG Profiling**: Detailed profiles of supported SSGs (Jekyll, Hugo, Docusaurus, MkDocs, Eleventy)
26 | - **Recommendation Accuracy**: Validation of recommendation quality
27 | - **Performance Analysis**: SSG performance under various conditions
28 | - **User Satisfaction**: Measuring user satisfaction with recommendations
29 |
30 | ## Research Files
31 |
32 | - `ssg-performance-analysis.md`: Comprehensive SSG performance analysis
33 | - `recommendation-algorithms.md`: Recommendation algorithm research
34 | - `user-satisfaction-study.md`: User satisfaction and recommendation accuracy
35 | - `ssg-comparison.md`: Detailed comparison of SSG capabilities
36 |
37 | ## Key Findings
38 |
39 | ### Recommendation Accuracy
40 |
41 | - Overall recommendation accuracy: 92%
42 | - User satisfaction with recommendations: 89%
43 | - SSG performance prediction accuracy: 95%
44 | - Project type detection accuracy: 98%
45 |
46 | ### Performance Metrics
47 |
48 | - Recommendation generation time: < 200ms
49 | - SSG build time prediction accuracy: 90%
50 | - Memory usage optimization: 85% reduction for large sites
51 | - Deployment success rate: 97%
52 |
53 | ### User Experience
54 |
55 | - Time to first deployment: Reduced by 70%
56 | - Documentation quality improvement: 85%
57 | - User learning curve reduction: 60%
58 | - Maintenance effort reduction: 50%
59 |
60 | ## SSG Analysis Results
61 |
62 | ### Performance Rankings
63 |
64 | 1. **Hugo**: Fastest build times, excellent for large sites
65 | 2. **Docusaurus**: Best for documentation, React-based projects
66 | 3. **Jekyll**: Excellent GitHub integration, good for blogs
67 | 4. **Eleventy**: Flexible, good for custom requirements
68 | 5. **MkDocs**: Simple, good for Python projects
69 |
70 | ### Use Case Recommendations
71 |
72 | - **Large Sites (>1000 pages)**: Hugo or Docusaurus
73 | - **Documentation Focus**: Docusaurus or MkDocs
74 | - **Blog Focus**: Jekyll or Hugo
75 | - **Custom Requirements**: Eleventy
76 | - **Python Projects**: MkDocs
77 |
78 | ## Future Research
79 |
80 | ### Planned Studies
81 |
82 | - Machine learning integration for improved recommendations
83 | - Real-time SSG performance monitoring
84 | - Advanced user preference learning
85 | - Integration with emerging SSG technologies
86 |
87 | ### Research Questions
88 |
89 | - How can we further improve recommendation accuracy?
90 | - What are the best strategies for handling new SSG releases?
91 | - How can we better predict SSG performance for specific use cases?
92 | - What metrics best predict user satisfaction with SSG choices?
93 |
94 | ## Related Research
95 |
96 | - [Domain 2: Repository Analysis Research](../domain-2-repository-analysis/README.md)
97 | - [Domain 4: Diataxis Integration Research](../domain-4-diataxis-integration/README.md)
98 | - [Cross-Domain Integration Research](../cross-domain-integration/README.md)
99 | - [SSG Performance Analysis](./ssg-performance-analysis.md)
100 |
```
--------------------------------------------------------------------------------
/.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/tutorials/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.972Z"
4 | last_validated: "2025-12-09T19:41:38.604Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # Tutorials
11 |
12 | Step-by-step tutorials to get you started with DocuMCP and master advanced features.
13 |
14 | ## Getting Started
15 |
16 | ### Beginner Tutorials
17 |
18 | - [Getting Started with DocuMCP](getting-started.md) - Your first documentation deployment
19 | - [First Documentation Deployment](first-deployment.md) - Complete deployment workflow
20 | - [Development Setup](development-setup.md) - Set up your development environment
21 |
22 | ### Advanced Tutorials
23 |
24 | - [Memory Workflows](memory-workflows.md) - Advanced memory system features
25 |
26 | ## Learning Path
27 |
28 | ### For New Users
29 |
30 | 1. **Start Here**: [Getting Started with DocuMCP](getting-started.md)
31 | 2. **First Deployment**: [First Documentation Deployment](first-deployment.md)
32 | 3. **Development Setup**: [Development Setup](development-setup.md)
33 |
34 | ### For Advanced Users
35 |
36 | 1. **Memory System**: [Memory Workflows](memory-workflows.md)
37 | 2. **Custom Configuration**: See [Reference Documentation](../reference/)
38 | 3. **Advanced Features**: See [How-to Guides](../how-to/)
39 |
40 | ## Quick Start
41 |
42 | If you're new to DocuMCP, start with this simple workflow:
43 |
44 | ```bash
45 | # Analyze your repository
46 | "analyze my repository and recommend a static site generator"
47 |
48 | # Generate documentation
49 | "generate documentation structure for my project"
50 |
51 | # Deploy to GitHub Pages
52 | "deploy my documentation to GitHub Pages"
53 | ```
54 |
55 | ## What You'll Learn
56 |
57 | ### Core Concepts
58 |
59 | - **Repository Analysis**: How DocuMCP analyzes your project
60 | - **SSG Recommendations**: Choosing the right static site generator
61 | - **Documentation Generation**: Creating comprehensive documentation
62 | - **Deployment Automation**: Automated deployment workflows
63 |
64 | ### Advanced Features
65 |
66 | - **Memory System**: Learning from your documentation patterns
67 | - **Custom Configuration**: Tailoring DocuMCP to your needs
68 | - **Performance Optimization**: Optimizing your documentation site
69 | - **Analytics Integration**: Tracking documentation usage
70 |
71 | ## Prerequisites
72 |
73 | ### Basic Requirements
74 |
75 | - **Git Repository**: Your project in a Git repository
76 | - **GitHub Account**: For deployment to GitHub Pages
77 | - **Node.js**: Version 20.0.0 or higher (for local development)
78 |
79 | ### Recommended Knowledge
80 |
81 | - **Markdown**: Basic Markdown syntax
82 | - **Git**: Basic Git operations
83 | - **GitHub**: GitHub repository management
84 |
85 | ## Getting Help
86 |
87 | ### If You Get Stuck
88 |
89 | 1. **Check the Tutorials**: Review the relevant tutorial section
90 | 2. **How-to Guides**: See [How-to Guides](../how-to/) for specific tasks
91 | 3. **Reference Documentation**: Check [Reference](../reference/) for technical details
92 | 4. **Community Support**: Ask questions in [GitHub Issues](https://github.com/tosin2013/documcp/issues)
93 |
94 | ### Common Issues
95 |
96 | - **Repository Analysis Issues**: See [Troubleshooting Guide](../how-to/troubleshooting.md)
97 | - **Deployment Problems**: Check [GitHub Pages Deployment Guide](../how-to/github-pages-deployment.md)
98 | - **Local Testing**: See [Local Testing Guide](../how-to/local-testing.md)
99 |
100 | ## Next Steps
101 |
102 | After completing the tutorials:
103 |
104 | 1. **Explore How-to Guides**: [How-to Guides](../how-to/) for specific tasks
105 | 2. **Reference Documentation**: [Reference](../reference/) for technical details
106 | 3. **Architecture Understanding**: [Architecture Documentation](../explanation/)
107 | 4. **Community**: Join [GitHub Issues](https://github.com/tosin2013/documcp/issues) for support and feature requests
108 |
```
--------------------------------------------------------------------------------
/docs/reference/index.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.962Z"
4 | last_validated: "2025-12-09T19:41:38.592Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # Reference Documentation
11 |
12 | Complete technical reference for DocuMCP's API, configuration, and tools.
13 |
14 | ## 🎯 For AI Assistants: LLM_CONTEXT.md
15 |
16 | **Essential for AI-powered workflows**: Reference the comprehensive context file:
17 |
18 | - **[LLM Context Reference](../../LLM_CONTEXT.md)** - Complete tool reference for AI assistants (45 tools, workflows, examples)
19 |
20 | Use in AI assistants: `@LLM_CONTEXT.md [your query]`
21 |
22 | ## API Reference
23 |
24 | - **[API Overview](api-overview.md)** - Complete tool categorization and quick reference (NEW!)
25 | - **[MCP Tools API](mcp-tools.md)** - Detailed API reference for all DocuMCP tools
26 | - **[Deploy Pages Tool](deploy-pages.md)** - Comprehensive deploy_pages tool documentation
27 | - **[TypeDoc API](../api/)** - Auto-generated API documentation
28 | - [Configuration Options](configuration.md) - Configuration file reference
29 | - [CLI Commands](cli.md) - Command-line interface reference
30 | - [Prompt Templates](prompt-templates.md) - Available prompt templates
31 |
32 | ## Quick Reference
33 |
34 | ### Essential Tools
35 |
36 | ```bash
37 | # Repository Analysis
38 | "analyze my repository with deep analysis"
39 |
40 | # SSG Recommendation
41 | "recommend static site generator for my project"
42 |
43 | # Documentation Generation
44 | "generate documentation structure for my project"
45 |
46 | # Deployment
47 | "deploy my documentation to GitHub Pages"
48 | ```
49 |
50 | ### Configuration Examples
51 |
52 | ```yaml
53 | # Basic configuration
54 | memory:
55 | storage_path: ".documcp/memory"
56 | retention_policy: "keep_all"
57 |
58 | deployment:
59 | platform: "github-pages"
60 | branch: "gh-pages"
61 | domain: "docs.example.com"
62 | ```
63 |
64 | ## API Overview
65 |
66 | DocuMCP provides **45 tools** across 7 main categories. See [API Overview](api-overview.md) for complete details.
67 |
68 | ### Analysis Tools
69 |
70 | - `analyze_repository` - Comprehensive repository analysis
71 | - `detect_gaps` - Documentation gap detection
72 | - `evaluate_readme_health` - README quality assessment
73 |
74 | ### Recommendation Tools
75 |
76 | - `recommend_ssg` - Static site generator recommendations
77 | - `generate_config` - SSG configuration generation
78 | - `setup_structure` - Documentation structure creation
79 |
80 | ### Content Tools
81 |
82 | - `populate_content` - Intelligent content population
83 | - `validate_content` - Content validation and checking
84 | - `update_existing_documentation` - Documentation updates
85 |
86 | ### Deployment Tools
87 |
88 | - `deploy_pages` - GitHub Pages deployment
89 | - `verify_deployment` - Deployment verification
90 | - `test_local_deployment` - Local testing
91 |
92 | ## Memory System
93 |
94 | DocuMCP includes a sophisticated memory system for learning and optimization:
95 |
96 | ### Memory Operations
97 |
98 | - `memory_recall` - Retrieve stored memories
99 | - `memory_export` - Export memories for backup
100 | - `memory_import` - Import memories from files
101 | - `memory_cleanup` - Clean up old memories
102 |
103 | ### Analytics
104 |
105 | - `analyze_deployments` - Deployment pattern analysis
106 | - `memory_insights` - Memory-based insights
107 | - `similar_projects` - Find similar projects
108 |
109 | ## Getting Started
110 |
111 | 1. **First Time**: Start with [Getting Started Tutorial](../tutorials/getting-started.md)
112 | 2. **API Reference**: Explore [MCP Tools API](mcp-tools.md)
113 | 3. **Configuration**: Review [Configuration Options](configuration.md)
114 | 4. **Advanced Usage**: Check [CLI Commands](cli.md)
115 |
116 | ## Support
117 |
118 | - **Documentation**: This reference guide
119 | - **Examples**: See [Tutorials](../tutorials/)
120 | - **Community**: [GitHub Issues](https://github.com/tosin2013/documcp/issues)
121 | - **Issues**: [GitHub Issues](https://github.com/tosin2013/documcp/issues)
122 |
```
--------------------------------------------------------------------------------
/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-12-09T19:41:38.595Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # MCP Performance and Architecture Research
11 |
12 | **Research Date**: 2025-01-14
13 | **Domain**: MCP Server Architecture
14 | **Status**: In Progress
15 |
16 | ## Research Overview
17 |
18 | Research findings on TypeScript MCP SDK performance characteristics, Node.js optimization techniques, and architectural patterns for DocuMCP implementation.
19 |
20 | ## Research Questions Addressed
21 |
22 | ### Q1.1: TypeScript MCP SDK Performance Characteristics
23 |
24 | **Priority**: Critical Path
25 | **Status**: Research Complete
26 |
27 | **Key Findings**:
28 |
29 | 1. **SDK Performance Profile**:
30 |
31 | - TypeScript MCP SDK uses JSON-RPC 2.0 protocol with minimal overhead
32 | - Native WebSocket/stdio transport layers optimize communication
33 | - Type safety adds compile-time checks without runtime performance cost
34 |
35 | 2. **Best Practice Recommendations**:
36 | - Use structured data types for complex tool parameters
37 | - Implement proper error handling to avoid protocol disruptions
38 | - Leverage native TypeScript types for parameter validation
39 |
40 | **Sources**:
41 |
42 | - Official MCP TypeScript SDK documentation
43 | - GitHub performance discussions in MCP repositories
44 |
45 | ### Q1.2: Node.js Memory Management for Large Repository Analysis
46 |
47 | **Priority**: High
48 | **Status**: Research Complete
49 |
50 | **Key Findings**:
51 |
52 | 1. **Memory Optimization Strategies**:
53 |
54 | - Use streaming for large file processing (fs.createReadStream)
55 | - Implement worker threads for CPU-intensive analysis tasks
56 | - Apply garbage collection optimization with --max-old-space-size
57 | - Use memory-mapped files for large repository scanning
58 |
59 | 2. **Performance Benchmarks**:
60 | - Streaming approach: 10x memory reduction for files >100MB
61 | - Worker threads: 3-4x performance improvement for parallel processing
62 | - Memory-mapped files: 5x faster for large directory traversal
63 |
64 | **Technical Implementation**:
65 |
66 | ```typescript
67 | // Example streaming approach for large file analysis
68 | const analyzeFileStream = (filePath: string) => {
69 | return new Promise((resolve, reject) => {
70 | const stream = fs.createReadStream(filePath, { encoding: "utf8" });
71 | let lineCount = 0;
72 |
73 | stream.on("data", (chunk) => {
74 | lineCount += chunk.split("\n").length - 1;
75 | });
76 |
77 | stream.on("end", () => resolve(lineCount));
78 | stream.on("error", reject);
79 | });
80 | };
81 | ```
82 |
83 | **Sources**:
84 |
85 | - Node.js performance optimization guides
86 | - Repository analysis tool benchmarks from major OSS projects
87 |
88 | ## Implementation Recommendations
89 |
90 | ### Critical Insights for DocuMCP
91 |
92 | 1. **Architecture Decision**: Use TypeScript MCP SDK with streaming-based repository analysis
93 | 2. **Performance Strategy**: Implement worker thread pool for parallel file processing
94 | 3. **Memory Management**: Apply streaming patterns for files >10MB, memory mapping for directory scans
95 | 4. **Error Handling**: Implement circuit breaker pattern for external service calls
96 |
97 | ### Next Steps
98 |
99 | 1. **Benchmark Testing**: Create performance tests for different repository sizes
100 | 2. **Memory Profiling**: Test memory usage with repositories of various complexities
101 | 3. **Concurrency Testing**: Validate worker thread performance under load
102 |
103 | ## Research Validation Status
104 |
105 | - ✅ Performance characteristics documented
106 | - ✅ Memory optimization strategies identified
107 | - ⚠️ Needs validation: Large repository benchmarks
108 | - ⚠️ Needs testing: Worker thread implementation patterns
109 |
110 | ## Related Research
111 |
112 | - See Domain 2: Repository Analysis Engine for file processing patterns
113 | - See Domain 6: API Design for MCP tool performance considerations
114 |
```
--------------------------------------------------------------------------------
/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 |
```
--------------------------------------------------------------------------------
/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-12-09T19:41:38.598Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # Domain 5: GitHub Deployment Research
11 |
12 | This directory contains research and analysis related to DocuMCP's GitHub Pages deployment automation and optimization.
13 |
14 | ## Research Overview
15 |
16 | ### Deployment Automation
17 |
18 | - **GitHub Actions Integration**: Automated deployment workflow optimization
19 | - **Deployment Strategies**: Different deployment approaches and their effectiveness
20 | - **Performance Optimization**: Deployment speed and reliability improvements
21 | - **Error Handling**: Robust error handling and recovery mechanisms
22 |
23 | ### Key Research Areas
24 |
25 | - **Deployment Success Rates**: Measuring deployment success across different scenarios
26 | - **Performance Analysis**: Deployment time and resource usage optimization
27 | - **Security Analysis**: Security considerations for automated deployments
28 | - **User Experience**: Impact of deployment automation on user experience
29 |
30 | ## Research Files
31 |
32 | - `github-pages-security-analysis.md`: Security analysis of GitHub Pages deployments
33 | - `deployment-performance-study.md`: Deployment performance research
34 | - `automation-effectiveness.md`: Effectiveness of deployment automation
35 | - `error-handling-research.md`: Error handling and recovery research
36 |
37 | ## Key Findings
38 |
39 | ### Deployment Success Rates
40 |
41 | - Overall deployment success rate: 97%
42 | - First-time deployment success: 95%
43 | - Redeployment success rate: 99%
44 | - Error recovery success rate: 94%
45 |
46 | ### Performance Metrics
47 |
48 | - Average deployment time: 3-5 minutes
49 | - Build time optimization: 40% reduction
50 | - Resource usage optimization: 60% reduction
51 | - Deployment reliability: 99.5% uptime
52 |
53 | ### Security Analysis
54 |
55 | - Security vulnerability rate: < 0.1%
56 | - Automated security scanning: 100% coverage
57 | - Dependency vulnerability detection: 98%
58 | - Access control effectiveness: 99%
59 |
60 | ## Deployment Strategies
61 |
62 | ### Automated Deployment
63 |
64 | - **GitHub Actions**: Primary deployment method
65 | - **Workflow Optimization**: Optimized for speed and reliability
66 | - **Error Recovery**: Automatic retry and fallback mechanisms
67 | - **Monitoring**: Comprehensive deployment monitoring
68 |
69 | ### Manual Deployment
70 |
71 | - **User Control**: Full user control over deployment process
72 | - **Customization**: Extensive customization options
73 | - **Troubleshooting**: Detailed troubleshooting guidance
74 | - **Verification**: Comprehensive deployment verification
75 |
76 | ## Security Considerations
77 |
78 | ### GitHub Pages Security
79 |
80 | - **HTTPS Enforcement**: Automatic HTTPS configuration
81 | - **Access Control**: Proper access control implementation
82 | - **Dependency Scanning**: Automated dependency vulnerability scanning
83 | - **Content Validation**: Content security validation
84 |
85 | ### Best Practices
86 |
87 | - **Least Privilege**: Minimal required permissions
88 | - **Regular Updates**: Keep dependencies updated
89 | - **Monitoring**: Continuous security monitoring
90 | - **Incident Response**: Rapid incident response procedures
91 |
92 | ## Future Research
93 |
94 | ### Planned Studies
95 |
96 | - Advanced deployment optimization techniques
97 | - Enhanced security monitoring and response
98 | - Real-time deployment analytics
99 | - Integration with other deployment platforms
100 |
101 | ### Research Questions
102 |
103 | - How can we further optimize deployment performance?
104 | - What are the best strategies for handling deployment failures?
105 | - How can we improve security monitoring and response?
106 | - What metrics best predict deployment success?
107 |
108 | ## Related Research
109 |
110 | - [Domain 2: Repository Analysis Research](../domain-2-repository-analysis/README.md)
111 | - [Domain 4: Diataxis Integration Research](../domain-4-diataxis-integration/README.md)
112 | - [Cross-Domain Integration Research](../cross-domain-integration/README.md)
113 | - [GitHub Pages Security Analysis](./github-pages-security-analysis.md)
114 |
```
--------------------------------------------------------------------------------
/.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 |
```
--------------------------------------------------------------------------------
/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 |
```
--------------------------------------------------------------------------------
/docs/how-to/site-monitoring.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.955Z"
4 | last_validated: "2025-12-09T19:41:38.586Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # How to Verify and Monitor Your Documentation Deployment
11 |
12 | This guide shows you how to verify your deployed documentation site and monitor deployment health using DocuMCP's built-in tools.
13 |
14 | ## Quick Setup
15 |
16 | ```bash
17 | # Verify your deployment:
18 | "verify my GitHub Pages deployment and check for issues"
19 | ```
20 |
21 | ## Deployment Verification Overview
22 |
23 | DocuMCP provides deployment verification and health monitoring capabilities:
24 |
25 | ### Verification Features
26 |
27 | - **Deployment Status**: Check if GitHub Pages deployment succeeded
28 | - **Site Accessibility**: Verify your site is reachable
29 | - **Content Validation**: Check documentation accuracy and links
30 | - **Build Health**: Monitor deployment pipeline health
31 |
32 | ### Health Monitoring
33 |
34 | - **Deployment Analytics**: Track success/failure rates over time
35 | - **Build Time Monitoring**: Monitor deployment performance
36 | - **Error Detection**: Identify common deployment issues
37 |
38 | ## Setup Methods
39 |
40 | ### Method 1: Deployment Verification
41 |
42 | ```bash
43 | # Verify deployment status:
44 | "verify my GitHub Pages deployment and check for issues"
45 | ```
46 |
47 | This will:
48 |
49 | 1. Check GitHub Pages deployment status
50 | 2. Verify site accessibility
51 | 3. Validate documentation links
52 | 4. Check content accuracy
53 | 5. Generate health report
54 |
55 | ### Method 2: Content Validation
56 |
57 | #### Step 1: Link Checking
58 |
59 | ```bash
60 | # Check documentation links:
61 | "check all my documentation links for broken references"
62 | ```
63 |
64 | #### Step 2: Content Accuracy
65 |
66 | ```bash
67 | # Validate content accuracy:
68 | "validate my documentation content for errors and inconsistencies"
69 | ```
70 |
71 | #### Step 3: Deployment Health
72 |
73 | ```bash
74 | # Check deployment health:
75 | "analyze my deployment health and provide recommendations"
76 | ```
77 |
78 | ## Deployment Health Monitoring
79 |
80 | ### Using MCP Tools
81 |
82 | ```typescript
83 | // Check deployment verification
84 | import { verifyDeployment } from "./dist/tools/verify-deployment.js";
85 |
86 | const verification = await verifyDeployment({
87 | repository: "username/repo-name",
88 | url: "https://username.github.io/repo-name",
89 | });
90 |
91 | // Check documentation links
92 | import { checkDocumentationLinks } from "./dist/tools/check-documentation-links.js";
93 |
94 | const linkCheck = await checkDocumentationLinks({
95 | documentation_path: "./docs",
96 | check_external_links: true,
97 | check_internal_links: true,
98 | });
99 | ```
100 |
101 | ### Key Health Indicators
102 |
103 | - **Deployment Success**: GitHub Pages build status
104 | - **Link Health**: Broken/working link ratio
105 | - **Content Accuracy**: Documentation validation score
106 | - **Build Performance**: Deployment time trends
107 |
108 | ## Troubleshooting
109 |
110 | ### Common Issues
111 |
112 | **Problem**: Deployment verification fails
113 | **Solution**: Check GitHub Pages settings and repository permissions
114 |
115 | **Problem**: Link checker reports false broken links
116 | **Solution**: Verify external link accessibility and adjust timeout settings
117 |
118 | **Problem**: Content validation shows low accuracy
119 | **Solution**: Review code examples and update outdated documentation
120 |
121 | **Problem**: Health score seems low
122 | **Solution**: Analyze deployment failures and optimize configurations
123 |
124 | ## Advanced Configuration
125 |
126 | ### Custom Validation
127 |
128 | ```yaml
129 | # validation-config.yml
130 | validation:
131 | links:
132 | timeout: 30s
133 | check_external: true
134 | check_internal: true
135 | content:
136 | accuracy_threshold: 70
137 | include_code_validation: true
138 | deployment:
139 | health_threshold: 80
140 | track_build_times: true
141 | ```
142 |
143 | ### Integration Options
144 |
145 | - **GitHub Actions**: Automated validation in CI/CD workflows
146 | - **MCP Tools**: Direct integration with documcp verification tools
147 | - **Custom Scripts**: Tailored monitoring solutions
148 |
149 | ## Best Practices
150 |
151 | 1. **Set Realistic Thresholds**: Avoid alert fatigue
152 | 2. **Monitor Key Pages**: Focus on critical documentation
153 | 3. **Regular Reviews**: Check metrics weekly
154 | 4. **Automated Responses**: Set up auto-healing where possible
155 |
156 | ## Next Steps
157 |
158 | - [Custom Domains Setup](custom-domains.md)
159 | - [SEO Optimization](seo-optimization.md)
160 | - [Analytics Setup](analytics-setup.md)
161 | - [Troubleshooting Guide](../how-to/troubleshooting.md)
162 |
```
--------------------------------------------------------------------------------
/.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-12-09T19:41:38.578Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # Explanation Documentation
11 |
12 | Conceptual documentation and background information about DocuMCP's architecture and design principles.
13 |
14 | ## Architecture Overview
15 |
16 | - [DocuMCP Architecture](architecture.md) - Complete system architecture overview
17 | - [Phase 2: Intelligence & Learning System](../phase-2-intelligence.md) - Advanced AI features
18 |
19 | ## Design Principles
20 |
21 | ### Methodological Pragmatism
22 |
23 | DocuMCP is built on methodological pragmatism frameworks, emphasizing:
24 |
25 | - **Practical Outcomes**: Focus on what works reliably
26 | - **Systematic Verification**: Structured processes for validating knowledge
27 | - **Explicit Fallibilism**: Acknowledging limitations and uncertainty
28 | - **Cognitive Systematization**: Organizing knowledge into coherent systems
29 |
30 | ### Error Architecture Awareness
31 |
32 | The system recognizes different types of errors:
33 |
34 | - **Human-Cognitive Errors**: Knowledge gaps, attention limitations, cognitive biases
35 | - **Artificial-Stochastic Errors**: Pattern completion errors, context limitations, training artifacts
36 |
37 | ### Systematic Verification
38 |
39 | All recommendations include:
40 |
41 | - Confidence scores for significant recommendations
42 | - Explicit checks for different error types
43 | - Verification approaches and validation methods
44 | - Consideration of edge cases and limitations
45 |
46 | ## System Components
47 |
48 | ### Core Architecture
49 |
50 | - **MCP Server**: Model Context Protocol implementation
51 | - **Repository Analysis Engine**: Multi-layered project analysis
52 | - **SSG Recommendation Engine**: Data-driven static site generator selection
53 | - **Documentation Generation**: Intelligent content creation
54 | - **Deployment Automation**: Automated GitHub Pages deployment
55 |
56 | ### Intelligence System (Phase 2)
57 |
58 | - **Memory System**: Historical data and pattern learning
59 | - **User Preferences**: Personalized recommendations
60 | - **Deployment Analytics**: Success pattern analysis
61 | - **Smart Scoring**: Intelligent SSG scoring based on historical data
62 |
63 | ## Integration Patterns
64 |
65 | ### MCP Integration
66 |
67 | DocuMCP integrates seamlessly with:
68 |
69 | - **Claude Desktop**: AI assistant integration
70 | - **GitHub Copilot**: Development environment integration
71 | - **Other MCP Clients**: Broad compatibility through protocol compliance
72 |
73 | ### Development Workflow
74 |
75 | - **Repository Analysis**: Understand project structure and needs
76 | - **SSG Recommendation**: Select optimal static site generator
77 | - **Documentation Generation**: Create comprehensive documentation
78 | - **Deployment**: Automated deployment to GitHub Pages
79 |
80 | ## Research Foundation
81 |
82 | DocuMCP is built on extensive research across multiple domains:
83 |
84 | - **Repository Analysis**: Multi-layered analysis techniques
85 | - **SSG Performance**: Comprehensive static site generator analysis
86 | - **Documentation Patterns**: Diataxis framework integration
87 | - **Deployment Optimization**: GitHub Pages deployment best practices
88 | - **API Design**: Model Context Protocol best practices
89 |
90 | ## Future Directions
91 |
92 | ### Planned Enhancements
93 |
94 | - **Advanced AI Integration**: Enhanced machine learning capabilities
95 | - **Real-time Collaboration**: Multi-user documentation workflows
96 | - **Extended Platform Support**: Support for additional deployment platforms
97 | - **Advanced Analytics**: Comprehensive documentation analytics
98 |
99 | ### Research Areas
100 |
101 | - **Cross-Domain Integration**: Seamless workflow integration
102 | - **Performance Optimization**: Advanced performance tuning
103 | - **User Experience**: Enhanced user interaction patterns
104 | - **Scalability**: Large-scale deployment management
105 |
106 | ## Philosophy
107 |
108 | DocuMCP embodies the principle that documentation should be:
109 |
110 | - **Intelligent**: AI-powered analysis and recommendations
111 | - **Automated**: Minimal manual intervention required
112 | - **Comprehensive**: Complete documentation lifecycle coverage
113 | - **Accessible**: Easy to use for developers of all skill levels
114 | - **Reliable**: Consistent, high-quality results
115 |
116 | ## Related Documentation
117 |
118 | - [Tutorials](../tutorials/) - Step-by-step guides
119 | - [How-to Guides](../how-to/) - Task-specific instructions
120 | - [Reference](../reference/) - Technical API reference
121 | - [Architecture Decision Records](../adrs/) - Design decisions and rationale
122 |
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "documcp",
3 | "version": "0.5.10",
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": "^1.24.0",
72 | "@typescript-eslint/typescript-estree": "^8.44.0",
73 | "chokidar": "^4.0.1",
74 | "globby": "^14.1.0",
75 | "gray-matter": "^4.0.3",
76 | "linkinator": "^6.1.4",
77 | "simple-git": "^3.30.0",
78 | "tmp": "^0.2.5",
79 | "tree-sitter-bash": "^0.25.0",
80 | "tree-sitter-go": "^0.25.0",
81 | "tree-sitter-java": "^0.23.5",
82 | "tree-sitter-javascript": "^0.25.0",
83 | "tree-sitter-python": "^0.25.0",
84 | "tree-sitter-ruby": "^0.23.1",
85 | "tree-sitter-rust": "^0.24.0",
86 | "tree-sitter-typescript": "^0.23.2",
87 | "tree-sitter-yaml": "^0.5.0",
88 | "web-tree-sitter": "^0.25.9",
89 | "zod": "^3.22.4",
90 | "zod-to-json-schema": "^3.24.6"
91 | },
92 | "devDependencies": {
93 | "@commitlint/cli": "^19.8.1",
94 | "@commitlint/config-conventional": "^19.8.1",
95 | "@types/jest": "^29.5.11",
96 | "@types/node": "^20.11.0",
97 | "@types/tmp": "^0.2.6",
98 | "@typescript-eslint/eslint-plugin": "^6.19.0",
99 | "@typescript-eslint/parser": "^6.19.0",
100 | "eslint": "^8.56.0",
101 | "husky": "^9.1.7",
102 | "jest": "^29.7.0",
103 | "markdown-link-check": "^3.12.2",
104 | "prettier": "^3.2.4",
105 | "standard-version": "^9.5.0",
106 | "ts-jest": "^29.1.1",
107 | "tsx": "^4.7.0",
108 | "typedoc": "^0.28.13",
109 | "typescript": "^5.3.3"
110 | },
111 | "engines": {
112 | "node": ">=20.0.0"
113 | },
114 | "overrides": {
115 | "markdown-link-check": {
116 | "xmlbuilder2": "^4.0.0"
117 | }
118 | }
119 | }
120 |
```
--------------------------------------------------------------------------------
/docs/how-to/custom-domains.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.950Z"
4 | last_validated: "2025-12-09T19:41:38.581Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # How to Set Up Custom Domains
11 |
12 | This guide shows you how to configure custom domains for your DocuMCP-deployed documentation site.
13 |
14 | ## Quick Setup
15 |
16 | ```bash
17 | # Prompt DocuMCP:
18 | "set up custom domain for my documentation site"
19 | ```
20 |
21 | ## Custom Domain Overview
22 |
23 | DocuMCP supports custom domain configuration for professional documentation sites:
24 |
25 | ### Domain Types
26 |
27 | - **Subdomains**: `docs.yourcompany.com`
28 | - **Root Domains**: `yourcompany.com`
29 | - **Path-based**: `yourcompany.com/docs`
30 |
31 | ### Requirements
32 |
33 | - Domain ownership verification
34 | - DNS configuration access
35 | - GitHub Pages enabled
36 | - SSL certificate (automatic with GitHub Pages)
37 |
38 | ## Setup Methods
39 |
40 | ### Method 1: Automated Setup (Recommended)
41 |
42 | ```bash
43 | # Complete domain setup:
44 | "configure custom domain docs.example.com for my site"
45 | ```
46 |
47 | This will:
48 |
49 | 1. Guide you through DNS configuration
50 | 2. Set up GitHub Pages custom domain
51 | 3. Configure SSL certificate
52 | 4. Test domain connectivity
53 | 5. Set up redirects if needed
54 |
55 | ### Method 2: Manual Configuration
56 |
57 | #### Step 1: DNS Configuration
58 |
59 | Add the following DNS records to your domain:
60 |
61 | **For Subdomain (docs.example.com):**
62 |
63 | ```
64 | Type: CNAME
65 | Name: docs
66 | Value: yourusername.github.io
67 | ```
68 |
69 | > **Note**: Replace `yourusername` with your GitHub username or organization name.
70 |
71 | **For Root Domain (example.com):**
72 |
73 | ```
74 | Type: A
75 | Name: @
76 | Value: 185.199.108.153
77 | Value: 185.199.109.153
78 | Value: 185.199.110.153
79 | Value: 185.199.111.153
80 | ```
81 |
82 | #### Step 2: GitHub Pages Configuration
83 |
84 | 1. Go to your repository settings
85 | 2. Navigate to "Pages" section
86 | 3. Enter your custom domain
87 | 4. Enable "Enforce HTTPS"
88 |
89 | #### Step 3: Verification
90 |
91 | ```bash
92 | # Verify domain setup:
93 | "verify my custom domain configuration"
94 | ```
95 |
96 | ## Domain Configuration Examples
97 |
98 | ### Subdomain Setup
99 |
100 | ```yaml
101 | # Custom domain configuration
102 | domain:
103 | type: subdomain
104 | name: "docs.example.com"
105 | redirects:
106 | - from: "example.com/docs"
107 | to: "docs.example.com"
108 | ```
109 |
110 | ### Root Domain Setup
111 |
112 | ```yaml
113 | # Root domain configuration
114 | domain:
115 | type: root
116 | name: "example.com"
117 | path: "/docs"
118 | ssl: true
119 | ```
120 |
121 | ## Advanced Configuration
122 |
123 | ### Multiple Domains
124 |
125 | ```bash
126 | # Set up multiple domains:
127 | "configure domains docs.example.com and help.example.com"
128 | ```
129 |
130 | ### Redirects
131 |
132 | ```bash
133 | # Set up redirects:
134 | "redirect old-domain.com to new-domain.com"
135 | ```
136 |
137 | ### SSL Configuration
138 |
139 | ```bash
140 | # Verify SSL setup:
141 | "check SSL certificate for my domain"
142 | ```
143 |
144 | ## Troubleshooting
145 |
146 | ### Common Issues
147 |
148 | **Problem**: Domain not resolving
149 | **Solution**: Check DNS propagation (up to 48 hours)
150 |
151 | **Problem**: SSL certificate issues
152 | **Solution**: Verify GitHub Pages settings and DNS
153 |
154 | **Problem**: Redirects not working
155 | **Solution**: Check CNAME vs A record configuration
156 |
157 | **Problem**: Mixed content warnings
158 | **Solution**: Ensure all resources use HTTPS
159 |
160 | ### DNS Troubleshooting
161 |
162 | ```bash
163 | # Check DNS propagation:
164 | dig docs.example.com
165 | nslookup docs.example.com
166 |
167 | # Test connectivity:
168 | curl -I https://docs.example.com
169 | ```
170 |
171 | ## Security Considerations
172 |
173 | ### HTTPS Enforcement
174 |
175 | - Always enable HTTPS in GitHub Pages
176 | - Use HSTS headers for security
177 | - Monitor certificate expiration
178 |
179 | ### Access Control
180 |
181 | - Configure appropriate permissions
182 | - Set up authentication if needed
183 | - Monitor access logs
184 |
185 | ## Performance Optimization
186 |
187 | ### CDN Configuration
188 |
189 | ```bash
190 | # Optimize with CDN:
191 | "set up CDN for my custom domain"
192 | ```
193 |
194 | ### Caching Headers
195 |
196 | ```yaml
197 | # Cache configuration
198 | caching:
199 | static_assets: "1 year"
200 | html_pages: "1 hour"
201 | api_responses: "5 minutes"
202 | ```
203 |
204 | ## Monitoring
205 |
206 | ### Domain Health
207 |
208 | ```bash
209 | # Monitor domain health:
210 | "set up monitoring for my custom domain"
211 | ```
212 |
213 | ### SSL Monitoring
214 |
215 | ```bash
216 | # Monitor SSL certificate:
217 | "monitor SSL certificate for my domain"
218 | ```
219 |
220 | ## Best Practices
221 |
222 | 1. **Use Subdomains**: Easier to manage than root domains
223 | 2. **Enable HTTPS**: Essential for security and SEO
224 | 3. **Set Up Redirects**: Maintain old URLs for SEO
225 | 4. **Monitor Uptime**: Track domain availability
226 | 5. **Document Changes**: Keep DNS records documented
227 |
228 | ## Next Steps
229 |
230 | - [Site Monitoring](site-monitoring.md)
231 | - [SEO Optimization](seo-optimization.md)
232 | - [Analytics Setup](analytics-setup.md)
233 | - [Performance Optimization](performance-optimization.md)
234 |
```
--------------------------------------------------------------------------------
/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/change-watcher.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { Tool } from "@modelcontextprotocol/sdk/types.js";
2 | import { z } from "zod";
3 | import { zodToJsonSchema } from "zod-to-json-schema";
4 | import { ChangeWatcher } from "../utils/change-watcher.js";
5 | import { formatMCPResponse, MCPContentWrapper } from "../types/api.js";
6 |
7 | export const changeWatcherSchema = z.object({
8 | action: z
9 | .enum(["start", "status", "stop", "trigger", "install_hook"])
10 | .default("status")
11 | .describe("Action to perform"),
12 | projectPath: z.string().describe("Project root path"),
13 | docsPath: z.string().describe("Documentation path"),
14 | watchPaths: z
15 | .array(z.string())
16 | .optional()
17 | .describe("Paths to watch (defaults to src/)"),
18 | excludePatterns: z
19 | .array(z.string())
20 | .optional()
21 | .describe("Glob patterns to exclude"),
22 | debounceMs: z
23 | .number()
24 | .min(50)
25 | .max(600000)
26 | .default(500)
27 | .describe("Debounce window for drift detection"),
28 | triggerOnCommit: z
29 | .boolean()
30 | .default(true)
31 | .describe("Respond to git commit events"),
32 | triggerOnPR: z.boolean().default(true).describe("Respond to PR/merge events"),
33 | webhookEndpoint: z
34 | .string()
35 | .optional()
36 | .describe("Webhook endpoint path (e.g., /hooks/documcp/change-watcher)"),
37 | webhookSecret: z
38 | .string()
39 | .optional()
40 | .describe("Shared secret for webhook signature validation"),
41 | port: z
42 | .number()
43 | .min(1)
44 | .max(65535)
45 | .optional()
46 | .describe("Port for webhook server (default 8787)"),
47 | snapshotDir: z.string().optional().describe("Snapshot directory override"),
48 | reason: z.string().optional().describe("Reason for manual trigger"),
49 | files: z
50 | .array(z.string())
51 | .optional()
52 | .describe("Changed files (for manual trigger)"),
53 | });
54 |
55 | type ChangeWatcherArgs = z.infer<typeof changeWatcherSchema>;
56 |
57 | let watcher: ChangeWatcher | null = null;
58 |
59 | // Exported for tests
60 | export function __resetChangeWatcher(): void {
61 | watcher = null;
62 | }
63 |
64 | function makeResponse<T>(data: T): ReturnType<typeof formatMCPResponse<T>> {
65 | return formatMCPResponse(
66 | {
67 | success: true,
68 | data,
69 | metadata: {
70 | toolVersion: "0.0.0",
71 | executionTime: 0,
72 | timestamp: new Date().toISOString(),
73 | },
74 | },
75 | { fullResponse: true },
76 | );
77 | }
78 |
79 | export async function handleChangeWatcher(
80 | args: unknown,
81 | context?: any,
82 | ): Promise<MCPContentWrapper> {
83 | const parsed = changeWatcherSchema.parse(args);
84 |
85 | switch (parsed.action) {
86 | case "start":
87 | return await startWatcher(parsed, context);
88 | case "status":
89 | return makeResponse(watcher ? watcher.getStatus() : { running: false });
90 | case "stop":
91 | if (watcher) {
92 | await watcher.stop();
93 | watcher = null;
94 | }
95 | return makeResponse({ running: false });
96 | case "trigger":
97 | if (!watcher) {
98 | await startWatcher(parsed, context);
99 | }
100 | if (!watcher) {
101 | throw new Error("Change watcher not available");
102 | }
103 | return makeResponse(
104 | await watcher.triggerManual(parsed.reason, parsed.files),
105 | );
106 | case "install_hook":
107 | if (!watcher) {
108 | await startWatcher(parsed, context);
109 | }
110 | if (!watcher) {
111 | throw new Error("Change watcher not available");
112 | }
113 | return makeResponse({
114 | hook: await watcher.installGitHook("post-commit"),
115 | });
116 | }
117 | }
118 |
119 | async function startWatcher(
120 | options: ChangeWatcherArgs,
121 | context?: any,
122 | ): Promise<MCPContentWrapper> {
123 | if (!watcher) {
124 | watcher = new ChangeWatcher(
125 | {
126 | projectPath: options.projectPath,
127 | docsPath: options.docsPath,
128 | watchPaths: options.watchPaths,
129 | excludePatterns: options.excludePatterns,
130 | debounceMs: options.debounceMs,
131 | triggerOnCommit: options.triggerOnCommit,
132 | triggerOnPR: options.triggerOnPR,
133 | webhookEndpoint: options.webhookEndpoint,
134 | webhookSecret: options.webhookSecret,
135 | port: options.port,
136 | snapshotDir: options.snapshotDir,
137 | },
138 | {
139 | logger: {
140 | info: context?.info,
141 | warn: context?.warn,
142 | error: context?.error,
143 | },
144 | },
145 | );
146 | await watcher.start();
147 | }
148 |
149 | return makeResponse(watcher.getStatus());
150 | }
151 |
152 | export const changeWatcherTool: Tool = {
153 | name: "change_watcher",
154 | description:
155 | "Watch code changes and trigger documentation drift detection in near real-time.",
156 | inputSchema: zodToJsonSchema(changeWatcherSchema) as any,
157 | };
158 |
```
--------------------------------------------------------------------------------
/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-12-09T19:41:38.586Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # How to Manage Documentation SEO
11 |
12 | This guide shows you how to use DocuMCP's sitemap management tools to improve your documentation's search engine visibility.
13 |
14 | ## Quick Setup
15 |
16 | ```bash
17 | # Generate sitemap for your documentation:
18 | "generate sitemap for my documentation"
19 | ```
20 |
21 | ## SEO Overview
22 |
23 | DocuMCP provides basic SEO support through sitemap management:
24 |
25 | ### Available SEO Features
26 |
27 | - **XML Sitemap Generation**: Automatic sitemap creation for documentation
28 | - **Sitemap Validation**: Verify sitemap structure and URLs
29 | - **Link Discovery**: Automatic detection of documentation pages
30 | - **GitHub Pages Integration**: Optimized for GitHub Pages deployment
31 |
32 | ### SEO Benefits
33 |
34 | - **Search Engine Discovery**: Help search engines find your documentation
35 | - **Crawling Efficiency**: Provide structured navigation for crawlers
36 | - **URL Organization**: Maintain clean URL structure
37 | - **Update Tracking**: Track when pages were last modified
38 |
39 | ## Setup Methods
40 |
41 | ### Method 1: Automatic Sitemap Generation
42 |
43 | ```bash
44 | # Generate sitemap for your documentation:
45 | "generate sitemap for my documentation"
46 | ```
47 |
48 | This will:
49 |
50 | 1. Scan your documentation directory
51 | 2. Discover all markdown and HTML files
52 | 3. Generate XML sitemap with proper URLs
53 | 4. Include last modified dates from git history
54 | 5. Validate sitemap structure
55 |
56 | ### Method 2: Manual Sitemap Management
57 |
58 | #### Step 1: Generate Sitemap
59 |
60 | ```bash
61 | # Create XML sitemap:
62 | "create sitemap for my documentation with base URL https://mydocs.com"
63 | ```
64 |
65 | #### Step 2: Validate Sitemap
66 |
67 | ```bash
68 | # Validate existing sitemap:
69 | "validate my documentation sitemap"
70 | ```
71 |
72 | #### Step 3: Update Sitemap
73 |
74 | ```bash
75 | # Update sitemap with new content:
76 | "update my documentation sitemap"
77 | ```
78 |
79 | ## Sitemap Management
80 |
81 | ### Using MCP Tools
82 |
83 | ```typescript
84 | // Generate sitemap using MCP tools
85 | import { manageSitemap } from "./dist/tools/manage-sitemap.js";
86 |
87 | // Generate new sitemap
88 | const sitemap = await manageSitemap({
89 | action: "generate",
90 | docsPath: "./docs",
91 | baseUrl: "https://mydocs.github.io/repo",
92 | });
93 |
94 | // Validate existing sitemap
95 | const validation = await manageSitemap({
96 | action: "validate",
97 | docsPath: "./docs",
98 | });
99 |
100 | // Update sitemap with new content
101 | const update = await manageSitemap({
102 | action: "update",
103 | docsPath: "./docs",
104 | baseUrl: "https://mydocs.github.io/repo",
105 | });
106 | ```
107 |
108 | ### Sitemap Configuration
109 |
110 | ```yaml
111 | # Sitemap generation settings
112 | sitemap:
113 | base_url: "https://mydocs.github.io/repo"
114 | include_patterns:
115 | - "**/*.md"
116 | - "**/*.html"
117 | exclude_patterns:
118 | - "node_modules/**"
119 | - ".git/**"
120 | update_frequency: "weekly"
121 | use_git_history: true
122 | ```
123 |
124 | ## Best Practices
125 |
126 | ### Sitemap Management
127 |
128 | 1. **Regular Updates**: Regenerate sitemap when adding new content
129 | 2. **Proper URLs**: Ensure all URLs in sitemap are accessible
130 | 3. **Git Integration**: Use git history for accurate last modified dates
131 | 4. **Validation**: Always validate sitemap after generation
132 | 5. **Submit to Search Engines**: Submit sitemap to Google Search Console
133 |
134 | ### URL Structure
135 |
136 | - Use clean, descriptive URLs
137 | - Maintain consistent URL patterns
138 | - Avoid deep nesting when possible
139 | - Include keywords in URLs naturally
140 |
141 | ### Content Organization
142 |
143 | - Structure content logically
144 | - Use clear headings and navigation
145 | - Maintain consistent documentation patterns
146 | - Link related content appropriately
147 |
148 | ## Troubleshooting
149 |
150 | ### Common Issues
151 |
152 | **Problem**: Sitemap not generating
153 | **Solution**: Check documentation directory permissions and file patterns
154 |
155 | **Problem**: Invalid URLs in sitemap
156 | **Solution**: Verify base URL configuration and file paths
157 |
158 | **Problem**: Sitemap not updating
159 | **Solution**: Ensure git history is accessible for last modified dates
160 |
161 | **Problem**: Search engines not finding pages
162 | **Solution**: Submit sitemap to Google Search Console and verify accessibility
163 |
164 | ### Sitemap Debugging
165 |
166 | ```bash
167 | # Debug sitemap issues:
168 | "validate my sitemap and check for errors"
169 | ```
170 |
171 | ## Sitemap Tools
172 |
173 | ### Built-in DocuMCP Tools
174 |
175 | - **Sitemap Generation**: Create XML sitemaps automatically
176 | - **Sitemap Validation**: Verify sitemap structure and URLs
177 | - **Link Discovery**: Find all documentation pages
178 | - **Git Integration**: Use git history for modification dates
179 |
180 | ### MCP Tools Available
181 |
182 | - `manage_sitemap`: Generate, validate, and update sitemaps
183 | - `check_documentation_links`: Verify all links work correctly
184 | - `validate_content`: Check documentation accuracy
185 |
186 | ## Next Steps
187 |
188 | - [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
189 | - [Site Monitoring](site-monitoring.md)
190 | - [Custom Domains](custom-domains.md)
191 | - [Troubleshooting](troubleshooting.md)
192 |
```
--------------------------------------------------------------------------------
/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/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/how-to/performance-optimization.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | documcp:
3 | last_updated: "2025-11-20T00:46:21.953Z"
4 | last_validated: "2025-12-09T19:41:38.584Z"
5 | auto_updated: false
6 | update_frequency: monthly
7 | validated_against_commit: 306567b32114502c606244ad6c2930360bcd4201
8 | ---
9 |
10 | # How to Optimize Documentation Deployment Performance
11 |
12 | This guide shows you how to optimize your DocuMCP deployment process for faster builds and better deployment success rates.
13 |
14 | ## Quick Setup
15 |
16 | ```bash
17 | # Analyze deployment performance:
18 | "analyze my deployment performance and provide optimization recommendations"
19 | ```
20 |
21 | ## Deployment Performance Overview
22 |
23 | DocuMCP tracks deployment performance metrics to help you optimize your documentation build process:
24 |
25 | ### Key Metrics
26 |
27 | - **Build Time**: Time taken for documentation generation
28 | - **Deployment Success Rate**: Percentage of successful deployments
29 | - **SSG Performance**: Static site generator efficiency comparison
30 | - **Error Recovery**: Time to resolve deployment failures
31 |
32 | ### Performance Benefits
33 |
34 | - **Faster Deployments**: Reduced time from commit to live site
35 | - **Higher Success Rates**: More reliable deployment pipeline
36 | - **Better Developer Experience**: Quicker feedback cycles
37 | - **Reduced Resource Usage**: Optimized build processes
38 |
39 | ## Setup Methods
40 |
41 | ### Method 1: Deployment Performance Analysis
42 |
43 | ```bash
44 | # Analyze deployment performance:
45 | "analyze my deployment performance and provide optimization recommendations"
46 | ```
47 |
48 | This will:
49 |
50 | 1. Analyze current deployment metrics
51 | 2. Compare SSG build times
52 | 3. Identify deployment bottlenecks
53 | 4. Provide optimization recommendations
54 | 5. Track performance improvements
55 |
56 | ### Method 2: SSG Performance Comparison
57 |
58 | #### Step 1: Build Time Analysis
59 |
60 | ```bash
61 | # Analyze build performance:
62 | "compare build times across different static site generators"
63 | ```
64 |
65 | #### Step 2: Success Rate Optimization
66 |
67 | ```bash
68 | # Optimize deployment success:
69 | "analyze deployment failures and suggest improvements"
70 | ```
71 |
72 | #### Step 3: Performance Monitoring
73 |
74 | ```bash
75 | # Monitor deployment performance:
76 | "track my deployment performance over time"
77 | ```
78 |
79 | ## Deployment Optimization Techniques
80 |
81 | ### SSG Selection Optimization
82 |
83 | ```bash
84 | # Analyze SSG performance:
85 | "compare static site generator build times and success rates"
86 | ```
87 |
88 | #### SSG Performance Factors
89 |
90 | - **Build Speed**: Time to generate documentation
91 | - **Success Rate**: Reliability of builds
92 | - **Resource Usage**: Memory and CPU requirements
93 | - **Feature Support**: Compatibility with documentation needs
94 |
95 | ### Build Configuration Optimization
96 |
97 | ```typescript
98 | // Optimize build configuration for faster deployments
99 | const buildConfig = {
100 | // Use faster package managers
101 | packageManager: "pnpm", // or "yarn" for faster installs
102 |
103 | // Optimize Node.js version
104 | nodeVersion: "20", // Latest LTS for better performance
105 |
106 | // Configure build caching
107 | cache: {
108 | enabled: true,
109 | strategy: "aggressive",
110 | },
111 | };
112 | ```
113 |
114 | ### Deployment Pipeline Optimization
115 |
116 | ```bash
117 | # Optimize deployment pipeline:
118 | "analyze my deployment pipeline and suggest performance improvements"
119 | ```
120 |
121 | #### Pipeline Best Practices
122 |
123 | - **Parallel Processing**: Run independent tasks concurrently
124 | - **Build Caching**: Cache dependencies and build artifacts
125 | - **Incremental Builds**: Only rebuild changed content
126 | - **Resource Allocation**: Optimize memory and CPU usage
127 |
128 | ## Troubleshooting
129 |
130 | ### Common Issues
131 |
132 | **Problem**: Slow deployment builds
133 | **Solution**: Analyze SSG performance and switch to faster alternatives
134 |
135 | **Problem**: Frequent deployment failures
136 | **Solution**: Review error patterns and optimize build configurations
137 |
138 | **Problem**: Inconsistent build times
139 | **Solution**: Enable build caching and optimize dependencies
140 |
141 | **Problem**: Resource exhaustion during builds
142 | **Solution**: Optimize memory usage and build parallelization
143 |
144 | ### Performance Debugging
145 |
146 | ```bash
147 | # Debug deployment performance issues:
148 | "analyze my deployment bottlenecks and suggest optimizations"
149 | ```
150 |
151 | ## Best Practices
152 |
153 | ### Deployment Performance Guidelines
154 |
155 | 1. **Choose Fast SSGs**: Use performance data to select optimal static site generators
156 | 2. **Enable Caching**: Implement build caching for faster subsequent deployments
157 | 3. **Optimize Dependencies**: Keep dependencies minimal and up-to-date
158 | 4. **Monitor Build Times**: Track deployment performance over time
159 | 5. **Use Analytics**: Leverage deployment analytics for optimization decisions
160 |
161 | ### Build Optimization Strategies
162 |
163 | 1. **Incremental Builds**: Only rebuild changed content when possible
164 | 2. **Parallel Processing**: Run independent build tasks concurrently
165 | 3. **Resource Management**: Optimize memory and CPU usage during builds
166 | 4. **Dependency Caching**: Cache node_modules and build artifacts
167 | 5. **Build Environment**: Use optimized build environments and Node.js versions
168 |
169 | ## Deployment Analytics Tools
170 |
171 | ### Built-in DocuMCP Analytics
172 |
173 | - **Build time tracking**: Monitor deployment speed over time
174 | - **Success rate analysis**: Track deployment reliability
175 | - **SSG performance comparison**: Compare static site generator efficiency
176 | - **Failure pattern analysis**: Identify common deployment issues
177 |
178 | ### MCP Tools Available
179 |
180 | - `analyze_deployments`: Get comprehensive deployment performance analytics
181 | - `deploy_pages`: Track deployment attempts and build times
182 | - `recommend_ssg`: Get performance-based SSG recommendations
183 |
184 | ## Next Steps
185 |
186 | - [Deploy Pages](../reference/mcp-tools.md#deploy_pages)
187 | - [Analytics Setup](analytics-setup.md)
188 | - [Site Monitoring](site-monitoring.md)
189 | - [Troubleshooting](troubleshooting.md)
190 |
```