# Nife.io MCP Server

<div align="center">

[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/nife-mcp-server)](https://pepy.tech/project/nife-mcp-server)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**A Model Context Protocol (MCP) server that interfaces with the Nife.io GraphQL API**

[Installation](#-installation) •
[Quick Start](#-quick-start) •
[Documentation](#-documentation) •
[Contributing](#-contributing)

</div>

---

##  Overview

Nife MCP Server provides a standardized interface to interact with Nife.io's GraphQL API through the Model Context Protocol, enabling seamless integration with Claude Desktop and other MCP-compatible applications.

###  Key Features

-  **Intelligent Schema Discovery** - Automatically discovers and adapts to the GraphQL schema
-  **Dynamic Tool Generation** - Creates MCP tools on-the-fly from schema
-  **Zero Configuration** - Works out of the box with minimal setup
-  **Secure Authentication** - Bearer token support with flexible configuration
-  **Multiple Install Methods** - PyPI, NPM, or GitHub
-  **Cross-Platform** - Works on macOS, Linux, and Windows
-  **Production Ready** - Comprehensive error handling and logging

##  Installation

### Option 1: PyPI (Recommended for Python users)

```bash
pip install nife-mcp-server
```

### Option 2: NPM (Best for Claude Desktop)

```bash
npx @nifelabs/mcp-server@latest
```

### Option 3: From Source

```bash
git clone https://github.com/nifetency/nife-mcp-graphql
cd nife-mcp-server
pip install -r requirements.txt
```

##  Quick Start

### 1. Get Your Access Token

```bash
nifectl auth login
nifectl auth token
```

### 2. Configure Claude Desktop

You can use the Nife MCP Server in three ways depending on your setup.

------------------------------------------------------------------------

### 1. Recommended: Using NPX (No Installation Required)

This is the easiest way to get started.

``` json
{
  "mcpServers": {
    "nife": {
      "command": "npx",
      "args": ["--yes", "@nifelabs/mcp-server@latest"],
      "env": {
        "NIFE_ACCESS_TOKEN": "your_token_here",
        "PYTHON": "PYTHON_PATH"

      }
    }
  }
}
```

------------------------------------------------------------------------

### 2.  Using Python (Installed via pip)

If you installed the package via pip:

``` bash
pip install nife-mcp-server
```

Use this configuration:

``` json
{
  "mcpServers": {
    "nife": {
      "command": "python",
      "args": ["-m", "nife_mcp_server"],
      "env": {
        "NIFE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

------------------------------------------------------------------------

### 3.  Local Development (Source Code)

If you're running from source:

``` json
{
  "mcpServers": {
    "nife": {
      "command": "python",
      "args": ["-m", "nife_mcp_server.intelligent_main"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\nife-mcp-server\\src",
        "NIFE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

 Replace the `PYTHONPATH` with your local project path.

------------------------------------------------------------------------

##  Environment Variables

  Variable              Description
  --------------------- ---------------------------------
  `NIFE_ACCESS_TOKEN`   Your API access token from Nife

------------------------------------------------------------------------



### 3. Restart Claude Desktop

Your Nife.io integration is now active! 🎉

## 📚 Documentation

- [Quick Start Guide](QUICKSTART.md) - Get started in 5 minutes
- [Hosted connector (URL-based)](HOSTED.md) - Deploy the remote server and connect by URL
- [API Documentation](ENDPOINT_GUIDE.md) - Complete API reference
- [Release Guide](RELEASE_GUIDE.md) - For contributors and maintainers
- [Contributing](CONTRIBUTING.md) - How to contribute

##  Usage

### Starting the Server

```bash
# If installed via pip
nife-mcp-server

# If running from source
python -m nife_mcp_server.intelligent_main
```

The server will start on `http://0.0.0.0:5000`

### Environment Variables

- `NIFE_ACCESS_TOKEN` - Your Nife.io access token
- `NIFE_API_ENDPOINT` - Custom GraphQL endpoint (optional)

### Example Usage with Claude

Once configured, you can ask Claude:

```
"List all my applications in Nife.io"
"Show me the status of my deployments"
"Create a new application called 'my-app'"
```

##  Architecture

```
┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │ MCP Protocol
┌────────▼────────┐
│  Nife MCP Server│
└────────┬────────┘
         │ GraphQL
┌────────▼────────┐
│   Nife.io API   │
└─────────────────┘
```

### Core Components

- **Schema Manager** - Intelligent GraphQL schema introspection
- **Tool Generator** - Dynamic MCP tool creation
- **Query Builder** - Smart query construction
- **Authentication** - Secure token management

##  API Endpoints

### MCP Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/mcp/context` | GET | Retrieve model context |
| `/api/mcp/context` | POST | Update model context |
| `/api/mcp/schema` | GET | Get GraphQL schema |
| `/api/mcp/query` | POST | Execute custom queries |
| `/api/mcp/health` | GET | Health check |

### GraphQL Integration

The server provides full access to Nife.io's GraphQL API:

-  Query all resources (apps, deployments, etc.)
-  Execute mutations (create, update, delete)
-  Custom query execution
-  Schema introspection

##  Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/nifetency/nife-mcp-graphql
cd nife-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -e .  # Install in editable mode



# Run the server
cd src
python -m nife_mcp_server.intelligent_main
```

### Project Structure

```
nife-mcp-server/
├── src/
│   └── nife_mcp_server/
│       ├── intelligent_main.py  # Main server logic
│       ├── schema_manager.py    # GraphQL schema handling
│       └── routes/
│           └── mcp.py          # MCP route handlers
├── tests/                      # Test suite
├── docs/                       # Documentation
└── bin/                        # Executable scripts
```

### Running Tests

```bash
pytest
pytest --cov=nife_mcp_server  # With coverage
```

##  Contributing

We love contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Ways to Contribute

-  Report bugs
-  Suggest features
-  Improve documentation
-  Submit pull requests

### Development Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

##  Stats

![GitHub stars](https://img.shields.io/github/stars/nife-io/nife-mcp-server?style=social)
![GitHub forks](https://img.shields.io/github/forks/nife-io/nife-mcp-server?style=social)
![GitHub issues](https://img.shields.io/github/issues/nife-io/nife-mcp-server)
![GitHub pull requests](https://img.shields.io/github/issues-pr/nife-io/nife-mcp-server)

##  License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

##  Acknowledgments

- Built for the [Model Context Protocol](https://modelcontextprotocol.io/)
- Powered by [Nife.io](https://nife.io)
- Designed for [Claude Desktop](https://claude.ai/desktop)

##  Support

-  Email: support@nife.io
-  Issues: [GitHub Issues](https://github.com/nife-io/nife-mcp-server/issues)
-  Discussions: [GitHub Discussions](https://github.com/nife-io/nife-mcp-server/discussions)
-  Documentation: [Full Docs](https://github.com/nife-io/nife-mcp-server#readme)

##  Roadmap

- [ ] WebSocket support for real-time updates
- [ ] GraphQL subscriptions
- [ ] Enhanced caching layer
- [ ] Query batching
- [ ] Metrics and monitoring
- [ ] Docker Compose examples
- [ ] Kubernetes manifests

##  Star History

If you find this project useful, please consider giving it a star!

[![Star History Chart](https://api.star-history.com/svg?repos=nife-io/nife-mcp-server&type=Date)](https://star-history.com/#nife-io/nife-mcp-server&Date)

---

<div align="center">

**Made by the Nife.io team**

[Website](https://nife.io) • [Documentation](https://docs.nife.io) • [Blog](https://blog.nife.io) • [MCP Open Source](https://nife.io/mcp_opensource)

</div>