feat: v0.2.0 — multi-installation support and citation tools (#86)

* feat: support multiple installations via --config-dir flag (Closes #85)

Add --config-dir flag and GSUITE_MCP_CONFIG_DIR env var to override the
default config directory (~/.config/gsuite-mcp/). This enables running
multiple gsuite-mcp instances with different GCP projects — e.g., one for
a work Workspace account and another for a personal account.

Each installation gets its own client_secret.json, config.json, and
credentials/ directory. The .installations/ convention keeps repo-local
configs gitignored.

* docs: add changelog and update default OAuth port references to 38917

Add [Unreleased] section to CHANGELOG.md covering all changes since
v0.1.0. Update all documentation and test references from port 8100 to
38917 to match the new DefaultOAuthPort constant.

* chore: bump version to 0.2.0

New features since 0.1.0: multi-installation support, citation tools,
Forms, Slides, Gmail send-as, Drive filtering, Docs/Sheets/Calendar
enhancements, and OAuth port change.

* feat(citation): add large document citation tools with FTS5 search

Add 11 citation tools for indexing, searching, and citing large documents:
- citation_create_index: Create Google Sheets index in a Drive folder
- citation_add_documents: Chunk docs/slides/pptx, write to Sheets + SQLite
- citation_lookup: FTS5 full-text search across indexed chunks
- citation_get_overview: Index stats with doc/chunk counts and concepts
- citation_get_chunks: Retrieve full chunk content by ID
- citation_verify_claim: Find chunks supporting a claim
- citation_format_citation: Human-readable citation with file/slide/snippet
- citation_save_concepts: Persist LLM-extracted concept→chunk mappings
- citation_save_summary: Persist hierarchical summaries
- citation_list_indexes: List configured indexes
- citation_refresh: Detect updated/removed/renamed files and re-index

Architecture: dual-layer storage (Google Sheets as source of truth,
SQLite FTS5 as disposable local cache). Cache auto-rebuilds from Sheets
when missing. Feature-flagged via large_doc_indexing config.

Supports Google Slides (native API), uploaded .pptx (zip/XML text
extraction), Google Docs (text export), and shared drives
(SupportsAllDrives). Large content responses get a citation hint when
the feature is enabled.

Author: aliwatters

.gitignore

@@ -34,3 +34,6 @@ rod-mcp.yaml
 !schemas/*.json
 credentials/
 .workflow-state.json
+
+# Per-installation config directories (see #85)
+.installations/

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-03-20
+
+### Added
+
+- **Multi-installation support**: `--config-dir` flag and `GSUITE_MCP_CONFIG_DIR` env var to run multiple instances with different GCP projects (#85)
+- **Citation tools** (11 tools): Large document indexing with chunking, FTS5 search, concept extraction, and citation formatting (feature-flagged via `large_doc_indexing`)
+- **Google Forms** (5 tools): Get form structure, create forms, batch update, list/get responses (#78)
+- **Google Slides** (5 tools): Read presentations, get slides, thumbnails, create, batch update (#77)
+- **Gmail send-as aliases and delegation** (9 tools): Manage send-as identities and delegate access (#79)
+- **Drive access filtering**: Configurable allowlist/blocklist for shared drives (#76)
+- **Docs enhancements**: Markdown export, find-replace, PDF export, doc import (#74)
+- **Docs styling and Sheets formatting**: Paragraph styles, charts, pivot tables (#73)
+- **Calendar enhancements**: Focus Time, OOO events, conference data, free/busy (#72)
+- **Drive enhancements**: Shareable links, file type filter, comments, revisions (#71)
+- Protocol-level MCP tests for regression prevention (#83)
+
+### Changed
+
+- Default OAuth port changed from `8100` to `38917` to avoid conflicts with common dev servers
+
 ## [0.1.0] - 2026-02-09
 
 ### Added

INSTALLATION.md

@@ -187,7 +187,7 @@ Re-run the auth command:
 gsuite-mcp auth
 ```
 
-Or, if gsuite-mcp is running as an MCP server, open `http://localhost:8100/auth` in your browser to re-authenticate without restarting the server. Error messages from tools will include this URL when the auth server is running.
+Or, if gsuite-mcp is running as an MCP server, open `http://localhost:38917/auth` in your browser to re-authenticate without restarting the server. Error messages from tools will include this URL when the auth server is running.
 
 ### API Not Enabled
 
@@ -270,7 +270,7 @@ Optional configuration file created by `gsuite-mcp init`. Settings:
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `oauth_port` | `8100` | Port for the OAuth callback server during `gsuite-mcp auth` |
+| `oauth_port` | `38917` | Port for the OAuth callback server during `gsuite-mcp auth` |
 
 Override `oauth_port` via the `GSUITE_MCP_OAUTH_PORT` environment variable.
 

README.md

@@ -340,7 +340,7 @@ See [INSTALLATION.md](INSTALLATION.md) for full setup instructions.
 
 ### OAuth Callback Port
 
-The default OAuth callback port is **8100**. Override it in `config.json`:
+The default OAuth callback port is **38917**. Override it in `config.json`:
 
 ```json
 { "oauth_port": 9000 }
@@ -354,7 +354,7 @@ Restrict which shared drives are accessible via MCP tools. Add `drive_access` to
 
 ```json
 {
-  "oauth_port": 8100,
+  "oauth_port": 38917,
   "drive_access": {
     "allowed": ["Marketing", "Engineering"]
   }
@@ -371,8 +371,8 @@ My Drive is always accessible. Setting both `allowed` and `blocked` is an error.
 
 When running as an MCP server, gsuite-mcp starts a persistent HTTP server on the OAuth port so agents and users can trigger re-authentication from a browser:
 
-- **`http://localhost:8100/auth`** — starts OAuth flow (opens Google consent screen)
-- **`http://localhost:8100/auth?account=user@gmail.com`** — pre-selects the Google account
+- **`http://localhost:38917/auth`** — starts OAuth flow (opens Google consent screen)
+- **`http://localhost:38917/auth?account=user@gmail.com`** — pre-selects the Google account
 
 When a tool encounters missing credentials, the error message includes a clickable auth URL. If the port is unavailable, the MCP server continues without the auth endpoint.
 

cmd/gsuite-mcp/main.go

@@ -4,10 +4,12 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"path/filepath"
 	"time"
 
 	"github.com/aliwatters/gsuite-mcp/internal/auth"
 	"github.com/aliwatters/gsuite-mcp/internal/calendar"
+	"github.com/aliwatters/gsuite-mcp/internal/citation"
 	"github.com/aliwatters/gsuite-mcp/internal/common"
 	"github.com/aliwatters/gsuite-mcp/internal/config"
 	"github.com/aliwatters/gsuite-mcp/internal/contacts"
@@ -23,10 +25,14 @@ import (
 
 const (
 	serverName    = "gsuite-mcp"
-	serverVersion = "0.1.0"
+	serverVersion = "0.2.0"
 )
 
 func main() {
+	// Parse --config-dir flag or GSUITE_MCP_CONFIG_DIR env var before subcommand dispatch.
+	// This must happen first so all config.* path functions resolve correctly.
+	parseConfigDir()
+
 	// Check for subcommands first
 	if len(os.Args) > 1 {
 		switch os.Args[1] {
@@ -80,6 +86,9 @@ func main() {
 	forms.RegisterTools(s)
 	contacts.RegisterTools(s)
 
+	// Conditionally register citation tools (feature-flagged)
+	registerCitationIfEnabled(s)
+
 	// Start server
 	if err := server.ServeStdio(s); err != nil {
 		fmt.Fprintf(os.Stderr, "Server error: %v\n", err)
@@ -138,17 +147,23 @@ Usage:
 No configuration required - just authenticate any Google account on demand.
 When tools request an account without credentials, auth flow is triggered automatically.
 
+Flags:
+  --config-dir DIR  Use DIR for config, credentials, and client_secret.json
+                    (default: %s)
+
 Configuration:
   Config dir:     %s
   Config file:    %s
   Credentials:    %s
   Client secret:  %s
 
 Environment variables:
+  GSUITE_MCP_CONFIG_DIR   Override config directory (same as --config-dir)
   GSUITE_MCP_OAUTH_PORT   Override OAuth callback port (default: %d)
 
 For more information, see README.md
 `, serverName, serverName, serverName, serverName, serverName, serverName,
+		config.DefaultConfigDir(),
 		config.DefaultConfigDir(), config.ConfigPath(), config.CredentialsDir(), config.ClientSecretPath(),
 		config.DefaultOAuthPort)
 }
@@ -218,6 +233,65 @@ func runAccounts() {
 	fmt.Printf("\nRun '%s auth' to add another account.\n", serverName)
 }
 
+// registerCitationIfEnabled registers citation tools if the large_doc_indexing feature is enabled.
+func registerCitationIfEnabled(s *server.MCPServer) {
+	cfg, err := config.LoadConfig()
+	if err != nil || cfg.Features == nil || !cfg.Features.LargeDocIndexing {
+		return
+	}
+
+	var citCfg *citation.CitationConfig
+	if cfg.Citation != nil {
+		citCfg = &citation.CitationConfig{
+			Indexes: make(map[string]citation.IndexEntry),
+		}
+		for k, v := range cfg.Citation.Indexes {
+			citCfg.Indexes[k] = citation.IndexEntry{SheetID: v.SheetID}
+		}
+	}
+
+	citation.InitDefaultDeps(citCfg)
+	citation.RegisterTools(s)
+
+	// Enable citation hints on large content responses
+	if d := common.GetDeps(); d != nil {
+		d.CitationEnabled = true
+	}
+
+	fmt.Fprintln(os.Stderr, "citation tools enabled (large_doc_indexing)")
+}
+
+// parseConfigDir checks for --config-dir flag or GSUITE_MCP_CONFIG_DIR env var
+// and sets the config directory override. The flag is consumed from os.Args so
+// subcommand parsing is unaffected.
+func parseConfigDir() {
+	// Check for --config-dir flag (must appear before subcommand)
+	for i := 1; i < len(os.Args); i++ {
+		if os.Args[i] == "--config-dir" && i+1 < len(os.Args) {
+			dir := os.Args[i+1]
+			absDir, err := filepath.Abs(dir)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "Error resolving --config-dir %q: %v\n", dir, err)
+				os.Exit(1)
+			}
+			config.SetConfigDir(absDir)
+			// Remove the flag and its value from os.Args
+			os.Args = append(os.Args[:i], os.Args[i+2:]...)
+			return
+		}
+	}
+
+	// Fall back to environment variable
+	if dir := os.Getenv("GSUITE_MCP_CONFIG_DIR"); dir != "" {
+		absDir, err := filepath.Abs(dir)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error resolving GSUITE_MCP_CONFIG_DIR %q: %v\n", dir, err)
+			os.Exit(1)
+		}
+		config.SetConfigDir(absDir)
+	}
+}
+
 // startAuthServer starts a persistent HTTP auth server for browser-based re-authentication.
 // Returns nil if the port cannot be bound (non-fatal — MCP server continues without it).
 func startAuthServer() *auth.AuthServer {

docs/AGENTS.md

@@ -165,7 +165,7 @@ if err != nil {
 
 #### HTTP Auth Endpoint
 
-When running as an MCP server, gsuite-mcp starts a persistent HTTP auth server on the OAuth port. If a tool encounters missing credentials, the error message includes a clickable URL (e.g., `http://localhost:8100/auth?account=user@gmail.com`). Agents should surface this URL to the user rather than suggesting CLI commands.
+When running as an MCP server, gsuite-mcp starts a persistent HTTP auth server on the OAuth port. If a tool encounters missing credentials, the error message includes a clickable URL (e.g., `http://localhost:38917/auth?account=user@gmail.com`). Agents should surface this URL to the user rather than suggesting CLI commands.
 
 ### 4. Error Handling
 

go.mod

@@ -1,6 +1,6 @@
 module github.com/aliwatters/gsuite-mcp
 
-go 1.24.0
+go 1.25.0
 
 require (
 	github.com/mark3labs/mcp-go v0.23.1
@@ -13,13 +13,17 @@ require (
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.3.11 // indirect
 	github.com/googleapis/gax-go/v2 v2.16.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/spf13/cast v1.7.1 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
@@ -29,9 +33,13 @@ require (
 	go.opentelemetry.io/otel/trace v1.39.0 // indirect
 	golang.org/x/crypto v0.47.0 // indirect
 	golang.org/x/net v0.49.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/text v0.33.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260122232226-8e98ce8d340d // indirect
 	google.golang.org/grpc v1.78.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
+	modernc.org/libc v1.70.0 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.47.0 // indirect
 )

go.sum

@@ -8,6 +8,8 @@ github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UF
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
@@ -35,8 +37,14 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/mark3labs/mcp-go v0.23.1 h1:RzTzZ5kJ+HxwnutKA4rll8N/pKV6Wh5dhCmiJUu5S9I=
 github.com/mark3labs/mcp-go v0.23.1/go.mod h1:rXqOudj/djTORU/ThxYx8fqEVj/5pvTuuebQ2RC7uk4=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y=
@@ -67,8 +75,11 @@ golang.org/x/oauth2 v0.34.0 h1:hqK/t4AKgbqWkdkcAeI8XLmbK+4m4G5YeQRrmiotGlw=
 golang.org/x/oauth2 v0.34.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
 golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
 golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
 golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
 gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
@@ -87,3 +98,11 @@ google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBN
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/libc v1.70.0 h1:U58NawXqXbgpZ/dcdS9kMshu08aiA6b7gusEusqzNkw=
+modernc.org/libc v1.70.0/go.mod h1:OVmxFGP1CI/Z4L3E0Q3Mf1PDE0BucwMkcXjjLntvHJo=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/sqlite v1.47.0 h1:R1XyaNpoW4Et9yly+I2EeX7pBza/w+pmYee/0HJDyKk=
+modernc.org/sqlite v1.47.0/go.mod h1:hWjRO6Tj/5Ik8ieqxQybiEOUXy0NJFNp2tpvVpKlvig=

internal/auth/auth.go

@@ -125,7 +125,7 @@ type Manager struct {
 	oauthConfig *oauth2.Config
 	// authMu prevents concurrent authentication attempts
 	authMu sync.Mutex
-	// AuthServerURL is set when the HTTP auth server is running (e.g. "http://localhost:8100/auth").
+	// AuthServerURL is set when the HTTP auth server is running (e.g. "http://localhost:38917/auth").
 	AuthServerURL string
 }
 
@@ -192,7 +192,7 @@ func loadOAuthConfig() (*oauth2.Config, error) {
 }
 
 // resolveOAuthPort determines the OAuth callback port.
-// Resolution order: GSUITE_MCP_OAUTH_PORT env var → config.json → default (8100).
+// Resolution order: GSUITE_MCP_OAUTH_PORT env var → config.json → default (38917).
 func resolveOAuthPort() (int, error) {
 	if portStr := os.Getenv("GSUITE_MCP_OAUTH_PORT"); portStr != "" {
 		port, err := strconv.Atoi(portStr)

internal/auth/server_test.go

@@ -24,7 +24,7 @@ func newTestAuthServer() *AuthServer {
 			Scopes: []string{"openid", "email"},
 		},
 	}
-	return NewAuthServer(mgr, 8100)
+	return NewAuthServer(mgr, 38917)
 }
 
 func TestHandleAuth_RedirectsToGoogle(t *testing.T) {