Arch Drawing Analyzer

What This Is

An MCP server that lets Claude read and analyze large architectural drawing PDFs (permit sets, construction documents, etc.) that are too big to upload directly. It works by slicing PDFs into manageable chunks — either as extracted PDF pages or rendered PNG images — and bridging them into Claude's environment via the Filesystem connector.

Supports local files and authenticated SharePoint downloads (via Microsoft Graph API with device code auth).

System Components

1. arch-drawing-analyzer (MCP Server)

Install location: %LOCALAPPDATA%\arch-design-mcp

On Windows this expands to C:\Users\{username}\AppData\Local\arch-design-mcp. Per-user, no admin rights required.

A Python MCP server running over stdio transport. Provides seven tools:

Tool	Purpose	Speed
process_pdf	Load a PDF (local path, SharePoint link, or URL), return metadata + session_id	Instant
save_pages	Extract a page range to a new PDF file on disk	Instant
save_pages_as_images	Render a page range as PNG files on disk	~1-2 sec/page
get_pages	Return page content as base64 (PDF or PNG) in the tool result	Instant (PDF) / slow (images)
search_pdf	Search for text across all pages, returns page numbers + context	Fast (~1-5 sec for 250 pages)
get_analysis_prompt	Return the analysis prompt template	Instant
cleanup_session	Delete temp files for a session	Instant

Source files:

File	Purpose
server.py	MCP tool definitions, session management, FastMCP entry point
pdf_processor.py	PDF inspection (pypdf), page extraction, image rendering (PyMuPDF), text search
downloader.py	Unauthenticated URL download with logging
graph_auth.py	Microsoft Graph device code authentication, token caching/refresh
graph_downloader.py	Authenticated SharePoint file download via Graph API
pyproject.toml	Dependencies and Python version
.env	Azure AD credentials (not committed to git)

2. Filesystem Connector (Claude Desktop Built-in)

Provides copy_file_user_to_claude which bridges files from the user's machine into Claude's environment. After save_pages_as_images writes PNGs to disk, the Filesystem connector copies them to /mnt/user-data/uploads/ where Claude can view them.

Required allowed directories:

• %LOCALAPPDATA%\arch-design-mcp — server source + pages/ output directory

3. Output Directory

All saved pages and images go to %LOCALAPPDATA%\arch-design-mcp\pages\ by default. This keeps output contained within the Filesystem connector's allowed root. All tools accept an optional output_dir parameter to override this.

---

Installation

Prerequisites

• Python 3.13+ (via uv)
• Claude Desktop with Filesystem connector enabled
• Azure AD app registration (for SharePoint access — see SharePoint Setup below)

No external binaries (Poppler, etc.) are required. PyMuPDF handles all PDF rendering natively.

Step 1: Clone the Project

cd %LOCALAPPDATA%
git clone <repo-url> arch-design-mcp
cd arch-design-mcp

Step 2: Install Dependencies

uv sync

This installs from pyproject.toml:

Package	Purpose
fastmcp	MCP server framework
httpx	Async HTTP client for URL downloads
pymupdf	PDF rendering and text search (no external binaries)
pypdf	Fast PDF page extraction (no rendering)
msal	Microsoft Authentication Library (device code flow)
python-dotenv	Load Azure credentials from .env file

Step 3: Register in Claude Desktop

Add to your Claude Desktop config file (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "arch-drawing-analyzer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\arch-design-mcp",
        "python",
        "-m",
        "server"
      ]
    }
  }
}

Replace YOUR_USERNAME with your Windows username. The JSON config does not expand environment variables.

Merge this into any existing mcpServers block — don't replace the whole file if you have other servers configured.

Step 4: Configure Filesystem Connector

In Claude Desktop, add %LOCALAPPDATA%\arch-design-mcp to the Filesystem connector's allowed directories.

---

SharePoint Setup (Optional)

Required only if you want to pass SharePoint links directly to process_pdf instead of downloading files manually first.

Azure AD App Registration

1. Go to Azure Portal → App registrations → find or create SP-MCP
2. API Permissions — add these Microsoft Graph delegated permissions:

Permission	Type	Purpose
User.Read	Delegated	Basic sign-in
Files.Read.All	Delegated	Read files the user can access
Sites.Read.All	Delegated	Resolve SharePoint sharing links

3. Click "Grant admin consent for {org}" after adding permissions
4. Go to Authentication → Advanced settings → set "Allow public client flows" to Yes (required for device code flow)
5. Copy the Application (client) ID and Directory (tenant) ID from the Overview page

Configure Credentials

cd %LOCALAPPDATA%\arch-design-mcp
copy .env.example .env

Edit .env:

SP_MCP_CLIENT_ID=your-actual-client-id
SP_MCP_TENANT_ID=your-actual-tenant-id

No client secret is needed. The device code flow uses a "public client" — no secrets stored on user machines.

First Authentication

Before using SharePoint links, authenticate once by opening a terminal and running:

cd %LOCALAPPDATA%\arch-design-mcp
uv run python -m graph_auth

This will automatically open your browser to the Microsoft sign-in page with the device code pre-filled. Just sign in with your Tocci account. The terminal will confirm:

Opening browser for sign-in...
Waiting for sign-in to complete...

Authenticated as: [email protected]
Token cached at: C:\Users\psavine\.arch-design-mcp-token-cache.json
You can now use SharePoint links in Claude.

The token refreshes silently for ~90 days. If it expires, Claude will tell you to run the auth command again.

To clear the token cache: uv run python -m graph_auth --clear

Security Notes

• Delegated permissions only — the server can only access files the signed-in user already has permission to view. No tenant-wide escalation.
• No client secret — nothing sensitive stored on the machine beyond a refresh token.
• No open ports — all auth happens via browser redirect, not a local server.
• Token cache — stored in the user's home directory, scoped to that user.

---

Usage Workflows

Workflow A: Visual Analysis (Claude reads the drawings)

The primary workflow. Claude renders specific pages as PNG images, copies them to its environment, and views them.

1. process_pdf("c:\path\to\drawings.pdf")
   → session_id, 255 pages, 69 MB

2. save_pages_as_images(session_id, start_page=1, end_page=1, dpi=150)
   → %LOCALAPPDATA%\arch-design-mcp\pages\page_001.png (707 KB)

3. Filesystem:copy_file_user_to_claude → copies PNG to Claude's environment

4. Claude views the drawing

Limits: 1-3 pages at a time for arch E-size (36"x24") sheets at 150 DPI. Each page is ~300-700 KB as PNG.

Workflow B: Text Search (find pages without rendering)

Use search_pdf to locate specific content across all pages, then render only the relevant ones.

1. process_pdf("c:\path\to\drawings.pdf")
   → session_id, 255 pages

2. search_pdf(session_id, query="generator")
   → 3 matches: pages 178, 180, 195 with context snippets

3. save_pages_as_images(session_id, start_page=178, end_page=178)
   → render only the relevant sheet

Works best on PDFs with embedded text (specifications, schedules, title blocks). Architectural vector drawings have limited searchable text.

Workflow C: Drawing Index Strategy

For large sets (100+ pages), don't render every page. Instead:

1. Render pages 2-4 to find the drawing index/sheet list
2. Identify sheet numbers for the discipline you need
3. Binary-search or text-search to the right page range
4. Render only the target sheets

Workflow D: PDF Extraction (for archiving or re-upload)

Fast page extraction without image rendering.

1. process_pdf("c:\path\to\drawings.pdf")
   → session_id, 255 pages

2. save_pages(session_id, start_page=1, end_page=10)
   → %LOCALAPPDATA%\arch-design-mcp\pages\drawings_p1-10.pdf (2 MB)

Workflow E: SharePoint Links

Pass SharePoint sharing links directly — the server authenticates and downloads automatically.

1. process_pdf("https://toccibuilding.sharepoint.com/:b:/s/24061-SouthShore/...")
   → authenticates via cached token, downloads, returns session_id

---

Configuration

Logging

Configured at the top of server.py. Logs go to stderr (doesn't interfere with MCP stdio transport).

LOG_LEVEL = logging.DEBUG   # DEBUG for full diagnostics, INFO for production

Image Rendering Defaults

Parameter	Default	Notes
dpi	150	Good balance for arch drawings. Use 100 for faster/smaller.
max_dimension	4096	Max pixels on longest side. Claude vision limit is ~4096.

A 36"x24" sheet at 150 DPI renders to ~5400x3600, then downscales to 4096x2730.

MCP Client Timeout

The Claude.ai MCP client has a ~60-120 second timeout per tool call. Keep image rendering to 1-3 pages per call.

---

Known Limitations

MCP Tool Result Size

Base64-encoded content in tool results is limited to ~1 MB. A single 36"x24" arch drawing exceeds this. Use save_pages_as_images (writes to disk) instead of get_pages(as_images=True) (returns base64).

Filesystem Bridge File Size

copy_file_user_to_claude fails on files larger than ~5 MB. Keep extracted PDF chunks to ~10 pages or use single-page image rendering.

PDF Text Extraction

Architectural drawings are mostly vector graphics with limited embedded text. PyMuPDF text extraction is better than pypdf on these files, but results are still sparse on heavily vector-based sheets. Use visual analysis for reading drawings.

Claude's PDF Handling

PDFs uploaded by the user in a chat message are rendered as images by the platform before Claude sees them. PDFs copied mid-conversation via copy_file_user_to_claude are NOT rendered — Claude sees raw bytes. That's why the PNG pipeline exists: render on the user's machine, copy the image, Claude views the image.

---

File Structure

%LOCALAPPDATA%\arch-design-mcp\
├── server.py              # MCP server — tool definitions, session management
├── pdf_processor.py       # PDF inspection, extraction, rendering (PyMuPDF), text search
├── downloader.py          # Unauthenticated URL download with logging
├── graph_auth.py          # Device code auth, token caching/refresh (MSAL)
├── graph_downloader.py    # SharePoint download via Graph API
├── pyproject.toml         # Python dependencies
├── .env.example           # Credential template
├── .env                   # Actual credentials (git-ignored)
├── .gitignore
├── pages/                 # Default output for saved pages and images
├── __init__.py
├── .python-version        # Python 3.13
└── uv.lock                # Locked dependency versions

Temp Files

Sessions create temp directories in %TEMP%\mcp_arch_{session_id}_*. Cleaned up by cleanup_session() or on server exit. Files in pages/ persist — clean up manually or add to a maintenance routine.

Token Cache

Stored at ~/.arch-design-mcp-token-cache.json. Delete to force re-authentication.

---

Deployment to Other Users

For non-technical users at Tocci:

1. Install uv — single binary, no Python install needed
2. Clone the repo to %LOCALAPPDATA%\arch-design-mcp
3. Run uv sync — installs everything including Python
4. Copy .env.example to .env, fill in the Azure app credentials (same Client ID/Tenant ID for all users)
5. Add the mcpServers config to %APPDATA%\Claude\claude_desktop_config.json (see Step 3 above — replace YOUR_USERNAME)
6. Add %LOCALAPPDATA%\arch-design-mcp to Filesystem connector allowed directories
7. First SharePoint use: run cd %LOCALAPPDATA%\arch-design-mcp && uv run python -m graph_auth in a terminal, follow the browser prompt once

No Poppler install, no PATH configuration, no external binaries, no admin rights needed.