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

$3

``bash
npm install -g architect-mcp-server@latest
`

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

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

$3

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

`json
{
"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.

$3

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.

$3

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

$3

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

$3

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.

$3

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

$3

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

$3

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.

$3

- 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

$3

- 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

$3

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

$3

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

$3

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.

$3

Same as searchSharePoint tool.

$3

Same as searchSharePoint tool.

$3

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

$3

Same Device Flow process as searchSharePoint tool.

$3

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.

$3

- 📁 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

$3

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

$3

`typescript
// 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
{}
`

$3

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

$3

- 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.

$3

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

$3

- 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'])

$3

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

$3

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

$3

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.

$3

Same as searchSharePoint:
- query (required)
- maxResults (optional)
- filterExpression (optional)
- resourceMetadata (optional, e.g., ['title', 'lastModifiedDateTime'])

$3

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

Prompt-Based Architecture

This MCP server uses a unique prompt orchestrator design:

$3

- 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

$3

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

$3

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

$3

#### "Configuration Required" Error
The SharePoint tools need Azure AD configuration. Add these environment variables to your MCP config:

`json
{
"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:
`bash
npm run build
`

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

$3

#### 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:
`bash
cd viewer
npm install
`

Development & Contribution

$3

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

$3

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

$3

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

$3

Automated publish scripts handle version incrementing and publishing:

`bash

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:
`bash
npm version patch # or minor/major
npm run build
npm publish
``

License

MIT