Inspect Project

Instructions

Implementation Reference

• src/tools/inspectProject.js:25-120 (handler)

  Main inspect_project tool handler. Validates project path, scans directory tree, detects languages/frameworks/entry points/project type/dependencies/config files, and returns comprehensive snapshot.

  export async function inspectProject({ path: projectPath, maxDepth = 3, includeHidden = false }) {
      // Validate path exists
      try {
          const stats = await fs.stat(projectPath);
          if (!stats.isDirectory()) {
              return createError(ErrorCodes.PATH_NOT_DIRECTORY);
          }
      } catch (err) {
          if (err.code === 'ENOENT') {
              return createError(ErrorCodes.PATH_NOT_FOUND);
          }
          if (err.code === 'EACCES') {
              return createError(ErrorCodes.ACCESS_DENIED);
          }
          return createError(ErrorCodes.SCAN_ERROR, err.message);
      }
  
      try {
          // Scan directory tree
          const { files, structure, truncated } = await scanTree(projectPath, {
              maxDepth,
              includeHidden
          });
  
          // Parse dependencies
          const dependencies = await parseDependencies(projectPath, files);
  
          // Detect languages
          const languages = await detectLanguages(projectPath, files);
  
          // Detect frameworks
          const frameworks = await detectFrameworks(projectPath, files, languages, dependencies);
  
          // Detect entry points
          const entryPoints = await detectEntryPoints(projectPath, files, languages);
  
          // Classify project type
          const projectType = await classifyProjectType(frameworks, languages, files, projectPath);
  
          // Get structure summary
          const structureSummary = getStructureSummary(structure, files);
  
          // Find config files
          const sigs = await getSignatures();
          const configFiles = files.filter(f =>
              sigs.configFiles.some(cf => path.basename(f) === cf || f.endsWith(cf))
          );
  
          // Build result (omit empty fields)
          const result = {
              project: {
                  language: languages.map(l => l.name),
                  type: projectType.type,
                  confidence: projectType.confidence
              }
          };
  
          if (frameworks.length > 0) {
              result.frameworks = frameworks.map(f => ({
                  name: f.name,
                  confidence: f.confidence
              }));
          }
  
          if (entryPoints.length > 0) {
              result.entryPoints = entryPoints;
          }
  
          if (Object.keys(structureSummary).length > 0) {
              result.structureSummary = structureSummary;
          }
  
          if (dependencies.primary.length > 0 || dependencies.dev.length > 0) {
              result.dependencies = {};
              if (dependencies.primary.length > 0) {
                  result.dependencies.primary = dependencies.primary;
              }
              if (dependencies.dev.length > 0) {
                  result.dependencies.dev = dependencies.dev;
              }
          }
  
          if (configFiles.length > 0) {
              result.configFiles = configFiles;
          }
  
          if (truncated) {
              result.truncated = true;
          }
  
          return result;
  
      } catch (err) {
          return createError(ErrorCodes.SCAN_ERROR, err.message);
      }
  }

• src/tools/inspectProject.js:15-19 (schema)

  Input schema for the inspect_project tool using Zod validation.

  export const inspectProjectSchema = {
      path: z.string().describe("Path to the project directory to inspect"),
      maxDepth: z.number().optional().default(3).describe("Maximum depth to scan (default: 3)"),
      includeHidden: z.boolean().optional().default(false).describe("Include hidden files and directories")
  };

• index.js:19-37 (registration)

  MCP server tool registration for inspect_project, using imported schema and handler.

  server.registerTool(
      "inspect_project",
      {
          title: "Inspect Project",
          description: "Analyze a project directory and return a complete snapshot including detected languages, frameworks, entry points, structure summary, and dependencies. This is the primary tool for understanding a project.",
          inputSchema: inspectProjectSchema
      },
      async (params) => {
          const result = await inspectProject(params);
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(result, null, 2),
                  },
              ],
          };
      }
  );

• server.js:32-44 (registration)

  Tool definition/registration for HTTP/SSE server, with inline schema and imported handler.

  inspect_project: {
      name: "inspect_project",
      description: "Analyze a project directory and return a complete snapshot including detected languages, frameworks, entry points, structure summary, and dependencies. This is the primary tool for understanding a project.",
      inputSchema: {
          type: "object",
          properties: {
              path: { type: "string", description: "Path to the project directory to inspect" },
              maxDepth: { type: "number", description: "Maximum depth to scan (default: 3)" },
              includeHidden: { type: "boolean", description: "Include hidden files and directories" }
          },
          required: ["path"]
      },
      handler: inspectProject

• api/index.js:10-13 (registration)

  Simple tool mapping for Vercel serverless API handler, mapping 'inspect_project' to inspectProject function.

  const tools = {
      inspect_project: inspectProject,
      detect_stack: detectStack,
      list_key_files: listKeyFiles