Architect MCP Server

MCP server for comprehensive code documentation and architecture analysis using client-side LLM sampling.

Features

• codedocumentation tool: Performs thorough architecture analysis, generates Mermaid diagrams, and creates structured documentation
• ghcpdocumentor tool: Generates GitHub Copilot instruction files tailored to your project
• launchviewer tool: Launches an interactive web-based markdown documentation viewer
• searchSharePoint tool: Search across SharePoint sites for documents, pages, and content (requires Azure AD configuration)
• searchOneDrive tool: Search across OneDrive for Business files and folders (requires Azure AD configuration)

Quick Start

Basic Installation (Code Documentation Only)

npm install -g architect-mcp-server@latest

Configure your MCP client (VS Code or Claude Desktop):

{
  "mcpServers": {
    "architect": {
      "command": "architect-mcp-server"
    }
  }
}

With SharePoint/OneDrive Integration

For SharePoint and OneDrive search capabilities, you'll need Azure AD credentials:

{
  "mcpServers": {
    "architect": {
      "command": "architect-mcp-server",
      "env": {
        "MS_CLIENT_ID": "your-azure-app-client-id",
        "MS_TENANT_ID": "your-tenant-id-or-organizations",
        "AUTH": "device",
        "AUTO_LAUNCH_BROWSER": "true"
      }
    }
  }
}

See CONFIGURATION.md for detailed Azure AD setup instructions.

Architecture

The server uses a prompt-based architecture where tools load detailed prompt templates and return them to the MCP client. The client's LLM then executes the actual analysis, keeping the server lightweight and leveraging powerful client-side models.

Key Components:

• src/tools/ - Tool implementations (prompt orchestrators and system utilities)
• prompts/ - Detailed prompt templates with placeholders for dynamic content
• viewer/ - Bundled documentation viewer (Express.js web app)
• dist/ - Compiled TypeScript output

Tool: codedocumentation

Analyzes a codebase and generates comprehensive documentation including:

• System architecture diagrams (Mermaid)
• Project dependencies and structure
• Business logic and workflows
• Technical health assessment
• Stakeholder-specific documentation

Architecture: Loads prompts/CodeDocumentation.prompt.md, injects workspace path and focus areas, returns enhanced prompt to client LLM for execution.

Parameters

• workspacePath (required): Absolute path to the solution/workspace root
• focusAreas (optional): Array of specific areas to prioritize (e.g., ['architecture', 'business-logic'])

Example

// Tool invocation
{
  "workspacePath": "c:\\projects\\my-solution",
  "focusAreas": ["architecture", "dependencies"]
}

Output

Documentation is created in a .solutiondocs folder within the analyzed workspace.

Tool: ghcpdocumentor

Generates GitHub Copilot instruction files tailored to your project's architecture and tech stack. Creates:

• .github/copilot-instructions.md with project-wide guidance
• Specialized *.instructions.md files for languages, frameworks, and domains
• Precise glob patterns for file matching
• Implementation and adoption guides

Architecture: Loads prompts/GithubCopilotFilesGenerator.prompt.md, injects workspace path and architecture context, returns enhanced prompt to client LLM for execution.

Parameters

• workspacePath (required): Absolute path to the solution/workspace root
• architectureContext (optional): Brief architecture description (e.g., 'React + Node.js microservices')

Example

// Tool invocation
{
  "workspacePath": "c:\\projects\\my-app",
  "architectureContext": "React SPA with Express API and PostgreSQL"
}

Output

Instruction files are created in .github/ directory following GitHub Copilot's instruction file system conventions.

Tool: searchSharePoint

Searches across SharePoint sites, libraries, lists, and files using Microsoft Graph API.

Architecture: System utility tool that calls the SharePoint MCP search handlers with Device Flow authentication.

Prerequisites

• Azure AD application registration with Device Flow support
• Required scopes: Files.Read.All Sites.Read.All ExternalItem.Read.All
• Environment variables: MS_CLIENT_ID, MS_TENANT_ID

Parameters

• query (required): Search query string (max 1500 characters)
• maxResults (optional): Maximum results to return (default: 8, max: 25)
• filterExpression (optional): KQL filter expression for refinement
• resourceMetadata (optional): Additional metadata fields to include

Example

// Tool invocation
{
  "query": "project plan budget",
  "maxResults": 10,
  "filterExpression": "FileType:docx"
}

Authentication

First use triggers Device Flow authentication:

1. Server displays authentication URL and device code
2. User visits URL and enters code
3. Authentication completes and token is cached
4. Subsequent requests use cached token

Output

Returns JSON with retrievalHits array containing search results with titles, URLs, snippets, and relevance scores.

Tool: searchOneDrive

Searches across OneDrive for Business files and folders using Microsoft Graph API.

Architecture: System utility tool that calls the SharePoint MCP search handlers with Device Flow authentication.

Prerequisites

Same as searchSharePoint tool.

Parameters

Same as searchSharePoint tool.

Example

// Tool invocation
{
  "query": "quarterly report 2024",
  "maxResults": 5
}

Authentication

Same Device Flow process as searchSharePoint tool.

Output

Returns JSON with retrievalHits array containing search results with file metadata, URLs, content snippets, and relevance scores.

Tool: launchviewer

Launches the bundled Documentation Viewer web server to browse markdown documentation with an interactive tree interface. Perfect for viewing the .solutiondocs folder generated by the codedocumentation tool.

Architecture: System utility tool that spawns processes and manages the bundled Express.js web server.

Features

• 📁 Tree navigation with expandable/collapsible folders
• 📄 Full markdown rendering with syntax highlighting
• 📊 Mermaid diagram support
• 🎨 Clean, modern UI
• 🚀 Auto-installs dependencies on first run
• 🌐 Opens browser automatically

Parameters

• documentationPath (optional): Absolute path to the documentation folder to view
• port (optional): Port number for the server (default: 3000)

Example

// Launch viewer for specific documentation folder
{
  "documentationPath": "c:\\projects\\my-solution\\.solutiondocs",
  "port": 3000
}

// Or launch without path - user enters it in the browser UI
{}

Usage

1. Call the launchviewer tool after running codedocumentation
2. The server starts on http://localhost:3000 (or specified port)
3. Browser opens automatically
4. Enter the path to your .solutiondocs folder (or any folder with markdown files)
5. Browse the documentation tree and click files to view

Notes

• First run installs dependencies automatically (takes 30-60 seconds)
• Server runs until you close the MCP session or manually stop it
• Viewer is bundled with the MCP server - no separate installation needed

Tool: searchSharePoint

Search across SharePoint sites for documents, pages, and content. Returns ranked results with titles, URLs, and text snippets.

Architecture: Integrates with Microsoft Graph Copilot Retrieval API. Uses Device Flow authentication for simplicity.

Prerequisites

• Azure AD app registration with Microsoft Graph permissions
• MS_CLIENT_ID and MS_TENANT_ID environment variables configured
• See CONFIGURATION.md for setup instructions

Parameters

• query (required): Search query string (max 1500 characters)
• maxResults (optional): Maximum number of results (default: 8, max: 25)
• filterExpression (optional): KQL filter expression to refine results
• resourceMetadata (optional): Metadata fields to include (e.g., ['title', 'author'])

Example

{
  "query": "project architecture document",
  "maxResults": 10,
  "filterExpression": "FileType:docx"
}

Authentication Flow

First time use:

1. Tool returns authentication instructions with device code
2. Visit URL and enter the code to authenticate
3. Authentication is cached for future requests

Output

Returns JSON with search results including:

• Title and summary snippets
• URLs and file types
• Ranking scores
• Metadata (if requested)

Tool: searchOneDrive

Search across OneDrive for Business files and folders. Works identically to searchSharePoint but searches OneDrive content.

Parameters

Same as searchSharePoint:

• query (required)
• maxResults (optional)
• filterExpression (optional)
• resourceMetadata (optional, e.g., ['title', 'lastModifiedDateTime'])

Example

{
  "query": "meeting notes 2024",
  "maxResults": 5
}

Prompt-Based Architecture

This MCP server uses a unique prompt orchestrator design:

Prompt Orchestrator Tools

• codedocumentation and ghcpdocumentor are prompt orchestrators
• They load detailed prompt templates from prompts/*.prompt.md
• Inject user parameters (workspace paths, focus areas, etc.) using placeholders
• Return enhanced prompts to the MCP client's LLM for execution
• No analysis logic runs in the server - it's delegated to the client's powerful models

System Utility Tools

• launchviewer is a system utility tool
• Executes system operations (process spawning, file system checks)
• Returns status and instructions to the user

Modifying Prompts

To customize tool behavior, edit the prompt templates in prompts/:

1. CodeDocumentation.prompt.md - Contains the full analysis methodology
2. GithubCopilotFilesGenerator.prompt.md - Contains GitHub Copilot instruction generation logic

Placeholders used:

• {{workspacePath}} - Replaced with the actual workspace path
• {{focusAreasSection}} - Optional focus areas (codedocumentation)
• {{architectureContextSection}} - Optional architecture context (ghcpdocumentor)

Changes take effect immediately (no rebuild needed since prompts are loaded at runtime).

Troubleshooting

SharePoint/OneDrive Tools

"Configuration Required" Error

The SharePoint tools need Azure AD configuration. Add these environment variables to your MCP config:

{
  "env": {
    "MS_CLIENT_ID": "your-azure-app-client-id",
    "MS_TENANT_ID": "your-tenant-id-or-organizations",
    "AUTH": "device"
  }
}

See CONFIGURATION.md for detailed setup instructions.

Tool Hangs/Spins Forever

This usually means authentication is required. Check the console output (stderr) for device flow instructions:

• The tool will display a URL and code
• Visit the URL and enter the code
• Once authenticated, retry your request

Enable automatic browser opening: "AUTO_LAUNCH_BROWSER": "true"

Module Loading Errors

Ensure the server is built before running:

npm run build

Check that your MCP config points to the compiled dist/index.js, not src/index.ts.

General Issues

Server Not Starting

1. Check Node.js version (requires Node 18+)
2. Verify the path in your MCP config is correct
3. Look for error messages in the MCP client logs

Prompts Not Loading

Prompts are loaded from the prompts/ directory relative to the compiled code. If using a custom installation location, ensure the prompts/ folder is in the same directory as dist/.

Documentation Viewer Issues

First run installs dependencies automatically. If it fails:

cd viewer
npm install

Development & Contribution

Building from Source

git clone https://github.com/RajKumarShinh/ArchitectMCP.git
cd ArchitectMCP
npm install
npm run build

Modifying Prompts

The server uses a prompt-based architecture where analysis logic lives in .md files:

1. Prompt Templates: Located in prompts/ directory
2. Placeholders: Use {{variableName}} for dynamic content
3. Runtime Loading: Prompts are read at runtime, no rebuild required for changes

Adding New Tools

1. Create prompt template in prompts/YourTool.prompt.md
2. Add tool definition in src/tools/index.ts
3. Implement handler in src/tools/yourtool.ts
4. Update README.md and copilot-instructions.md

Publishing

Automated publish scripts handle version incrementing and publishing:

# Increment patch version and publish (1.0.3 -> 1.0.4)
npm run publish:patch

# Increment minor version and publish (1.0.3 -> 1.1.0)
npm run publish:minor

# Increment major version and publish (1.0.3 -> 2.0.0)
npm run publish:major

See PUBLISHING.md for detailed publishing guide.

Manual publishing:

npm version patch  # or minor/major
npm run build
npm publish

License

MIT