philip-hayden/wi-graphql-mcp-server

wi-graphql-mcp-server

A Model Context Protocol (MCP) server implementing the Wildlife Insights GraphQL API. This server provides natural language tools for wildlife management and species identification.

🦌 Natural Language Interface for Wildlife Insights GraphQL API

A comprehensive Model Context Protocol (MCP) server that provides intuitive, natural language tools for accessing Wildlife Insights data. Perfect for wildlife management, species identification workflows, and Texas ranch operations.

🌟 Features

🎯 20+ Natural Language Tools

• Data Navigation: getMyOrganizations, exploreMyData, getMyProjects
• Species Identification: getIdentifyPhotosCount, submitIdentification, bulkIdentifyImages
• Analytics & Insights: getRanchManagementInsights, getSpeciesAnalytics, getProjectAnalytics
• Upload Management: createUpload, uploadImageWorkflow, completeUpload
• Advanced: executeGraphQL for custom queries

🦌 Texas Ranch Optimized

• Texas game species classification
• Ranch management goal alignment (conservation/hunting/ecotourism)
• Habitat management recommendations
• Seasonal monitoring guidance

🔧 Production Ready

• TypeScript implementation
• Comprehensive error handling
• Complete memory bank documentation
• Professional deployment options

🚀 Quick Start

Installation

# Install from NPM (recommended)
npm install -g wildlife-insights-mcp

# Or from source
git clone https://github.com/yourusername/wildlife-insights-mcp.git
cd wildlife-insights-mcp
npm install

Development

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

MCP Client Configuration

For Cline/Cursor:

{
  "mcpServers": {
    "wildlife-insights": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": ["./node_modules/tsx/dist/cli.mjs", "src/server.ts"],
      "cwd": "/path/to/wildlife-insights-mcp",
      "env": {
        "WI_GRAPHQL_ENDPOINT": "https://api.wildlifeinsights.org/graphql",
        "WI_BEARER_TOKEN": "your_token_here"
      }
    }
  }
}

📖 Usage Examples

🏠 Organization Discovery

// Find your organizations
await use_mcp_tool("wildlife-insights", "getMyOrganizations")

📊 Project Analytics

// Get Texas ranch management insights
await use_mcp_tool("wildlife-insights", "getRanchManagementInsights", {
  projectId: "2010935",
  ranchGoals: "balanced"
})

🦊 Species Analysis

// Analyze species in your project
await use_mcp_tool("wildlife-insights", "getSpeciesAnalytics", {
  projectId: "2010935"
})

📷 Identification Workflow

// Check pending identifications
await use_mcp_tool("wildlife-insights", "getIdentifyPhotosCount", {
  projectId: "2010935"
})

// Get images for identification
await use_mcp_tool("wildlife-insights", "getImagesForIdentification", {
  projectId: "2010935",
  limit: 20
})

📤 Upload Management

// Complete upload workflow
await use_mcp_tool("wildlife-insights", "uploadImageWorkflow", {
  projectId: "2010935",
  deploymentId: "2420851",
  fileName: "camera001.jpg",
  fileSize: "1024000"
})

🔧 Authentication

Option 1: Environment Variable

export WI_BEARER_TOKEN="your_bearer_token_here"
npm run dev

Option 2: Runtime Setup

// Set token for this session
await use_mcp_tool("wildlife-insights", "auth.setToken", {
  token: "your_bearer_token_here"
})

🏗️ Development

Project Structure

├── src/
│   ├── server.ts          # Main MCP server with all tools
│   ├── wiClient.ts        # GraphQL client wrapper
│   └── schemas/
│       └── operations.ts  # GraphQL query definitions
├── memory-bank/           # Complete project documentation
│   ├── projectbrief.md    # Core requirements
│   ├── productContext.md  # Problem/solution fit
│   ├── activeContext.md   # Current work focus
│   ├── systemPatterns.md  # Architecture patterns
│   ├── techContext.md     # Technical implementation
│   └── progress.md        # Status and roadmap
├── dist/                  # Compiled JavaScript (auto-generated)
└── examples/              # MCP client configurations

Adding New Tools

1. Add GraphQL queries to src/schemas/operations.ts
2. Register tools in src/server.ts
3. Update memory bank documentation
4. Test with real API calls

📋 Available Tools

🏢 Organization & Project Management

• getMyOrganizations - Discover accessible organizations
• getMyProjects - Navigate project hierarchy
• exploreMyData - Step-by-step data exploration
• getProjectDetails - Comprehensive project information

📊 Analytics & Insights

• getProjectAnalytics - Overall project metrics
• getSpeciesAnalytics - Species pattern analysis
• getRanchManagementInsights - Texas-specific recommendations
• getDeploymentAnalytics - Camera deployment optimization

🦊 Species Identification

• getIdentifyPhotosCount - Count pending identifications
• getImagesForIdentification - Retrieve images for processing
• submitIdentification - Submit species identification
• bulkIdentifyImages - Process multiple images
• getIdentificationWorkflow - Monitor progress

📤 Upload Management

• createUpload - Create upload sessions
• getUploadUrl - Get signed upload URLs
• completeUpload - Finalize upload sessions
• uploadImageWorkflow - Complete upload workflow

🔧 System & Advanced

• executeGraphQL - Run custom GraphQL queries
• auth.setToken - Manage authentication
• auth.refreshToken - Token management
• whoami - Server information

🌍 Texas Ranch Focus

This MCP server is specifically optimized for Texas ranch wildlife management:

• Game Species: White-tailed deer, feral hogs, collared peccary
• Management Goals: Conservation, hunting, ecotourism, balanced approaches
• Habitat Types: Texas ecosystems and seasonal patterns
• Regulatory Context: Texas wildlife regulations and best practices

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Update memory bank documentation
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Wildlife Insights: GraphQL API and platform
• MCP SDK: Model Context Protocol implementation
• Texas Ranchers: Real-world use case and feedback

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Complete memory bank in memory-bank/ directory

Made with ❤️ for wildlife conservation and ranch management