akij-hr-data-mcp

A production-ready, read-only, remote Model Context Protocol (MCP) server that exposes a single Google Drive folder — the AKIJ HR DATA repository — to MCP-compatible clients over modern Streamable HTTP transport.

It is a general-purpose Drive MCP: it handles XLSX, XLS, CSV, PDF, DOCX, TXT, images, and native Google Docs/Sheets/Slides files — not an Excel-only tool.

---

1. What this project does

• Connects to Google Drive using a service account (no user OAuth flow, no browser login).
• Restricts every operation to one configured folder (GOOGLE_DRIVE_FOLDER_ID) and its subfolders. Files outside that tree are never returned, even if the service account could technically see them.
• Exposes 11 MCP tools for discovering and reading files (list, search, metadata, content, and format-specific extraction for Excel/CSV/PDF/DOCX).
• Runs as a standard Node/Express HTTP server with a single POST /mcp endpoint (Streamable HTTP transport) and a GET /health endpoint, deployable to Render (or any Node host) so it keeps running when your PC is off.
• Enforces API-key authentication on every MCP request.
• Is strictly read-only — there is no code path that can upload, edit, delete, rename, move, or share a Drive file, or change permissions.

2. Architecture

Google Drive (AKIJ HR DATA folder)
        ↓ Drive API v3 (read-only scope)
Google Service Account (GCP_KEY_BASE64)
        ↓
GoogleDriveClient (src/google-drive.ts) — enforces folder-tree scope
        ↓
MCP Server (src/mcp-server.ts) — 11 tools, Zod-validated inputs
        ↓
Express app (src/index.ts) — API-key auth, Streamable HTTP transport
        ↓ POST /mcp  (stateless, one transport per request)
        ↓
Render (always-on host)
        ↓ HTTPS
Remote MCP Clients (Claude, other MCP-compatible clients)

The server is stateless: each POST /mcp request gets its own McpServer + StreamableHTTPServerTransport instance (sessionIdGenerator: undefined), so there's no session affinity requirement and it scales horizontally on Render without sticky sessions.

Project structure

src/
  index.ts            Express app: /health, /mcp, startup
  config.ts           Environment variable loading/validation
  auth.ts             API-key authentication middleware
  google-auth.ts      Decodes GCP_KEY_BASE64 → JWT auth client
  google-drive.ts      Drive API client with folder-scope enforcement
  mcp-server.ts        McpServer wiring: registers all 11 tools

  tools/
    files.ts           list_files, get_file_metadata, get_file_content, list_supported_files
    search.ts           search_files, search_repository
    excel.ts            inspect_excel, read_excel_sheet
    csv.ts               read_csv
    pdf.ts               extract_pdf_text
    docx.ts              extract_docx_text

  utils/
    errors.ts            Typed AppError hierarchy + safe error serialization
    limits.ts            Size/row/timeout/pagination limits
    mime-types.ts         MIME → file-category classification

tests/                  Jest test suite (46 tests, 10 suites)
.env.example
.gitignore
render.yaml             Render Blueprint (optional one-click deploy)
README.md
package.json
tsconfig.json
jest.config.cjs

3. Prerequisites

• Node.js 20+ and npm
• A Google Cloud project with the Google Drive API enabled
• A Google service account with Viewer access shared on the AKIJ HR DATA Drive folder
• A GitHub account (for deploying to Render from a repo)
• A Render account

4. Installation

npm install

5. Environment variables

Variable	Required	Description
PORT	no (default 10000)	Port the HTTP server listens on. Render sets this automatically.
GOOGLE_DRIVE_FOLDER_ID	yes	The Drive folder ID this MCP is restricted to.
GCP_KEY_BASE64	yes	Base64-encoded service-account JSON key.
API_KEYS	yes	Comma-separated list of valid API keys for POST /mcp.

See .env.example for the template (no real secrets are committed).

6. Google Cloud setup

1. Go to console.cloud.google.com and select/create a project.
2. APIs & Services → Library → enable Google Drive API.
3. APIs & Services → Credentials → Create Credentials → Service Account.
4. Give it a name (e.g. akij-hr-data-mcp), no project-level IAM role is needed.
5. Open the new service account → Keys → Add Key → Create new key → JSON. This downloads a gcp-key.json file — do not commit this file.
6. Note the service account's email address (looks like akij-hr-data-mcp@your-project.iam.gserviceaccount.com).

7. Google Drive permissions

1. Open the AKIJ HR DATA folder in Google Drive (folder ID 1oxYLPcC9MPVuxsbeP0kGgYhLmkxt0w2o).
2. Click Share, paste the service account's email, and grant Viewer access.
3. Do not grant Editor/Owner — this server never writes to Drive, so Viewer is sufficient and safer.

8. Local setup

npm install
cp .env.example .env
# fill in GOOGLE_DRIVE_FOLDER_ID, GCP_KEY_BASE64, API_KEYS in .env
npm run dev

npm run dev runs the TypeScript server directly with tsx watch (no build step needed for local iteration).

9. Generating GCP_KEY_BASE64

You should never paste the raw service-account JSON into chat, source code, or .env.example. Generate the base64 value locally from your downloaded gcp-key.json and put it only in your local .env (gitignored) or in Render's environment variable settings.

PowerShell:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\Downloads\gcp-key.json")) | Set-Clipboard

This reads the key file and copies the base64 string directly to your clipboard — paste it as the value of GCP_KEY_BASE64 in .env (locally) or in the Render dashboard (for deployment). Adjust the path if gcp-key.json isn't in your Downloads folder.

If you'd rather print it to the terminal instead of the clipboard:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\Downloads\gcp-key.json"))

10. Local testing

Start the server:

npm run dev

Check health:

curl http://localhost:10000/health

Call an MCP tool (example: list_files) with curl, using the initialize → tools/call sequence, or point any Streamable-HTTP-capable MCP client at http://localhost:10000/mcp with header X-Api-Key: <one of your API_KEYS>.

11. Building

npm run build

Compiles src/ (TypeScript, NodeNext ESM) to dist/. Run npm run typecheck to type-check without emitting files.

Run the test suite:

npm test

This runs Jest in-band (46 tests across 10 suites: config, auth, Google auth, Drive folder-scope enforcement, all 11 tools, and the /health//mcp HTTP endpoints).

12. GitHub setup

git init
git add .
git commit -m "Initial commit: akij-hr-data-mcp"
git branch -M main
git remote add origin https://github.com/<your-username>/akij-hr-data-mcp.git
git push -u origin main

.env, gcp-key.json, *.pem, and *.key are already gitignored — verify with git status before committing that nothing secret is staged.

13. Render deployment

1. Go to render.com → New → Web Service.
2. Connect your GitHub repo (akij-hr-data-mcp).
3. Render will detect render.yaml (Blueprint) automatically, or configure manually:
   • Build Command: npm install && npm run build
   • Start Command: npm start
   • Health Check Path: /health
4. Add the environment variables (section 14) in the Render dashboard — never commit them.
5. Deploy. Render builds, starts the service, and keeps it running independent of your PC.

14. Render environment variables

Set these in Render → your service → Environment:

PORT=10000
GOOGLE_DRIVE_FOLDER_ID=1oxYLPcC9MPVuxsbeP0kGgYhLmkxt0w2o
GCP_KEY_BASE64=<paste the base64 string from step 9>
API_KEYS=<comma-separated production keys, e.g. key-abc123,key-def456>

Generate strong random API keys, e.g.:

[Convert]::ToBase64String([Guid]::NewGuid().ToByteArray()) -replace '[+/=]',''

15. Health endpoint

GET /health

{ "status": "ok", "timestamp": "2026-08-17T12:00:00.000Z" }

No authentication required; exposes no secrets or internal state.

16. MCP endpoint

POST /mcp

• Implements the MCP Streamable HTTP transport (@modelcontextprotocol/sdk StreamableHTTPServerTransport), stateless (sessionIdGenerator: undefined) — no SSE-only fallback.
• Requires authentication: Authorization: Bearer <API_KEY> or X-Api-Key: <API_KEY> header.
• GET /mcp and DELETE /mcp return 405 — this server doesn't maintain sessions or support the optional SSE stream.

17. Connecting the remote MCP to clients

Once deployed, your MCP endpoint is:

https://<your-render-service>.onrender.com/mcp

For MCP clients that support remote/HTTP servers, add a server entry with:

• URL: https://<your-render-service>.onrender.com/mcp
• Transport: Streamable HTTP
• Headers: X-Api-Key: <one of your API_KEYS> (or Authorization: Bearer <API_KEY>)

Example generic client config:

{
  "mcpServers": {
    "akij-hr-data": {
      "url": "https://<your-render-service>.onrender.com/mcp",
      "headers": {
        "X-Api-Key": "<API_KEY>"
      }
    }
  }
}

18. Security

• Read-only: no upload/delete/edit/rename/move/share/permission tool exists in this codebase.
• Folder-scoped: GoogleDriveClient.assertFileInScope walks each file's parents chain up to the configured root before any metadata or content is returned; files outside the tree raise a ForbiddenError.
• API-key auth: every POST /mcp request is checked against API_KEYS with a timing-safe comparison (crypto.timingSafeEqual). Missing/invalid keys get 401.
• Credentials never logged or returned: the decoded service-account JSON stays inside google-auth.ts; no tool, log line, or error message can surface it. Error responses are passed through toSafeErrorMessage, which strips stack traces and raw upstream error bodies.
• Size/output limits: downloads are capped (LIMITS.MAX_DOWNLOAD_BYTES / MAX_PARSE_BYTES), text extraction is truncated (MAX_TEXT_OUTPUT_CHARS), rows are paginated (DEFAULT_ROW_LIMIT/MAX_ROW_LIMIT), and every outbound Google API call has a timeout (GOOGLE_API_TIMEOUT_MS).
• Extensible auth: req.identity is a small, stable shape ({ keyId }) designed so a future per-user-key, OAuth, or role-based authorization layer can attach richer claims without changing every call site.
• Known dependency advisory: the xlsx (SheetJS) package used for legacy .xls parsing has a published high-severity advisory (prototype pollution / ReDoS). It's used only for internal, access-controlled files from your own Drive folder (not arbitrary internet uploads) and files are size-capped before parsing. Run npm audit periodically and consider replacing it if a patched release becomes available.

Security checklist

• [ ] gcp-key.json never committed to git
• [ ] .env never committed to git
• [ ] API_KEYS set to strong, random values in Render (not the local dev value)
• [ ] Service account has Viewer only on the Drive folder
• [ ] GOOGLE_DRIVE_FOLDER_ID matches the intended repository folder
• [ ] Render environment variables set directly in the dashboard, never in render.yaml's committed values

19. Troubleshooting

Symptom	Cause	Fix
Server exits immediately with a ConfigError	Missing/invalid env var	Check the exact variable named in the error message against section 5
GCP_KEY_BASE64 is not valid base64	Wrong file encoded, or copy/paste truncated the string	Regenerate with the PowerShell command in section 9
403 Forbidden from Drive API	Service account not shared on the folder, or shared with the wrong email	Re-check section 7; confirm the client_email in your key matches
File ... is outside the configured repository folder	You passed a file_id that isn't inside GOOGLE_DRIVE_FOLDER_ID's tree	Use list_supported_files or search_repository to get valid IDs
401 on every /mcp call	Missing/incorrect API key	Send X-Api-Key or Authorization: Bearer <key> matching one entry in API_KEYS
FILE_TOO_LARGE error	File exceeds the configured byte limit	This is intentional; large files are rejected rather than loaded fully into memory (see src/utils/limits.ts)
Render service sleeps / cold-starts slowly	Free/starter Render plans idle after inactivity	Upgrade the Render plan, or accept the cold-start delay on the first request
Tests hang for minutes locally	ts-jest type-checking full googleapis types under parallel workers	Already mitigated: npm test runs Jest with --runInBand; don't remove that flag

---

Remaining manual steps (only you can do these)

1. Generate GCP_KEY_BASE64 from your downloaded gcp-key.json (section 9) and put it in your local .env for testing.
2. Share the AKIJ HR DATA Drive folder with your service account's email as Viewer (section 7).
3. Run locally (npm run dev) and confirm GET /health and a real list_files call work against your real Drive folder.
4. Push to GitHub (section 12).
5. Create the Render Web Service, connect the repo, and set the four environment variables in the Render dashboard (sections 13–14) — Render will build and deploy automatically.
6. Generate production API_KEYS (different from any local dev key) and store them securely for your MCP clients.
7. Connect your MCP client to https://<your-render-service>.onrender.com/mcp (section 17).