nia-mcp-server 1.0.6__py3-none-any.whl → 1.0.8__py3-none-any.whl

nia_mcp_server/__init__.py

@@ -2,4 +2,4 @@
 NIA MCP Server - Proxy server for NIA Knowledge Agent
 """
 
-__version__ = "1.0.6"
+__version__ = "1.0.8"

nia_mcp_server/api_client.py

@@ -24,7 +24,7 @@ class NIAApiClient:
     def __init__(self, api_key: str, base_url: str = None):
         self.api_key = api_key
         # Remove trailing slash from base URL to prevent double slashes
-        self.base_url = (base_url or os.getenv("NIA_API_URL", "https://api.trynia.ai")).rstrip('/')
+        self.base_url = (base_url or os.getenv("NIA_API_URL", "https://apigcp.trynia.ai")).rstrip('/')
         self.client = httpx.AsyncClient(
             headers={
                 "Authorization": f"Bearer {api_key}",
@@ -400,6 +400,7 @@ class NIAApiClient:
         self, 
         url: str, 
         url_patterns: List[str] = None,
+        exclude_patterns: List[str] = None,
         max_age: int = None,
         only_main_content: bool = True
     ) -> Dict[str, Any]:
@@ -407,7 +408,8 @@ class NIAApiClient:
         try:
             payload = {
                 "url": url,
-                "url_patterns": url_patterns or []
+                "url_patterns": url_patterns or [],
+                "exclude_patterns": exclude_patterns or []
             }
             
             # Add optional parameters

nia_mcp_server/assets/rules/claude_rules.md

@@ -0,0 +1,270 @@
+# Nia Integration for Claude Desktop
+
+## Claude Desktop Configuration
+
+### 1. Project Structure
+When Nia is initialized for Claude Desktop, it creates:
+```
+.claude/
+├── nia_config.json      # Nia-specific settings
+├── indexed_repos.json   # Tracked repositories
+└── search_patterns.json # Common search patterns
+```
+
+### 2. Configuration File
+Create `.claude/nia_config.json`:
+
+```json
+{
+  "version": "1.0",
+  "defaultBehavior": {
+    "autoSuggestIndexing": true,
+    "includeSourcesInResponse": true,
+    "searchResultLimit": 5,
+    "deepResearchTimeout": 300
+  },
+  "searchPatterns": {
+    "architecture": "How is {feature} architected in {repo}?",
+    "implementation": "Show me the implementation of {feature}",
+    "patterns": "What patterns are used for {concern}?",
+    "debugging": "Find similar issues to {error}"
+  },
+  "workspaceRepos": [],
+  "frequentSearches": []
+}
+```
+
+## Claude-Specific Interaction Patterns
+
+### 1. Conversational Flow
+Claude should maintain context naturally:
+
+```
+User: "I'm working on a RAG implementation"
+Claude: I'll help you with RAG implementation. Let me search for the best examples and patterns.
+[Runs: nia_web_search "RAG implementation examples production ready"]
+
+I found several excellent RAG implementations. Would you like me to:
+1. Index these repositories for detailed analysis
+2. Compare different approaches
+3. Search for specific features you need
+```
+
+### 2. Proactive Assistance
+Anticipate user needs:
+
+- When user mentions a GitHub URL → Suggest indexing
+- When user asks about code → Check if repo is indexed first
+- When comparing options → Use deep research agent
+- When debugging → Search for similar issues
+
+### 3. Context-Aware Responses
+Maintain conversation context:
+
+```
+First message: User asks about authentication
+- Check indexed repos for auth implementations
+- Remember this context for follow-ups
+
+Second message: User asks "how about the middleware?"
+- Know they mean auth middleware
+- Search specifically for middleware in auth context
+- Reference previous findings
+```
+
+## Claude Desktop Workflows
+
+### 1. Project Understanding
+```markdown
+When user opens a new project:
+1. Detect project type from files
+2. Suggest indexing the repository
+3. Offer to index related dependencies
+4. Provide architecture overview
+```
+
+### 2. Code Generation
+```markdown
+When generating code:
+1. Search indexed repos for patterns
+2. Use found examples as reference
+3. Adapt to project's style
+4. Cite sources for transparency
+```
+
+### 3. Problem Solving
+```markdown
+When solving issues:
+1. Search for error messages
+2. Find similar problems and solutions
+3. Understand the context
+4. Provide step-by-step fixes
+```
+
+### 4. Learning & Teaching
+```markdown
+When explaining concepts:
+1. Use deep research for comprehensive overview
+2. Find real-world examples in indexed repos
+3. Show implementation variations
+4. Explain trade-offs with evidence
+```
+
+## Response Formatting for Claude
+
+### 1. Search Results Presentation
+```markdown
+## 🔍 Found in indexed repositories:
+
+**Authentication Implementation** (nextjs-app-template)
+- 📁 `middleware.ts:23-45` - Route protection
+- 📁 `lib/auth/session.ts:12-89` - Session management
+- 📁 `app/api/auth/route.ts:5-34` - API endpoints
+
+**Key Pattern:** Uses NextAuth with JWT strategy
+[Show relevant code snippet]
+```
+
+### 2. Code Examples
+Always provide context:
+```typescript
+// From: awesome-saas-starter/lib/auth/session.ts
+// This pattern handles refresh tokens elegantly
+export async function refreshSession(token: string) {
+  // ... implementation
+}
+// Note: This repo uses Redis for session storage
+```
+
+### 3. Comparative Analysis
+Structure comparisons clearly:
+```markdown
+## Comparison: Prisma vs Drizzle ORM
+
+Based on analysis of 15 production repositories:
+
+| Aspect | Prisma | Drizzle |
+|--------|--------|---------|
+| Type Safety | Excellent (generated) | Excellent (inferred) |
+| Performance | Good | Better |
+| Learning Curve | Gentle | Steeper |
+
+**Recommendation:** [Based on your use case...]
+```
+
+## Advanced Claude Behaviors
+
+### 1. Multi-Step Research
+For complex questions:
+```
+Step 1: Use nia_deep_research_agent for overview
+Step 2: Use nia_web_search for specific examples  
+Step 3: Index discovered repositories
+Step 4: Search indexed repos for details
+Step 5: Synthesize findings with citations
+```
+
+### 2. Intelligent Caching
+Remember within conversation:
+- Previously indexed repositories
+- Search results from earlier queries
+- User's project context
+- Technical preferences
+
+### 3. Error Recovery
+Handle failures gracefully:
+```
+If indexing fails:
+- Explain the issue clearly
+- Suggest alternatives
+- Offer to try again later
+- Provide manual workarounds
+```
+
+### 4. Documentation Indexing
+When users want to index documentation:
+```
+If user provides just a URL:
+- Default to indexing entire site with ["/*"]
+- Or ask: "Should I index the entire documentation or specific sections?"
+- Suggest common patterns: ["/docs/*", "/api/*", "/guide/*"]
+- Example: index_documentation "https://docs.example.com" ["/*"]
+```
+
+## Claude-Specific Commands
+
+### Quick Actions
+Recognize these patterns:
+
+- "Index this" → Index current repository
+- "Search for X" → Use appropriate search tool
+- "Compare X and Y" → Use deep research
+- "Find examples" → Web search then index
+- "Explain this code" → Search for patterns
+
+### Batch Operations
+Handle multiple requests:
+```
+User: "Index these repos: A, B, C and then compare their auth systems"
+Claude: I'll index all three repositories and then analyze their authentication approaches.
+[Runs multiple index_repository commands]
+[Waits for completion]
+[Runs search_codebase for auth patterns]
+[Provides comparative analysis]
+```
+
+## Best Practices for Claude
+
+### 1. Natural Language
+- Maintain conversational tone
+- Explain technical concepts clearly
+- Use analogies when helpful
+- Avoid jargon unless necessary
+
+### 2. Progressive Disclosure
+- Start with overview
+- Provide details on request
+- Link to deeper resources
+- Offer next steps
+
+### 3. Source Attribution
+- Always cite repositories
+- Include file paths and line numbers
+- Link to specific commits when relevant
+- Credit original authors
+
+### 4. Learning from Interaction
+- Note user preferences
+- Adapt search queries based on feedback
+- Refine suggestions over time
+- Build on previous conversations
+
+## Example Interactions
+
+### Architecture Understanding
+```
+User: "How does Vercel handle serverless functions?"
+Claude: I'll research how Vercel implements serverless functions.
+
+[Runs: nia_deep_research_agent "Vercel serverless functions architecture implementation"]
+
+Based on my research, Vercel's serverless architecture... [comprehensive explanation]
+
+I found several open-source projects that demonstrate this. Shall I index them for deeper analysis?
+```
+
+### Code Pattern Search
+```
+User: "Show me good examples of React Server Components"
+Claude: I'll search for production-ready React Server Components examples.
+
+[Runs: nia_web_search "React Server Components production examples 2024"]
+
+I found 5 excellent repositories using RSC. Let me index the most relevant one:
+
+[Runs: index_repository https://github.com/vercel/next-app-router-playground]
+
+Now I can show you specific patterns... [detailed examples]
+```
+
+Remember: Make Nia's capabilities feel like a natural extension of Claude's knowledge!

nia_mcp_server/assets/rules/cursor_rules.md

@@ -0,0 +1,64 @@
+# Nia MCP Tool Usage Guide
+
+Note: Nia is just "Nia" - not an acronym or "Neural Intelligent Assistant".
+
+## When to use each tool:
+
+### `list_repositories`
+Use when:
+- User asks what repos are available/indexed
+- Before searching to verify repo is indexed
+- User wants to see their indexed codebase list
+
+### `index_repository`
+Use when:
+- User mentions a GitHub URL
+- User wants to analyze a specific codebase
+- Before searching a new repository
+
+### `search_codebase`
+Use when:
+- User asks how something works in code
+- User wants to find specific implementations
+- User needs to understand code patterns
+- Searching within indexed repositories only
+
+### `search_documentation` 
+Use when:
+- User asks about documentation
+- Looking for API references
+- Searching indexed documentation sites
+
+### `nia_web_search`
+Use when:
+- Finding new repositories to index
+- Quick discovery of libraries/frameworks
+- Simple, direct searches
+- Looking for trending content
+
+### `nia_deep_research_agent`
+Use when:
+- Comparing multiple options (X vs Y)
+- Need structured analysis
+- Complex questions requiring synthesis
+- Evaluating pros/cons
+
+### `check_repository_status`
+Use when:
+- After starting indexing
+- User asks about indexing progress
+- Verifying if indexing completed
+
+### `index_documentation`
+Use when:
+- User wants to index documentation sites
+- User provides a documentation URL
+
+**Important**: If user doesn't specify URL patterns:
+- Default to `["/*"]` to index entire site
+- Or ask: "Should I index the entire documentation or specific sections?"
+- Common patterns: `["/docs/*", "/api/*", "/guide/*"]`
+
+### Other tools:
+- `delete_repository` - Remove indexed repo
+- `initialize_project` - Set up Nia rules in project

nia_mcp_server/assets/rules/nia_rules.md

@@ -0,0 +1,149 @@
+# Nia Knowledge Agent Integration Rules
+
+## Overview
+These rules guide AI assistants in effectively using Nia's knowledge search capabilities for codebase analysis, documentation search, and AI-powered research.
+
+Note: Nia is just "Nia" - not an acronym. It's the name of the knowledge search platform.
+
+## Core Principles
+
+### 1. Repository Management
+- **Always check indexed repositories** before searching with `list_repositories`
+- **Proactively suggest indexing** when users mention GitHub repositories
+- **Monitor indexing status** using `check_repository_status` for ongoing operations
+- **Index relevant repositories** discovered during web searches
+
+### 2. Search Strategy Selection
+
+#### Use `nia_web_search` for:
+- Finding specific repositories or documentation
+- Quick lookups and discovery tasks
+- Trending content searches
+- Finding similar content to a known URL
+- Simple, direct queries
+
+#### Use `nia_deep_research_agent` for:
+- Comparative analysis (X vs Y vs Z)
+- Evaluating pros and cons
+- Complex questions requiring synthesis
+- Structured output needs (tables, lists)
+- Questions with "best", "which is better", "compare"
+
+### 3. Query Optimization
+- **Use natural language queries** - Form complete questions, not just keywords
+- **Be specific and detailed** - "How does authentication work in NextAuth.js?" not "auth nextauth"
+- **Include context** - Mention specific technologies, frameworks, or use cases
+- **Leverage repository context** - Specify repositories when searching indexed codebases
+
+### 4. API Usage Best Practices
+- **Handle rate limits gracefully** - Free tier has 25 API request limit
+- **Cache results mentally** - Avoid redundant searches in the same conversation
+- **Batch operations** - Index multiple related repositories together
+- **Monitor status efficiently** - Check status periodically, not continuously
+
+### 5. Result Interpretation
+- **Provide actionable next steps** - Always suggest how to use the results
+- **Extract indexable content** - Identify repositories and docs from search results
+- **Format for readability** - Use markdown formatting for clear presentation
+- **Include sources** - Always show where information comes from
+
+### 6. Error Handling
+- **Explain API limits clearly** - Help users understand free tier limitations
+- **Suggest alternatives** - Provide workarounds when hitting limits
+- **Report issues helpfully** - Include enough context for debugging
+- **Guide to solutions** - Link to upgrade options when appropriate
+
+## Workflow Patterns
+
+### Pattern 1: New Project Research
+1. Use `nia_deep_research_agent` to understand the technology landscape
+2. Use `nia_web_search` to find specific implementations
+3. Index discovered repositories for detailed analysis
+4. Search indexed codebases for implementation details
+
+### Pattern 2: Codebase Understanding
+1. Check if repository is already indexed with `list_repositories`
+2. If not indexed, use `index_repository` and wait for completion
+3. Use `search_codebase` with specific technical questions
+4. Include code snippets and file references in responses
+
+### Pattern 3: Documentation Search
+1. Index documentation sites with `index_documentation`
+   - If no URL patterns specified, default to `["/*"]` for entire site
+   - Or ask user: "Which sections should I index? (e.g., /docs/*, /api/*, or /* for everything)"
+   - Common patterns: `["/docs/*", "/api/*", "/guide/*", "/reference/*"]`
+2. Use URL patterns to focus on relevant sections
+3. Search with `search_documentation` for specific topics
+4. Combine with code searches for complete understanding
+
+### Pattern 4: Technology Comparison
+1. Start with `nia_deep_research_agent` for structured comparison
+2. Follow up with `nia_web_search` for specific examples
+3. Index key repositories from each option
+4. Search codebases to understand implementation differences
+
+## Configuration
+
+### Environment Setup
+- **API Key**: Set `NIA_API_KEY` environment variable
+- **Never hardcode API keys** in code or configuration files
+- **Use .env files** for local development
+- **Secure key storage** in production environments
+
+### Project Structure
+When initialized, Nia projects should have:
+```
+.nia/
+├── config.json          # Project-specific settings
+├── indexed_repos.json   # Track indexed repositories
+└── search_history.json  # Cache common queries
+```
+
+## Integration Guidelines
+
+### With Version Control
+- Add `.nia/cache/` to `.gitignore`
+- Commit `.nia/config.json` for team sharing
+- Document indexed repositories in README
+
+### With CI/CD
+- Set `NIA_API_KEY` as secret environment variable
+- Run repository indexing in setup phase
+- Cache search results between builds
+
+### With IDEs
+- Configure workspace-specific indexed repositories
+- Set up quick search shortcuts
+- Integrate with code navigation features
+
+## Post-Initialization Guidance
+
+**After using the `initialize_project` tool, ALWAYS ask the user what they'd like to do next. DO NOT take action automatically.**
+
+Ask something like:
+> "Nia is now set up for your project! What would you like to do next?
+> 
+> 1. **Index your current repository** - I can index this codebase for intelligent search
+> 2. **Index documentation** - Index docs from frameworks/libraries you're using  
+> 3. **Research new technologies** - Use deep research to compare tools and frameworks
+> 4. **Search existing repositories** - Find and index repositories related to your project
+> 5. **Just chat** - I'm ready to help with any questions using Nia's tools when needed
+> 
+> What interests you most?"
+
+**Key rules:**
+- Always offer options but don't assume what the user wants
+- Explain briefly what each option does
+- Wait for the user to choose before taking any indexing actions
+- Be helpful but not pushy
+
+## Best Practices Summary
+
+1. **Be Proactive** - Suggest indexing relevant content
+2. **Be Efficient** - Use the right tool for each query type  
+3. **Be Helpful** - Provide clear next steps and context
+4. **Be Smart** - Learn from search results to improve future queries
+5. **Be Considerate** - Respect API limits and guide users appropriately
+6. **Be Patient** - After project initialization, ask what the user wants to do next
+
+Remember: Nia is designed to make AI-powered code and documentation search accessible. Help users unlock its full potential by following these guidelines.

nia_mcp_server/assets/rules/vscode_rules.md

@@ -0,0 +1,312 @@
+# NIA Integration for Visual Studio Code
+
+## VSCode-Specific Configuration
+
+### 1. Workspace Settings
+Configure `.vscode/settings.json` for NIA integration:
+
+```json
+{
+  "nia.defaultRepositories": [
+    "owner/main-project",
+    "owner/dependency-lib"
+  ],
+  "nia.searchHistory": true,
+  "nia.autoIndex": {
+    "enabled": true,
+    "patterns": ["github.com/*/*"]
+  },
+  "nia.apiEndpoint": "https://api.trynia.ai",
+  "nia.cacheTimeout": 3600
+}
+```
+
+### 2. Tasks Configuration
+Set up `.vscode/tasks.json` for common NIA operations:
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "NIA: Index Current Repository",
+      "type": "shell",
+      "command": "echo 'index_repository ${workspaceFolder}'",
+      "problemMatcher": []
+    },
+    {
+      "label": "NIA: List Indexed Repositories",
+      "type": "shell",
+      "command": "echo 'list_repositories'",
+      "problemMatcher": []
+    },
+    {
+      "label": "NIA: Search Codebase",
+      "type": "shell",
+      "command": "echo 'search_codebase \"${input:searchQuery}\"'",
+      "problemMatcher": []
+    }
+  ],
+  "inputs": [
+    {
+      "id": "searchQuery",
+      "type": "promptString",
+      "description": "Enter your search query"
+    }
+  ]
+}
+```
+
+### 3. Code Snippets
+Add to `.vscode/nia.code-snippets`:
+
+```json
+{
+  "Nia Index Repository": {
+    "prefix": "nia-index",
+    "body": [
+      "index_repository ${1:https://github.com/owner/repo}"
+    ],
+    "description": "Index a repository with Nia"
+  },
+  "Nia Search Code": {
+    "prefix": "nia-search",
+    "body": [
+      "search_codebase \"${1:How does authentication work?}\""
+    ],
+    "description": "Search indexed codebases"
+  },
+  "Nia Web Search": {
+    "prefix": "nia-web",
+    "body": [
+      "nia_web_search \"${1:find RAG implementation libraries}\""
+    ],
+    "description": "Search the web with Nia"
+  },
+  "Nia Deep Research": {
+    "prefix": "nia-research",
+    "body": [
+      "nia_deep_research_agent \"${1:compare X vs Y for use case}\""
+    ],
+    "description": "Perform deep research analysis"
+  }
+}
+```
+
+### 4. Launch Configuration
+Configure `.vscode/launch.json` for debugging with NIA context:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug with NIA Context",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/index.js",
+      "env": {
+        "NIA_API_KEY": "${env:NIA_API_KEY}",
+        "NIA_INDEXED_REPOS": "${workspaceFolder}/.nia/indexed_repos.json"
+      }
+    }
+  ]
+}
+```
+
+### 5. Extensions Recommendations
+Add to `.vscode/extensions.json`:
+
+```json
+{
+  "recommendations": [
+    "github.copilot",
+    "continue.continue",
+    "codeium.codeium"
+  ]
+}
+```
+
+## VSCode Command Palette Integration
+
+### Quick Commands
+Access via `Cmd/Ctrl + Shift + P`:
+
+1. **Nia: Index This Repository**
+   - Automatically indexes the current workspace
+   - Shows progress in status bar
+   - Notifies when complete
+
+2. **Nia: Search Symbol**
+   - Search for functions, classes, or variables
+   - Across all indexed repositories
+   - Jump to definition support
+
+3. **Nia: Explain Code**
+   - Select code and search for explanations
+   - Find similar implementations
+   - Understand patterns
+
+4. **Nia: Find Examples**
+   - Search for usage examples
+   - Filter by language or framework
+   - Copy-paste ready snippets
+
+## VSCode-Specific Workflows
+
+### 1. Project Onboarding
+When opening a new project:
+```
+1. Check if repo is indexed: list_repositories
+2. If not, index it: index_repository [current repo]
+3. Index related dependencies
+4. Search for architecture overview
+5. Create workspace documentation
+```
+
+### 2. Code Review Assistance
+During code reviews:
+```
+1. Search for similar patterns in indexed repos
+2. Find best practices for the specific feature
+3. Check for common pitfalls
+4. Suggest improvements based on examples
+```
+
+### 3. Debugging Workflow
+When debugging issues:
+```
+1. Search for error messages across repos
+2. Find similar bug fixes
+3. Understand the problematic code context
+4. Search for test cases
+```
+
+### 4. Learning & Documentation
+For learning new codebases:
+```
+1. Index the main repository
+2. Search for entry points (main, index, app)
+3. Understand the architecture
+4. Find example usage patterns
+```
+
+## Terminal Integration
+
+### Integrated Terminal Commands
+Use in VSCode's integrated terminal:
+
+```bash
+# Quick index
+alias nia-index='echo "index_repository $(git remote get-url origin)"'
+
+# Search current project
+alias nia-search='echo "search_codebase"'
+
+# List all indexed
+alias nia-list='echo "list_repositories"'
+```
+
+### PowerShell Functions
+For Windows users in `.vscode/powershell_profile.ps1`:
+
+```powershell
+function Nia-Index {
+    param($repo)
+    Write-Host "index_repository $repo"
+}
+
+function Nia-Search {
+    param($query)
+    Write-Host "search_codebase `"$query`""
+}
+```
+
+## Output Formatting for VSCode
+
+### 1. File References
+Format as clickable links:
+```
+📁 authentication/middleware.ts:45
+📁 lib/auth/session.ts:23-67
+📁 pages/api/auth/[...nextauth].ts:12
+```
+
+### 2. Code Blocks
+Use proper syntax highlighting:
+```typescript
+// From: lib/auth/session.ts
+export async function getSession(req: Request) {
+  // Implementation details
+}
+```
+
+### 3. Problem Markers
+For issues found during search:
+```
+⚠️ Warning: Deprecated pattern found
+   File: utils/oldAuth.js:34
+   Suggestion: Use new auth method
+
+❌ Error: Security vulnerability
+   File: api/user.js:56
+   Fix: Validate input parameters
+```
+
+## Keyboard Shortcuts
+Suggested keybindings for `.vscode/keybindings.json`:
+
+```json
+[
+  {
+    "key": "ctrl+shift+n i",
+    "command": "workbench.action.terminal.sendSequence",
+    "args": { "text": "index_repository " }
+  },
+  {
+    "key": "ctrl+shift+n s",
+    "command": "workbench.action.terminal.sendSequence",
+    "args": { "text": "search_codebase \"" }
+  },
+  {
+    "key": "ctrl+shift+n l",
+    "command": "workbench.action.terminal.sendSequence",
+    "args": { "text": "list_repositories\n" }
+  }
+]
+```
+
+## Performance Optimization
+
+### 1. Workspace-Specific Cache
+Store frequently searched queries:
+```
+.vscode/.nia-cache/
+├── search-results.json
+├── indexed-files.json
+└── common-queries.json
+```
+
+### 2. Search Filters
+Use repository context for faster searches:
+```
+search_codebase "authentication" repositories=["current-project"]
+```
+
+### 3. Batch Operations
+Index related repositories together:
+```
+index_repository repo1
+index_repository repo2
+index_repository repo3
+```
+
+### 4. Documentation Indexing
+When indexing documentation:
+- If user provides just a URL without patterns, use `["/*"]` to index everything
+- Or ask: "Should I index the entire documentation or specific sections?"
+- Common patterns: `["/docs/*", "/api/*", "/guide/*", "/reference/*"]`
+- Example: `index_documentation "https://docs.example.com" ["/*"]`
+- Can index multiple doc sites for comprehensive searches
+
+Remember: Make Nia feel like a native part of the VSCode experience!

nia_mcp_server/assets/rules/windsurf_rules.md

@@ -0,0 +1,92 @@
+# Nia Integration for Windsurf Cascade
+
+## Quick Reference
+- **List indexed repos**: `list_repositories`
+- **Index new repo**: `index_repository repo_url`
+- **Index docs**: `index_documentation url` (use `["/*"]` for entire site)
+- **Search code**: `search_codebase "your question"`
+- **Search docs**: `search_documentation "your question"`
+- **Web search**: `nia_web_search "find X library"`
+- **Deep research**: `nia_deep_research_agent "compare X vs Y"`
+
+## Windsurf Cascade Guidelines
+
+### 1. Flow-Based Development
+When using Cascade's flow feature:
+- Start flows by checking indexed repositories with `list_repositories`
+- Auto-suggest indexing when users mention GitHub URLs
+- Use Nia search results to inform multi-step flows
+- Reference specific files found via search in subsequent steps
+
+### 2. Memory Integration
+Create memories for frequently used repositories:
+- "Remember: Project X is indexed at owner/repo"
+- "Remember: Use Nia to search for implementation patterns"
+- Memories will automatically recall indexed repos context
+
+### 3. Code Understanding Workflow
+For codebase exploration:
+```
+1. Check if indexed: list_repositories
+2. If not indexed: index_repository [url]
+3. Search naturally: search_codebase "How does X work?"
+4. Use results in flow steps
+```
+
+### 4. Search Optimization for Cascade
+
+#### Natural Language Queries
+- Write complete questions: "How is authentication implemented in this Next.js app?"
+- Include context: "Find React hooks that handle user state"
+- Be specific: "Show me where API routes are defined"
+
+#### Multi-Step Flows
+1. Research: `nia_deep_research_agent "compare state management libraries"`
+2. Find examples: `nia_web_search "Redux toolkit examples"`
+3. Index chosen repo: `index_repository https://github.com/...`
+4. Explore patterns: `search_codebase "action creators pattern"`
+
+### 5. Cascade Commands
+
+When users ask about code:
+- Always check if the repository is indexed first
+- Suggest indexing if working with a new codebase
+- Use search results to build comprehensive responses
+- Create flows that combine multiple searches
+
+### 6. Best Practices
+
+#### For New Projects
+1. Index the main repository immediately
+2. Search for architecture overview: "How is this project structured?"
+3. Create memories of key findings
+4. Build flows based on discovered patterns
+
+#### For Debugging
+1. Search for error messages across indexed repos
+2. Find similar implementations that work
+3. Compare working vs broken code
+4. Create fix flow based on findings
+
+#### For Feature Development
+1. Search for similar features in indexed repos
+2. Understand existing patterns
+3. Find best practices examples
+4. Generate code following discovered patterns
+
+### 7. Documentation Indexing
+
+When indexing documentation:
+- If user provides just a URL without patterns, use `["/*"]` to index everything
+- Or ask: "Should I index the entire documentation or specific sections?"
+- Common patterns: `["/docs/*", "/api/*", "/guide/*", "/reference/*"]`
+- Example: `index_documentation "https://docs.example.com" ["/*"]`
+
+### 8. Integration Tips
+
+- Nia complements Cascade's abilities by providing deep code search
+- Use Nia for finding specific implementations
+- Let Cascade handle the creative synthesis
+- Combine both for powerful development workflows
+
+Remember: Nia provides the knowledge, Cascade provides the flow!

nia_mcp_server/project_init.py

@@ -20,7 +20,7 @@ class NIAProjectInitializer:
     
     def __init__(self, project_root: str):
         self.project_root = Path(project_root).resolve()
-        self.assets_dir = Path(__file__).parent.parent.parent / "assets"
+        self.assets_dir = Path(__file__).parent / "assets"
         self.templates_dir = self.assets_dir / "templates"
         self.rules_dir = self.assets_dir / "rules"
         

nia_mcp_server/server.py

@@ -5,6 +5,7 @@ import os
 import logging
 import json
 import asyncio
+import webbrowser
 from typing import List, Optional, Dict, Any
 from datetime import datetime
 from urllib.parse import urlparse
@@ -503,6 +504,7 @@ async def check_repository_status(repository: str) -> List[TextContent]:
 async def index_documentation(
     url: str,
     url_patterns: Optional[List[str]] = None,
+    exclude_patterns: Optional[List[str]] = None,
     max_age: Optional[int] = None,
     only_main_content: Optional[bool] = True
 ) -> List[TextContent]:
@@ -512,6 +514,7 @@ async def index_documentation(
     Args:
         url: URL of the documentation site to index
         url_patterns: Optional list of URL patterns to include in crawling (e.g., ["/docs/*", "/guide/*"])
+        exclude_patterns: Optional list of URL patterns to exclude from crawling (e.g., ["/blog/*", "/changelog/*"])
         max_age: Maximum age of cached content in seconds (for fast scraping mode)
         only_main_content: Extract only main content (removes navigation, ads, etc.)
         
@@ -520,6 +523,8 @@ async def index_documentation(
 
     Important:
         - When started indexing, prompt users to either use check_documentation_status tool or go to app.trynia.ai to check the status.
+        - By default, crawls the entire domain (up to 10,000 pages)
+        - Use exclude_patterns to filter out unwanted sections like blogs, changelogs, etc.
     """
     try:
         client = await ensure_api_client()
@@ -529,6 +534,7 @@ async def index_documentation(
         result = await client.create_data_source(
             url=url, 
             url_patterns=url_patterns,
+            exclude_patterns=exclude_patterns,
             max_age=max_age,
             only_main_content=only_main_content
         )
@@ -1366,6 +1372,159 @@ async def initialize_project(
                  "- The NIA MCP server is properly installed"
         )]
 
+@mcp.tool()
+async def visualize_codebase(
+    repository: str
+) -> List[TextContent]:
+    """
+    Open the graph visualization for an indexed repository in a browser.
+    
+    This tool launches a browser with the interactive graph visualization
+    that shows the code structure, relationships, and dependencies of
+    the indexed codebase.
+    
+    Args:
+        repository: Repository in owner/repo format (e.g., "facebook/react")
+        
+    Returns:
+        Status message with the URL that was opened
+        
+    Examples:
+        - visualize_codebase("facebook/react")
+        - visualize_codebase("langchain-ai/langchain")
+    """
+    try:
+        client = await ensure_api_client()
+        
+        logger.info(f"Looking up repository: {repository}")
+        
+        # List all repositories to find the matching one
+        repositories = await client.list_repositories()
+        
+        # Find the repository by name
+        matching_repo = None
+        for repo in repositories:
+            if repo.get("repository") == repository:
+                matching_repo = repo
+                break
+        
+        if not matching_repo:
+            # Try case-insensitive match as fallback
+            repository_lower = repository.lower()
+            for repo in repositories:
+                if repo.get("repository", "").lower() == repository_lower:
+                    matching_repo = repo
+                    break
+        
+        if not matching_repo:
+            return [TextContent(
+                type="text",
+                text=f"❌ Repository '{repository}' not found.\n\n"
+                     f"Available repositories:\n" +
+                     "\n".join(f"- {r.get('repository')}" for r in repositories if r.get('repository')) +
+                     "\n\nUse `list_repositories` to see all indexed repositories."
+            )]
+        
+        # Check if the repository is fully indexed
+        status = matching_repo.get("status", "unknown")
+        # Use the actual project ID if available, fall back to repository_id
+        repository_id = matching_repo.get("id") or matching_repo.get("repository_id")
+        
+        if not repository_id:
+            return [TextContent(
+                type="text",
+                text=f"❌ No repository ID found for '{repository}'. This may be a data inconsistency."
+            )]
+        
+        if status != "completed":
+            warning_msg = f"⚠️ Note: Repository '{repository}' is currently {status}.\n"
+            if status == "indexing":
+                warning_msg += "The visualization may show incomplete data.\n\n"
+            elif status == "error":
+                error_msg = matching_repo.get("error", "Unknown error")
+                warning_msg += f"Error: {error_msg}\n\n"
+            else:
+                warning_msg += "The visualization may not be available.\n\n"
+        else:
+            warning_msg = ""
+        
+        # Determine the base URL based on the API URL
+        api_base_url = client.base_url
+        if "localhost" in api_base_url or "127.0.0.1" in api_base_url:
+            # Local development
+            app_base_url = "http://localhost:3000"
+        else:
+            # Production
+            app_base_url = "https://app.trynia.ai"
+        
+        # Construct the visualization URL
+        visualization_url = f"{app_base_url}/visualize/{repository_id}"
+        
+        # Try to open the browser
+        try:
+            webbrowser.open(visualization_url)
+            browser_opened = True
+            open_msg = "✅ Opening graph visualization in your default browser..."
+        except Exception as e:
+            logger.warning(f"Failed to open browser: {e}")
+            browser_opened = False
+            open_msg = "⚠️ Could not automatically open browser."
+        
+        # Format the response
+        response_lines = [
+            f"# Graph Visualization: {repository}",
+            "",
+            warning_msg if warning_msg else "",
+            open_msg,
+            "",
+            f"**URL:** {visualization_url}",
+            "",
+        ]
+        
+        if matching_repo.get("display_name"):
+            response_lines.append(f"**Display Name:** {matching_repo['display_name']}")
+        
+        response_lines.extend([
+            f"**Branch:** {matching_repo.get('branch', 'main')}",
+            f"**Status:** {status}",
+            "",
+            "## Features Available:",
+            "- 🔍 Interactive force-directed graph",
+            "- 🎨 Color-coded node types (functions, classes, files, etc.)",
+            "- 🔗 Relationship visualization (calls, imports, inherits, etc.)",
+            "- 💬 Click on any node to chat with that specific code element",
+            "- 🔎 Search and filter capabilities",
+            "- 📊 Graph statistics and insights"
+        ])
+        
+        if not browser_opened:
+            response_lines.extend([
+                "",
+                "**Manual Access:**",
+                f"Copy and paste this URL into your browser: {visualization_url}"
+            ])
+        
+        return [TextContent(
+            type="text",
+            text="\n".join(response_lines)
+        )]
+        
+    except APIError as e:
+        logger.error(f"API Error in visualize_codebase: {e}")
+        if e.status_code == 403 or "free tier limit" in str(e).lower():
+            return [TextContent(
+                type="text",
+                text=f"❌ {str(e)}\n\n💡 Tip: Upgrade to Pro at https://trynia.ai/billing for unlimited access."
+            )]
+        else:
+            return [TextContent(type="text", text=f"❌ {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error in visualize_codebase: {e}")
+        return [TextContent(
+            type="text",
+            text=f"❌ Error opening visualization: {str(e)}"
+        )]
+
 # Resources
 
 # Note: FastMCP doesn't have list_resources or read_resource decorators

{nia_mcp_server-1.0.6.dist-info → nia_mcp_server-1.0.8.dist-info}/METADATA

@@ -1,18 +1,16 @@
 Metadata-Version: 2.4
 Name: nia-mcp-server
-Version: 1.0.6
-Summary: NIA Knowledge Agent - MCP server for intelligent codebase search
+Version: 1.0.8
+Summary: Nia Knowledge Agent
 Project-URL: Homepage, https://trynia.ai
 Project-URL: Documentation, https://docs.trynia.ai
-Project-URL: Repository, https://github.com/trynia/nia-mcp-server
-Project-URL: Issues, https://github.com/trynia/nia-mcp-server/issues
-Author-email: NIA Team <support@trynia.ai>
-License-Expression: MIT
+Author-email: Nia Team <founders@nozomio.com>
+License-Expression: AGPL-3.0
 License-File: LICENSE
 Keywords: ai,codebase,mcp,nia,search
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -203,7 +201,7 @@ Add to your Cline settings:
 ## Environment Variables
 
 - `NIA_API_KEY` (required) - Your NIA API key
-- `NIA_API_URL` (optional) - API endpoint (defaults to https://api.trynia.ai)
+- `NIA_API_URL` (optional) - API endpoint (defaults to https://apigcp.trynia.ai)
 
 ## Pricing
 

nia_mcp_server-1.0.8.dist-info/RECORD

@@ -0,0 +1,16 @@
+nia_mcp_server/__init__.py,sha256=7gOUBmOzahYrylDFhFFQLPegegf4dI-ZGt7UNfUVXho,84
+nia_mcp_server/__main__.py,sha256=XY11ESL4hctu-BBgtPATFZyd1o-O7wE7y-UOSoNs-hw,152
+nia_mcp_server/api_client.py,sha256=zcTWTDkG9KYj5xunx8A8t1JDLctJJqNqB_ZiGZc9H1M,24362
+nia_mcp_server/profiles.py,sha256=2DD8PFRr5Ij4IK4sPUz0mH8aKjkrEtkKLC1R0iki2bA,7221
+nia_mcp_server/project_init.py,sha256=T0-ziJhofL4L8APwnM43BLhxtlmOHaYH-V9PF2yXLw4,7138
+nia_mcp_server/rule_transformer.py,sha256=wCxoQ1Kl_rI9mUFnh9kG5iCXYU4QInrmFQOReZfAFVo,11000
+nia_mcp_server/server.py,sha256=m8tvape27a72NyQEho8_tT9z0plRGBR0kcEB6gSrqsw,65816
+nia_mcp_server/assets/rules/claude_rules.md,sha256=HNL5GJMUbFxSpNbIAJUQWqAywjMl4lf530I1in69aNY,7380
+nia_mcp_server/assets/rules/cursor_rules.md,sha256=hd6lhzNrK1ULQUYIEVeOnyKnuLKq4hmwZPbMqGUI1Lk,1720
+nia_mcp_server/assets/rules/nia_rules.md,sha256=mvdYrkoiRgxeROhtnRXCV53TX5B9wqLiCJ6oYTqSPfY,6345
+nia_mcp_server/assets/rules/vscode_rules.md,sha256=fqn4aJO_bhftaCGkVoquruQHf3EaREQJQWHXq6a4FOk,6967
+nia_mcp_server/assets/rules/windsurf_rules.md,sha256=PzU2as5gaiVsV6PAzg8T_-GR7VCyRQGMjAHcSzYF_ms,3354
+nia_mcp_server-1.0.8.dist-info/METADATA,sha256=A5e26Zda8sTmFMYoQnfeIOM1LEfXxiWnclFva2YMMGo,6766
+nia_mcp_server-1.0.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nia_mcp_server-1.0.8.dist-info/licenses/LICENSE,sha256=XYY1C3d9XyjAGuntC4mVWGrEhWIm-044Ji9ouO7hfLA,1557
+nia_mcp_server-1.0.8.dist-info/RECORD,,

nia_mcp_server-1.0.8.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2024 NIA (trynia.ai)
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Additional permissions under GNU AGPL version 3 section 7:
+
+If you modify this Program, or any covered work, by linking or combining it 
+with other code, such other code is not for that reason alone subject to any 
+of the requirements of the GNU Affero General Public License.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
+IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
+YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

nia_mcp_server-1.0.6.dist-info/RECORD

@@ -1,12 +0,0 @@
-nia_mcp_server/__init__.py,sha256=xrM4qDGEvxPXQYqVksy08mhmfAj0wIljhJPnYZYHea8,84
-nia_mcp_server/__main__.py,sha256=XY11ESL4hctu-BBgtPATFZyd1o-O7wE7y-UOSoNs-hw,152
-nia_mcp_server/api_client.py,sha256=dk9FkMljuekyjIw7Ij3athsoVNnu7E2b1l2xi2XtB1Y,24255
-nia_mcp_server/profiles.py,sha256=2DD8PFRr5Ij4IK4sPUz0mH8aKjkrEtkKLC1R0iki2bA,7221
-nia_mcp_server/project_init.py,sha256=Mtxvlg7FfdWumc2AdMXifht3V1b6sZvX4b7USbbwMvw,7152
-nia_mcp_server/rule_transformer.py,sha256=wCxoQ1Kl_rI9mUFnh9kG5iCXYU4QInrmFQOReZfAFVo,11000
-nia_mcp_server/server.py,sha256=B6aLTXkX2Mq5eBqDCV_WTumqtSm4bzDf2bHPVyVsgcA,59579
-nia_mcp_server-1.0.6.dist-info/METADATA,sha256=hN6ls8aDU9h83JuQ3AZ8VfLBsrKIVLGt-annSRXHbS8,6910
-nia_mcp_server-1.0.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nia_mcp_server-1.0.6.dist-info/entry_points.txt,sha256=V74FQEp48pfWxPCl7B9mihtqvIJNVjCSbRfCz4ww77I,64
-nia_mcp_server-1.0.6.dist-info/licenses/LICENSE,sha256=5jUPBVkZEicxSAZ91jOO7i8zXEPAHS6M0w8SSf6DftI,1071
-nia_mcp_server-1.0.6.dist-info/RECORD,,

nia_mcp_server-1.0.6.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-nia-mcp-server = nia_mcp_server.__main__:main

nia_mcp_server-1.0.6.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 NIA (trynia.ai)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.