analyze_project_with_metadata

Instructions

Implementation Reference

• src/index.ts:741-866 (handler)

  Main execution logic for the 'analyze_project_with_metadata' tool. Initializes .handoff_docs directory, creates default MD files if missing, analyzes content with remark, categorizes, generates metadata, finds related docs, updates search index, adds YAML frontmatter, and returns project status with git info.

      case "analyze_project_with_metadata": {
        const { projectPath } = request.params.arguments as { projectPath: string };
        const docsPath = `${projectPath}/.handoff_docs`;
  
        try {
          // First run the standard analyze_project workflow
          await fs.mkdir(docsPath, { recursive: true });
  
          // Initialize default documentation files if they don't exist
          for (const doc of DEFAULT_DOCS) {
            const filePath = `${docsPath}/${doc}`;
            try {
              await fs.access(filePath);
            } catch {
              const title = doc.replace(".md", "")
                .split(/[_-]/)
                .map(word => word.charAt(0).toUpperCase() + word.slice(1))
                .join(" ");
              await fs.writeFile(filePath, TEMPLATE_CONTENT.replace("{title}", title));
            }
          }
  
          // Reset state
          state = {
            currentFile: null,
            completedFiles: [],
            inProgress: false,
            lastReadFile: null,
            lastReadContent: null,
            continueToNext: false,
            metadata: {},
            contextCache: {},
            templateOverrides: {}
          };
  
          // Clear existing search index
          searchEngine.removeAll();
  
          // Now enhance each file with metadata and context
          for (const doc of DEFAULT_DOCS) {
            const filePath = `${docsPath}/${doc}`;
            const content = await fs.readFile(filePath, "utf8");
  
            // Use unified/remark to analyze content structure
            const analysis = await analyzeContent(content);
  
            // Use enhanced categorization
            const { category, tags } = categorizeContent(doc, content, analysis);
  
            // Generate metadata
            const metadata = {
              title: analysis.title || doc.replace(".md", "")
                .split(/[_-]/)
                .map(word => word.charAt(0).toUpperCase() + word.slice(1))
                .join(" "),
              category,
              tags,
              lastUpdated: new Date().toISOString()
            };
  
            // Update metadata for the file
            await updateMetadata(filePath, metadata);
  
            // Find and update related docs
            const relatedDocs = await findRelatedDocs(doc, projectPath);
            await updateMetadata(filePath, { relatedDocs });
  
            // Update search index with full content and metadata
            updateSearchIndex(doc, content, {
              ...metadata,
              relatedDocs
            });
  
            // Add structured front matter to content
            const enhancedContent = `---
  title: ${metadata.title}
  category: ${metadata.category}
  tags: ${metadata.tags.join(', ')}
  lastUpdated: ${metadata.lastUpdated}
  relatedDocs: ${relatedDocs.join(', ')}
  ---
  
  ${content}`;
  
            // Update file with enhanced content
            await fs.writeFile(filePath, enhancedContent);
          }
  
          // Get project info for additional context
          let gitInfo = {};
          try {
            gitInfo = {
              remoteUrl: execSync("git config --get remote.origin.url", { cwd: projectPath }).toString().trim(),
              branch: execSync("git branch --show-current", { cwd: projectPath }).toString().trim(),
              lastCommit: execSync("git log -1 --format=%H", { cwd: projectPath }).toString().trim()
            };
          } catch {
            // Not a git repository or git not available
          }
  
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({
                  message: "Documentation structure initialized with metadata and context",
                  docsPath,
                  files: DEFAULT_DOCS,
                  metadata: state.metadata,
                  gitInfo,
                  contextCache: {
                    timestamp: state.contextCache.timestamp,
                    ttl: CACHE_TTL
                  }
                }, null, 2)
              }
            ]
          };
        } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          throw new McpError(
            ErrorCode.InternalError,
            `Error initializing documentation with metadata: ${errorMessage}`
          );
        }
      }

• src/index.ts:404-417 (registration)

  Tool registration in ListToolsRequestSchema handler, including name, description, and input schema definition.

  {
    name: "analyze_project_with_metadata",
    description: "Analyze project structure, create initial documentation files, and enhance with metadata/context",
    inputSchema: {
      type: "object",
      properties: {
        projectPath: {
          type: "string",
          description: "Path to the project root directory"
        }
      },
      required: ["projectPath"]
    }
  },

• src/index.ts:407-416 (schema)

  Input schema definition for the tool, specifying projectPath as required string parameter.

  inputSchema: {
    type: "object",
    properties: {
      projectPath: {
        type: "string",
        description: "Path to the project root directory"
      }
    },
    required: ["projectPath"]
  }