willibrandon · willibrandon · Mar 22, 2025 · Mar 22, 2025
diff --git a/.github/images/demo.gif b/.github/images/demo.gif
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# Contributing to NetContextServer
+
+## Quick Start
+
+1. Fork and clone the repository
+2. Install .NET 9.0 SDK or later
+3. Build: `dotnet build`
+4. Test: `dotnet test`
+
+## Development Process
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature
+   # or
+   git checkout -b fix/your-bug
+   ```
+
+2. Make changes:
+   - Follow C# coding conventions
+   - Add/update tests
+   - Update relevant documentation
+
+3. Commit with clear messages:
+   ```bash
+   git commit -m "feat: add new feature
+
+   - Brief description of changes
+   - Additional details if needed
+
+   Fixes #123"
+   ```
+
+4. Push and create a Pull Request
+
+## Guidelines
+
+- Keep changes focused and atomic
+- Include tests for new features
+- Update documentation as needed
+- Follow existing code style
+- Test AI integration if relevant
+
+## Need Help?
+
+- Check existing issues
+- Create a new issue
+- Join community discussions
+
+Thank you for contributing! 
diff --git a/NetContextServer.sln b/NetContextServer.sln
@@ -5,7 +5,10 @@ VisualStudioVersion = 17.13.35818.85
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}"
 	ProjectSection(SolutionItems) = preProject
-		README.md = README.md
+		docs\configuration.md = docs\configuration.md
+		docs\getting-started.md = docs\getting-started.md
+		docs\integrations.md = docs\integrations.md
+		docs\tool-reference.md = docs\tool-reference.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}"
@@ -21,6 +24,8 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8EC462FD-D22E-90A8-E5CE-7E832BA40C5D}"
 	ProjectSection(SolutionItems) = preProject
 		.github\workflows\ci.yaml = .github\workflows\ci.yaml
+		CONTRIBUTING.md = CONTRIBUTING.md
+		README.md = README.md
 	EndProjectSection
 EndProject
 Global

diff --git a/README.md b/README.md
@@ -1,6 +1,85 @@
 # NetContextServer
 
-A .NET Codebase Context MCP Server that provides AI assistants with access to your .NET codebase through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). This allows AI tools to understand and work with your specific codebase context.
+<div align="center">
+
+🔍 **Supercharge Your AI Coding Assistant with Deep .NET Codebase Understanding**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Built with .NET](https://img.shields.io/badge/Built%20with-.NET-512BD4)](https://dotnet.microsoft.com/)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-brightgreen)](https://modelcontextprotocol.io/)
+
+</div>
+
+NetContextServer empowers AI coding assistants like Cursor AI to deeply understand your .NET codebase through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). This means more accurate code suggestions, better answers to your questions, and a more productive coding experience.
+
+![Demo of NetContextServer with Cursor AI](.github/images/demo.gif)
+
+## ✨ Key Features
+
+- 🧠 **Semantic Code Search**: Find code by describing what you're looking for in natural language
+- 🔍 **Intelligent Navigation**: Help AI tools understand your project structure and dependencies
+- 🛡️ **Built-in Security**: Safe file access with automatic protection of sensitive data
+- 🚀 **Cursor AI Integration**: Seamless setup with Cursor AI for enhanced coding assistance
+- 📦 **Package Analysis**: Understand your dependencies and get update recommendations
+- ⚡ **Fast & Efficient**: Quick indexing and response times for large codebases
+
+## 🚀 Quick Start
+
+1. **Clone & Build**:
+```bash
+git clone https://github.com/willibrandon/NetContextServer.git
+cd NetContextServer
+dotnet build
+```
+
+2. **Set Up** (optional, for semantic search):
+```bash
+# Set Azure OpenAI credentials in environment:
+AZURE_OPENAI_ENDPOINT=your_endpoint
+AZURE_OPENAI_API_KEY=your_key
+```
+
+3. **Start Using**:
+```bash
+# Point to your project
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- set-base-dir --directory "path/to/your/project"
+
+# Try semantic search
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- semantic-search --query "find authentication logic"
+```
+
+👉 **[Read our Getting Started Guide](docs/getting-started.md)** for detailed setup instructions and best practices.
+
+## 🔌 Integration with Cursor AI
+
+1. Open Cursor AI
+2. Press `Cmd/Ctrl + Shift + P`
+3. Type "Configure MCP Server"
+4. Enter:
+```json
+{
+  "command": "dotnet",
+  "args": ["run", "--project", "path/to/NetContextServer/src/NetContextServer/NetContextServer.csproj"]
+}
+```
+
+Now Cursor AI can understand your codebase! Try asking it questions like:
+- "List all .NET source files in this project directory"
+- "Search for exact text matches in the code files"
+- "Analyze NuGet packages in all projects"
+- "Get the current list of ignore patterns"
+- "Add these ignore patterns: *.generated.cs, bin/*"
+- "List all .csproj files in this directory"
+- "Show me the contents of this file"
+- "What's the current base directory for file operations?"
+
+## 📚 Documentation
+
+- [Getting Started Guide](docs/getting-started.md) - Quick setup and first steps
+- [Tool Reference](docs/tool-reference.md) - Detailed tool documentation
+- [Configuration Guide](docs/configuration.md) - Advanced configuration options
+- [Integration Examples](docs/integrations.md) - Using with different AI tools
+- [Contributing Guide](CONTRIBUTING.md) - How to help improve NetContextServer
 
 ## Features
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,210 @@
+# Advanced Configuration Guide
+
+This guide covers advanced configuration options for NetContextServer to help you customize and optimize its behavior for your specific needs.
+
+## Environment Variables
+
+### Azure OpenAI Configuration
+Required for semantic search functionality:
+```bash
+# Azure OpenAI Settings
+AZURE_OPENAI_ENDPOINT=your_azure_openai_endpoint
+AZURE_OPENAI_API_KEY=your_azure_openai_key
+```
+
+## Base Directory Configuration
+
+The base directory is a critical security feature that defines the root of your workspace. All file operations are restricted to this directory and its subdirectories.
+
+### Setting the Base Directory
+
+You can set the base directory in several ways:
+
+1. **Command Line**:
+```bash
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- set-base-dir --directory "D:\YourProject"
+```
+
+2. **Environment Variable** (optional):
+```bash
+NETCONTEXT_BASE_DIR=D:\YourProject
+```
+
+### Base Directory Best Practices
+
+1. Set to your solution or project root
+2. Ensure it contains all necessary source files
+3. Avoid setting to system directories or root paths
+4. Use absolute paths for reliability
+
+## Security Configuration
+
+### Ignore Patterns
+
+NetContextServer uses ignore patterns to protect sensitive files and optimize performance.
+
+#### Default Ignore Patterns
+These patterns are always active and cannot be disabled:
+```
+*.env
+appsettings.*.json
+*.pfx
+*.key
+*.pem
+*password*
+*secret*
+```
+
+#### Custom Ignore Patterns
+Add your own patterns for project-specific needs:
+```bash
+# Add patterns
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- add-ignore-patterns --patterns "*.generated.cs" "bin/*" "obj/*"
+
+# View current patterns
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- get-ignore-patterns
+```
+
+#### Persistent Ignore Patterns
+Patterns are stored in `ignore_patterns.json`. Location can be found using:
+```bash
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- get-state-file-location
+```
+
+### File Access Controls
+
+1. **Size Limits**
+   - Large files are truncated to prevent memory issues
+   - Default limit: 1MB per file
+   - Binary files are blocked
+
+2. **Path Validation**
+   - All file paths must be within base directory
+   - Symbolic links are resolved and validated
+   - Parent directory traversal (`..`) is blocked
+
+## Search Configuration
+
+### Text Search
+
+Text search is configured for:
+- Case-sensitive matching
+- Regular expression support
+- Line number reporting
+- Context lines around matches
+
+### Semantic Search
+
+Semantic search can be customized with:
+
+1. **Results Count**
+```bash
+# Customize number of results
+dotnet run --project src/NetContextClient/NetContextClient.csproj -- semantic-search --query "error handling" --top 10
+```
+
+2. **Index Management**
+- Files are automatically indexed on first search
+- Index is maintained in memory for performance
+- Reindexing occurs when files change
+
+## Performance Optimization
+
+### File Scanning
+
+1. **Excluded Directories**
+   - `bin` and `obj` directories are skipped by default
+   - Add custom directories to ignore for faster scanning
+
+2. **File Type Filtering**
+   - Focus on relevant file types
+   - Add ignore patterns for non-code files
+
+### Memory Management
+
+1. **File Content Caching**
+   - Recently accessed files are cached
+   - Large files are read in chunks
+
+2. **Search Index**
+   - Semantic search index is optimized for speed
+   - Index is updated incrementally
+
+## Integration Configuration
+
+### Cursor AI Setup
+
+1. **MCP Server Configuration**
+```json
+{
+  "command": "dotnet",
+  "args": ["run", "--project", "path/to/NetContextServer/src/NetContextServer/NetContextServer.csproj"]
+}
+```
+
+2. **Recommended Settings**
+   - Keep server running for better performance
+   - Configure in workspace settings for project-specific setup
+
+### CursorMCPMonitor Integration
+
+For debugging MCP communication:
+1. Install CursorMCPMonitor
+2. Configure logging level
+3. Monitor real-time interactions
+
+## Logging and Diagnostics
+
+### Log Levels
+Available log levels:
+- ERROR: Critical issues
+- WARN: Important warnings
+- INFO: General operation info
+- DEBUG: Detailed debugging info
+
+### Diagnostic Information
+- Server status
+- Connection details
+- Operation timing
+- Error traces
+
+## Best Practices
+
+1. **Project Structure**
+   - Set base directory at solution root
+   - Use consistent file organization
+   - Follow standard .NET project layout
+
+2. **Security**
+   - Review ignore patterns regularly
+   - Keep sensitive files outside source tree
+   - Use environment variables for secrets
+
+3. **Performance**
+   - Optimize ignore patterns
+   - Clean up unused files
+   - Monitor memory usage
+
+4. **Integration**
+   - Test configuration changes
+   - Verify file access patterns
+   - Monitor error logs
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Access Denied**
+   - Verify base directory setting
+   - Check file permissions
+   - Review ignore patterns
+
+2. **Search Not Working**
+   - Verify Azure OpenAI credentials
+   - Check file indexing status
+   - Review search patterns
+
+3. **Performance Issues**
+   - Optimize ignore patterns
+   - Clean up temporary files
+   - Review large file handling