dependency-context

Dependency Context

by @darianb

An MCP server that provides AI assistants with contextual access to your project's dependency documentation, enabling more accurate responses about libraries and frameworks used in your codebase.

Configuration

The recommended way to specify which dependencies you want to index is by creating a custom dependency-context.json file in your project root. This allows you to:

• Only index the dependencies you're actively using and need help with
• Improve indexing speed by limiting the number of dependencies
• Focus the search results on the libraries that matter most

Create a dependency-context.json file in your project root with the following format:

{
  "express": "^4.17.1",
  "axios": "1.0.0"
}

If a dependency-context.json file is not present, Dependency Context falls back to scanning package.json or requirements.txt.

Quick Start

Option 1: Use MCP with AI Integration (Recommended for Cursor Users)

• Add the MCP config to your editor (Cursor recommended):

{
  "mcpServers": {
    "dependency-context": {
      "command": "npx",
      "args": ["-y", "--package=dependency-context", "dependency-context"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE", // Optional but recommended
        "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // Optional, default shown
        "DEBUG": "false", // Optional, default shown
        "MIN_CHUNK_SIZE": "800", // Optional, default shown
        "MAX_CHUNK_SIZE": "8000", // Optional, default shown
        "CHUNKS_RETURNED": "5" // Optional, default shown
      }
    }
  }
}

• Enable the MCP in your editor

• Prompt the AI to initialialize dependency-context. Make sure you are in "Agent" mode.

Can you initialize dependency-context?

• Prompt the AI like you normally do. It will automatically pull in dependency-context when relevant

Option 2: Direct Download of Documentation (No Vector Database)

If you prefer to just download and browse the dependency documentation without vector search:

• Install dependency-context:

npm install -g dependency-context

• Download documentation for a project:

# From your project directory
dependency-context download

# Or specify a different project path
dependency-context download /path/to/your/project

• Find the documentation in the dependency-context folder in your project:

# Explore the documentation
cd dependency-context
ls

Each dependency will have its own folder containing all the markdown documentation from its repository.

MCP Tools

Dependency Context provides two main tools through its MCP interface:

1. InitializeDependencyIndex

Analyzes a project's dependencies and creates a searchable index of their documentation.

{
  "capability": "InitializeDependencyIndex",
  "parameters": {
    "project_path": "/path/to/your/project",
    "env_vars": {
      "GITHUB_TOKEN": "your_github_token", // Optional but recommended
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // Optional, default shown
      "DEBUG": "true", // Optional
      "MIN_CHUNK_SIZE": "800", // Optional, default shown
      "MAX_CHUNK_SIZE": "8000" // Optional, default shown
    }
  }
}

This capability:

• Checks for a custom dependencies.json file (recommended)
• Falls back to scanning package.json or requirements.txt if no custom file exists
• Locates the GitHub repositories for each dependency
• Clones repositories and extracts Markdown documentation
• Creates vector embeddings for semantic search

2. searchDependencyDocs

Performs semantic search over indexed dependency documentation.

{
  "capability": "searchDependencyDocs",
  "parameters": {
    "project_path": "/path/to/your/project",
    "query": "How do I handle authentication?",
    "repository_context": "express", // Optional: limit to a specific dependency
    "env_vars": {
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2",
      "CHUNKS_RETURNED": "5" // Optional, default shown
    }
  }
}

Returns:

• The most relevant documentation chunks matching your query
• Source information (repository, file path)
• Similarity scores for each result

Architecture

Dependency Context is built with a modular TypeScript architecture:

• Core Components:

  • Parsers: Extract dependencies from package.json and requirements.txt
  • Repository Discovery: Locate GitHub repositories using registry metadata
  • Document Fetching: Clone repositories and extract documentation
  • Vector Store: Generate embeddings and enable semantic search
  • MCP Server: Provide a standardized interface for AI tools

• Key Libraries:

  • fastmcp: MCP protocol implementation
  • @xenova/transformers: Local embedding model for vector creation
  • simple-git: Git client for repository operations
  • axios: HTTP client for API requests
  • fs-extra: Enhanced file system operations
  • dotenv: Environment variable management

Testing

Unit Testing

Run the test suite with:

npm test

Manual Testing

For manual testing, follow these steps:

• Set up a Test Project

mkdir test-project
cd test-project

# Create a custom dependencies.json file (recommended approach)
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > dependencies.json

# Alternatively, you can use standard dependency files:

# For Node.js projects
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > package.json

# For Python projects
echo 'requests==2.26.0
numpy>=1.20.0' > requirements.txt

• Use fastmcp dev to test dependency-context

# Build and make the CLI executable
cd /path/to/dependency-context
npx fastmcp dev src/index.ts

# Initialize and index dependencies (from your test project directory)
tool(InitializeDependencyIndex)

# Search for information in the indexed dependencies
tool(searchDependencyDocs)


## Troubleshooting

### GitHub API Rate Limits

If you encounter "API rate limit exceeded" errors:

1. Create a GitHub personal access token at https://github.com/settings/tokens
2. Set it as the `GITHUB_TOKEN` environment variable:
   ```bash
   export GITHUB_TOKEN=your_token_here

• Or add it to your .env file:

  # Optional but recommended for higher API rate limits
  GITHUB_TOKEN=your_token_here
  
  # Optional settings with defaults shown below
  MIN_CHUNK_SIZE=800
  MAX_CHUNK_SIZE=8000
  CHUNKS_RETURNED=5
  

Empty Search Results

If your searches return empty results:

• Ensure the indexing process completed successfully
• Check the console output for any error messages
• Verify that your search query is relevant to the indexed dependencies
• Try a more general query to see if any results are returned

Permission Issues

If you encounter permission errors when accessing project directories:

• Ensure the server has read/write access to the project directory
• Check that temporary directories are accessible
• Run the server with appropriate permissions

Development

# Clone the repository
git clone https://github.com/yourusername/dependency-context.git

# Install dependencies
cd dependency-context
npm install

# Run MCP server locally with fastmcp dev
npx fastmcp dev src/index.ts

# Test CLI download command
node src/index.js download ./test-project

Project Todo List

High Priority

• Set up basic project structure and dependencies
• Implement dependency parser for package.json and requirements.txt
• Create GitHub repository discovery functionality
• Build documentation fetching and markdown processing
• Implement vector store creation and indexing
• Set up MCP endpoint for semantic search
• Add environment variable support through multiple channels (system, project, MCP params)
• Add parameters for chunk size and top-k returns to functions
• Add CLI mode to download raw documentation
• Add proper error handling and retry mechanisms for GitHub API

Medium Priority

• Support for additional package managers (Maven, Go, Rust)
• Add progress reporting for long-running index operations
• Enhance chunking algorithm to better respect Markdown structure
• Support for non-GitHub repositories (GitLab, Bitbucket)

Low Priority

• Create comprehensive documentation

Future Enhancements

• Additional Package Managers: Support for pom.xml, go.mod, and other dependency formats (note: custom dependencies.json is already supported as the recommended approach)
• Incremental Indexing: Avoid reprocessing unchanged repositories
• Configurable Chunking: Custom strategies for document splitting
• Alternative Models: Support for different embedding models
• Caching Layer: Improved performance for frequently accessed documentation

License

Dependency Context is licensed under the MIT License with Commons Clause. This means you can:

✅ Allowed:

• Use Dependency Context for any purpose (personal, commercial, academic)
• Modify the code
• Distribute copies
• Create and sell products built using Dependency Context

❌ Not Allowed:

• Sell Dependency Context itself
• Offer Dependency Context as a hosted service
• Create competing products based on Dependency Context

See the LICENSE file for the complete license text and licensing details for more information.

Copyright © 2024 DarianB