nia-mcp-server 1.0.5__tar.gz → 1.0.7__tar.gz

{nia_mcp_server-1.0.5 → nia_mcp_server-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nia-mcp-server
-Version: 1.0.5
+Version: 1.0.7
 Summary: NIA Knowledge Agent - MCP server for intelligent codebase search
 Project-URL: Homepage, https://trynia.ai
 Project-URL: Documentation, https://docs.trynia.ai

{nia_mcp_server-1.0.5 → nia_mcp_server-1.0.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nia-mcp-server"
-version = "1.0.5"
+version = "1.0.7"
 description = "NIA Knowledge Agent - MCP server for intelligent codebase search"
 readme = "README.md"
 requires-python = ">=3.8"

{nia_mcp_server-1.0.5 → nia_mcp_server-1.0.7}/src/nia_mcp_server/__init__.py

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

{nia_mcp_server-1.0.5 → nia_mcp_server-1.0.7}/src/nia_mcp_server/api_client.py

@@ -137,7 +137,18 @@ class NIAApiClient:
         try:
             response = await self.client.get(f"{self.base_url}/v2/repositories")
             response.raise_for_status()
-            return response.json()
+            data = response.json()
+            
+            # Ensure we always return a list
+            if not isinstance(data, list):
+                logger.error(f"Unexpected response type from list_repositories: {type(data)}, data: {data}")
+                # If it's a dict with an error message, raise it
+                if isinstance(data, dict) and "error" in data:
+                    raise APIError(f"API returned error: {data['error']}")
+                # Otherwise return empty list
+                return []
+            
+            return data
         except httpx.HTTPStatusError as e:
             logger.error(f"Caught HTTPStatusError in list_repositories: status={e.response.status_code}, detail={e.response.text}")
             raise self._handle_api_error(e)
@@ -336,6 +347,53 @@ class NIAApiClient:
             logger.error(f"Failed to delete repository: {e}")
             return False
     
+    async def rename_repository(self, owner_repo: str, new_name: str) -> Dict[str, Any]:
+        """Rename a repository's display name."""
+        try:
+            # Check if this looks like owner/repo format (contains /)
+            if '/' in owner_repo:
+                # First, get the repository ID
+                status = await self.get_repository_status(owner_repo)
+                if not status:
+                    raise APIError(f"Repository {owner_repo} not found", 404)
+                
+                # Extract the repository ID from status
+                repo_id = status.get("repository_id") or status.get("id")
+                if not repo_id:
+                    # Try to get it from list as fallback
+                    repos = await self.list_repositories()
+                    for repo in repos:
+                        if repo.get("repository") == owner_repo:
+                            repo_id = repo.get("repository_id") or repo.get("id")
+                            break
+                
+                if not repo_id:
+                    raise APIError(f"No repository ID found for {owner_repo}", 404)
+                    
+                # Rename using the ID
+                response = await self.client.patch(
+                    f"{self.base_url}/v2/repositories/{repo_id}/rename",
+                    json={"new_name": new_name}
+                )
+                response.raise_for_status()
+                return response.json()
+            else:
+                # Assume it's already a repository ID
+                response = await self.client.patch(
+                    f"{self.base_url}/v2/repositories/{owner_repo}/rename",
+                    json={"new_name": new_name}
+                )
+                response.raise_for_status()
+                return response.json()
+                
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except APIError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to rename repository: {e}")
+            raise APIError(f"Failed to rename repository: {str(e)}")
+    
     # Data Source methods
     
     async def create_data_source(
@@ -408,6 +466,22 @@ class NIAApiClient:
             logger.error(f"Failed to delete data source: {e}")
             return False
     
+    async def rename_data_source(self, source_id: str, new_name: str) -> Dict[str, Any]:
+        """Rename a data source's display name."""
+        try:
+            response = await self.client.patch(
+                f"{self.base_url}/v2/data-sources/{source_id}/rename",
+                json={"new_name": new_name}
+            )
+            response.raise_for_status()
+            return response.json()
+            
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except Exception as e:
+            logger.error(f"Failed to rename data source: {e}")
+            raise APIError(f"Failed to rename data source: {str(e)}")
+    
     async def query_unified(
         self,
         messages: List[Dict[str, str]],

nia_mcp_server-1.0.7/src/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-1.0.7/src/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-1.0.7/src/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.