npm package: @nifelabs/mcp-server
Description: Model Context Protocol server for Nife.io GraphQL API
Author: Nife Team
Latest version: 1.0.0

# Nife.io MCP Server

<div align="center">

[![PyPI version](https://badge.fury.io/py/nife-mcp-server.svg)](https://badge.fury.io/py/nife-mcp-server)
[![npm version](https://badge.fury.io/js/@nife%2Fmcp-server.svg)](https://badge.fury.io/js/@nife%2Fmcp-server)
[![CI](https://github.com/nife-io/nife-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/nife-io/nife-mcp-server/actions/workflows/ci.yml)
[![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 @nife/mcp-server
```

### Option 3: From Source

```bash
git clone https://github.com/nife-io/nife-mcp-server.git
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

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "nife": {
      "command": "npx",
      "args": ["-y", "@nife/mcp-server"],
      "env": {
        "NIFE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

Your Nife.io integration is now active! 🎉

## 📚 Documentation

- [Quick Start Guide](QUICKSTART.md) - Get started in 5 minutes
- [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/nife-io/nife-mcp-server.git
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
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 with ❤️ by the Nife.io team**

[Website](https://nife.io) • [Documentation](https://docs.nife.io) • [Blog](https://blog.nife.io)

</div>