AppSage

AppSage is a comprehensive software analysis and visualization platform that helps developers understand and analyze their codebases through metrics, documentation generation, and interactive visualizations.

Table of Contents

• Prerequisites
• Building the Project
• Installation
• Basic Usage
• MCP Server Integration
• Security
• License

Prerequisites

Prerequisites to Build

• .NET core SDK 10.0+: Required to build the AppSage .NET applications

  • Download from Microsoft .NET Downloads
  • Verify installation: dotnet --version

• PowerShell 5.1+ or PowerShell Core 6+: Required for build scripts

  • Windows: Built-in PowerShell 5.1 or install PowerShell Core
  • Cross-platform: Install PowerShell Core

• Node.js 16+: Required for VS Code extension development

  • Download from Node.js
  • Verify installation: node --version

• TypeScript 4.9+: Required for VS Code extension

  • Install globally: npm install -g typescript

Prerequisites to Run

• .NET Runtime 10.0+: Required to run AppSage applications
• Visual Studio Code latest version: Required for the AppSage VS Code extension
• Git: Required for repository analysis features

Building the Project

To build AppSage from source:

1. Clone the repository:

   git clone https://github.com/awslabs/appsage.git
   cd appsage

2. Build the complete project using the installer creation script:

   cd src\Installer
   .\Create-Installer.ps1 -Configuration Release

   Optional parameters:

   • -Configuration Debug|Release (default: Release)
   • -Version x.y.z (uses version from Directory.Build.props if not specified)

   This script will:

   • Clean old build artifacts
   • Build the .NET solution
   • Publish the AppSage.Run application
   • Build the VS Code extension
   • Create a packaged installer zip file

3. Build output: The installer will be created as AppSage-Installer-v{version}.zip in the src/Installer directory.

Installation

Installing from the Built Package

1. Extract the installer:

   Expand-Archive -Path "AppSage-Installer-v{version}.zip" -DestinationPath "AppSage-Installer"
   cd AppSage-Installer

2. Run the installation script:

   .\Install-AppSage.ps1

   Installation options:

   # Install to default location (C:\Program Files\AppSage)
   .\Install-AppSage.ps1
   
   # Install to custom location
   .\Install-AppSage.ps1 -InstallPath "C:\Tools\AppSage"
   
   # Install for current user only
   .\Install-AppSage.ps1 -Scope User

3. Verify installation:

   appsage --version

Installing the VS Code Extension

After running the installer, install the VS Code extension:

1. From the installer package:

   code --install-extension appsage-vscode-extension-{version}.vsix

2. Alternative manual installation:

   • Open VS Code
   • Press Ctrl+Shift+P and type "Extensions: Install from VSIX"
   • Select the appsage-vscode-extension-{version}.vsix file from the installer

Basic Usage

Initial Setup

1. Initialize a new AppSage workspace:

   mkdir MyProject
   cd MyProject
   appsage init

   This creates the AppSage workspace structure with:

   • Repository/ - Source code repositories folder (each repository in separate subfolder)
   • Template/ - Analysis templates for bulk generation
   • ProviderOutput/ - Tooling output after code scanning
   • MCPServerOutput/ - Files generated by MCP server queries
   • TemplateBasedAnalysisOutput/ - Template-based analysis results
   • Logs/ - Application logs
   • Extension/ - Extension management folder
     • Packages/ - Extension NuGet packages (.nupkg, .snupkg)
     • Install/ - Installed extensions (one folder per extension)
   • .appsage/ - Hidden configuration folder
     • appsage.json - Main workspace configuration file
     • cache/ - Internal caching directory
   • .vscode/ - VS Code workspace configuration
     • mcp.json - MCP server configuration

2. Add repositories to analyze:

   # Copy or clone repositories into the Repository folder
   cd Repository
   git clone https://github.com/your-org/your-repo.git
   # Or copy existing repositories here

3. Run AppSage analysis:

   # Return to workspace root
   cd ..
   
   # Run extension analysis
   appsage extension run

Common Commands

• Initialize workspace: appsage init
• Run all extensions: appsage extension run
• List available extensions: appsage extension list

Viewing Results

AppSage generates various output files that can be viewed with the VS Code extension:

• Graph files (.appsagegraph): Visualize code relationships and dependencies
• Table files (.appsagetable): View metrics and analysis data in tabular format

MCP Server Integration

AppSage includes a Model Context Protocol (MCP) server for integration with AI tools and VS Code.

Starting the MCP Server

1. Navigate to your AppSage workspace:

   cd path\to\your\appsage\workspace

2. Start the MCP server:

   appsage mcp start

   The server will start on http://localhost:44000/mcp by default.

Connecting from VS Code

1. Install an MCP-compatible VS Code extension (such as Claude Dev or similar)

2. Configure the MCP connection:

   {
     "mcpServers": {
       "appsage": {
         "command": "appsage",
         "args": ["mcp", "start"],
         "transport": "http",
         "url": "http://localhost:44000/mcp"
       }
     }
   }

Example MCP Queries

Once connected, you can query AppSage through the MCP interface:

Analyze code metrics:

@appsage Create a table listing all the methods and classes used in the project. 

****:

@appsage Do an effort estimate to migrate SQL server classes to PostgreSQL

Visualize dependencies:

@appsage Create a dependency graph for the classes with more than 1 method. 

The MCP server provides access to:

• Tools: Callable functions for running analyses and generating reports
• Prompts: Pre-built templates for common analysis tasks
• Resources: Read-only access to workspace data and metrics

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.