Set Up Your Project

Configure TeaRAGs on a per-project basis using environment variables.

Future: .mcp.json Configuration

Project-level .mcp.json configuration file is planned for future release (tea-rags-mcp-h64). Currently, use environment variables for project-specific settings.

Why Project-Level Configuration?

Different codebases have different characteristics:

Project Type	Custom Settings
Monorepo	Smaller chunk size, exclude build artifacts, multiple ignore patterns
Documentation site	Larger chunks, disable git enrichment, markdown-only
Enterprise legacy	Enable git enrichment, custom file extensions, exclude vendor dirs
Microservice	Fast indexing, minimal enrichment, specific search defaults

Current Approach: Environment Variables

Set environment variables before starting the MCP server or in your MCP server configuration.

Global Configuration

Edit ~/.config/claude/claude_desktop_config.json (or equivalent):

{
  "mcpServers": {
    "tea-rags": {
      "command": "node",
      "args": ["/path/to/tea-rags/build/index.js"],
      "env": {
        "INGEST_CHUNK_SIZE": "2500",
        "INGEST_CHUNK_OVERLAP": "300",
        "TRAJECTORY_GIT_ENABLED": "false"
      }
    }
  }
}

tip

QDRANT_URL is autodetected (embedded Qdrant starts automatically). Add it only if using external Qdrant.

Per-Project Workflows

For different projects, you can:

Use .contextignore - Exclude project-specific paths
Use query parameters - Override settings in MCP tool calls
Switch MCP server configs - Create multiple server entries with different env vars

Configuration Categories

Chunking Settings

Control how code is split into searchable chunks.

Environment Variable	Type	Default	Description
`INGEST_CHUNK_SIZE`	number	2500	Maximum chunk size in characters
`INGEST_CHUNK_OVERLAP`	number	300	Overlap between chunks in characters

Use cases:

Large chunks (3000+): Documentation sites, architectural documents, low file count
Small chunks (1500-2000): Dense code, many small functions, better precision

Example:

{
  "env": {
    "INGEST_CHUNK_SIZE": "2000",
    "INGEST_CHUNK_OVERLAP": "250"
  }
}

Indexing Settings

Configure what gets indexed and how.

Environment Variable	Type	Default	Description
`TRAJECTORY_GIT_ENABLED`	boolean	true	Enable git enrichment (20+ signals per chunk, 13 file + 10 chunk raw)

Use cases:

Enable git enrichment: Enterprise projects, legacy codebases, need ownership/churn data
Disable git enrichment: Documentation sites, fast prototyping

Git Enrichment Performance

Git enrichment runs concurrently with embedding and does not increase indexing time. The process is parallelized across multiple workers:

INGEST_TUNE_CHUNKER_POOL_SIZE=4 — Parallel AST parsing workers
INGEST_TUNE_FILE_CONCURRENCY=50 — Parallel file reads
TRAJECTORY_GIT_CHUNK_CONCURRENCY=10 — Parallel git blame operations for chunk-level churn

Recommended: Keep defaults for production use.

Example:

{
  "env": {
    "TRAJECTORY_GIT_ENABLED": "true"
  }
}

Search Settings

Configure search behavior.

Currently, search settings are specified via query parameters in MCP tool calls:

// search_code tool
{
  "path": "/path/to/project",
  "query": "authentication logic",
  "limit": 10,
  "rerank": "stable"
}

Available rerank presets:

relevance - Default semantic similarity
recent - Boost recently modified code
stable - Boost low-churn, stable code
hotspots - High-churn, bug-prone areas
ownership - Single-author code (knowledge silos)

Embedding Settings

Configure embedding provider and batching.

Environment Variable	Type	Default	Description
`EMBEDDING_BASE_URL`	string	`http://localhost:11434`	Ollama server URL
`EMBEDDING_MODEL`	string	`unclemusclez/jina-embeddings-v2-base-code:latest`	Embedding model name
`EMBEDDING_TUNE_BATCH_SIZE`	number	Auto-tuned	Ceiling for the embedding batch size the run picks (Adaptive Embedding)
`INGEST_PIPELINE_CONCURRENCY`	number	unset	Hard ceiling for the embedding concurrency; the run climbs toward it only while measured throughput rises. Unset: implicit ceiling `8`, everything else at `1`
`EMBEDDING_TUNE_STATIC`	boolean	`false`	`true` uses the two values above unchanged for the whole run

Example:

{
  "env": {
    "EMBEDDING_MODEL": "nomic-embed-text:latest",
    "EMBEDDING_TUNE_BATCH_SIZE": "512",
    "INGEST_PIPELINE_CONCURRENCY": "1"
  }
}

Common Configurations

Monorepo

{
  "mcpServers": {
    "tea-rags-monorepo": {
      "command": "node",
      "args": ["/path/to/tea-rags/build/index.js"],
      "env": {
        "INGEST_CHUNK_SIZE": "2000",
        "INGEST_CHUNK_OVERLAP": "200",
        "TRAJECTORY_GIT_ENABLED": "true"
      }
    }
  }
}

Why:

Smaller chunks (2000) for better precision across many packages
Git enrichment to track ownership across teams

Additional: Create .contextignore in monorepo root:

packages/*/node_modules
packages/*/dist
packages/*/build
tools/**
scripts/**

Documentation Site

{
  "mcpServers": {
    "tea-rags-docs": {
      "command": "node",
      "args": ["/path/to/tea-rags/build/index.js"],
      "env": {
        "INGEST_CHUNK_SIZE": "3500",
        "INGEST_CHUNK_OVERLAP": "500",
        "TRAJECTORY_GIT_ENABLED": "false"
      }
    }
  }
}

Why:

Large chunks (3500) for complete documentation sections
No git enrichment (documentation churn is normal)

Additional: Create .contextignore:

node_modules/**
.docusaurus/**
build/**

Legacy Enterprise Codebase

{
  "mcpServers": {
    "tea-rags-legacy": {
      "command": "node",
      "args": ["/path/to/tea-rags/build/index.js"],
      "env": {
        "INGEST_CHUNK_SIZE": "2500",
        "INGEST_CHUNK_OVERLAP": "300",
        "TRAJECTORY_GIT_ENABLED": "true"
      }
    }
  }
}

Why:

Git enrichment to find code owners and knowledge silos
Use rerank: "ownership" in searches to identify domain experts

Additional: Create .contextignore:

vendor/**
third-party/**
*.generated.*

Microservice

{
  "mcpServers": {
    "tea-rags-microservice": {
      "command": "node",
      "args": ["/path/to/tea-rags/build/index.js"],
      "env": {
        "INGEST_CHUNK_SIZE": "2000",
        "INGEST_CHUNK_OVERLAP": "200",
        "TRAJECTORY_GIT_ENABLED": "false"
      }
    }
  }
}

Why:

Smaller chunks for focused microservice code
No git enrichment (fast iteration, small team)
Use rerank: "recent" in searches for actively developed code

Additional: Create .contextignore:

vendor/**
mocks/**
*.pb.go

Priority Order

Settings are resolved in this order (highest priority first):

Query parameters — passed directly to search/index tools
Environment variables — MCP server configuration
Defaults — built-in TeaRAGs defaults

Example:

# Global setting (lowest priority)
export INGEST_CHUNK_SIZE=2500

# Query parameter (highest priority)
/index_codebase /path/to/project --chunkSize 1500

Result: chunkSize=1500 (query parameter wins)

File Location: .contextignore

Place .contextignore in the root of your project — the same directory you pass to indexing tools.

/path/to/project/
├── .contextignore     ← Ignore patterns
├── src/
├── tests/
└── package.json

TeaRAGs automatically detects .contextignore when indexing that directory.

Validation

Invalid environment variables are logged but do not block indexing. Defaults are used for invalid values.

Enable debug mode to see configuration resolution:

export DEBUG=1

Logs show:

Which environment variables were loaded
Which settings were overridden
Validation errors (if any)

Check logs in ~/.tea-rags/logs/

Best Practices

1. Use .contextignore

Do: Create .contextignore in each project

# In project root
cat > .contextignore <<EOF
node_modules/**
dist/**
build/**
vendor/**
*.min.js
EOF

2. Document Your Configuration

Add comments in MCP config or project README:

## TeaRAGs Configuration

- `INGEST_CHUNK_SIZE: 2000` — Dense microservice code, smaller chunks for precision
- `TRAJECTORY_GIT_ENABLED: false` — Fast iteration, small team, no ownership tracking needed

3. Test Configuration

After changing settings, reindex and verify:

# Reindex with new settings
/index_codebase /path/to/project

# Check index status
/get_index_status /path/to/project

# Test search
/search_code /path/to/project "your query"

4. Start Minimal

Don't override everything. Start with the minimum:

{
  "env": {
    "INGEST_CHUNK_SIZE": "2000"
  }
}

Add more settings only when needed.

Troubleshooting

Settings Not Applied

Check:

Environment variables are set in MCP server config
MCP server was restarted after config changes
Variable names match exactly (case-sensitive)
Values are valid (numbers as strings, booleans as "true"/"false")

Invalid Settings Ignored

Enable debug mode:

export DEBUG=1

Check logs in ~/.tea-rags/logs/ for validation errors.

Query Parameters Not Overriding

Remember priority order:

Query parameters > Environment variables > Defaults

If environment variable is set globally, query parameters still override it.

Next Steps

Configuration Variables — see all available settings
Performance Tuning — optimize chunk size and batch settings
Indexing Repositories — learn about .contextignore patterns

Why Project-Level Configuration?​

Current Approach: Environment Variables​

Global Configuration​

Per-Project Workflows​

Configuration Categories​

Chunking Settings​

Indexing Settings​

Search Settings​

Embedding Settings​

Common Configurations​

Monorepo​

Documentation Site​

Legacy Enterprise Codebase​

Microservice​

Priority Order​

File Location: .contextignore​

Validation​

Best Practices​

1. Use .contextignore​

2. Document Your Configuration​

3. Test Configuration​

4. Start Minimal​

Troubleshooting​

Settings Not Applied​

Invalid Settings Ignored​

Query Parameters Not Overriding​

Next Steps​

Why Project-Level Configuration?

Current Approach: Environment Variables

Global Configuration

Per-Project Workflows

Configuration Categories

Chunking Settings

Indexing Settings

Search Settings

Embedding Settings

Common Configurations

Monorepo

Documentation Site

Legacy Enterprise Codebase

Microservice

Priority Order

File Location: .contextignore

Validation

Best Practices

1. Use .contextignore

2. Document Your Configuration

3. Test Configuration

4. Start Minimal

Troubleshooting

Settings Not Applied

Invalid Settings Ignored

Query Parameters Not Overriding

Next Steps