metadata

title: 🕉 KarmaCheck - Spiritual Guidance & MCP Server
emoji: 🕉
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.33.1
app_file: app.py
pinned: true
license: mit
short_description: Universal wisdom AI with MCP server
tags:
  - mcp-server-track
  - spiritual-guidance
  - ancient-wisdom
  - life-coaching
  - ethical-guidance
  - track-1
  - mcp-server
  - llamaindex
  - rag
video_overview: https://youtu.be/4XG0SDb7BTw
collection: https://huggingface.co/collections/Agents-MCP-Hackathon

🕉️ KarmaCheck - Spiritual Guidance with MCP Server

KarmaCheck is an AI-powered spiritual assistant that provides guidance based on ancient Vedic wisdom. It combines Retrieval-Augmented Generation (RAG) with Vedic scriptures to offer meaningful insights for modern life challenges.

✨ Features

🔮 Spiritual Guidance: Get personalized advice based on Vedic principles
📚 Sacred Texts: Draws from Bhagavad Gita, Upanishads, and dharmic teachings
🤖 MCP Server: Integrate with Claude Desktop for seamless AI interactions
🌟 Daily Wisdom: Receive daily spiritual insights
⚖️ Ethical Analysis: Analyze dilemmas using dharmic principles
🎯 Concept Explanation: Understand spiritual concepts deeply

🚀 Quick Start

1. Installation

# Clone or download the project
git clone <your-repo-url>
cd karmacheck

# Install dependencies
pip install -r requirements.txt

2. Get Hugging Face API Token

Go to Hugging Face Settings
Create a new token (read access is sufficient)
Copy the token

3. Configuration

# Copy the example environment file
cp .env.example .env

# Edit .env and add your token
HUGGINGFACE_API_TOKEN=your_actual_token_here

4. Run the Application

python karma_check.py

The app will be available at:

🌐 Web UI: http://localhost:7860
🔧 MCP Server: Same address for Claude Desktop

🤖 Claude Desktop Integration

Setup Steps:

Install Claude Desktop (if not already installed)

Configure MCP Server:

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "karmacheck": {
      "command": "python",
      "args": ["/absolute/path/to/karma_check.py"],
      "env": {
        "HUGGINGFACE_API_TOKEN": "your_hf_token_here"
      }
    }
  }
}

Update the path: Replace /absolute/path/to/karma_check.py with the actual path to your file
Restart Claude Desktop

Available MCP Tools:

get_spiritual_guidance(question) - Main spiritual guidance function
find_vedic_quotes(topic) - Find quotes on specific topics
explain_concept(concept) - Explain spiritual concepts
daily_wisdom() - Get daily spiritual insight
analyze_dilemma(situation) - Analyze ethical dilemmas

Example Usage in Claude:

User: Use KarmaCheck to help me understand karma
Claude: I'll use the KarmaCheck tool to explain karma for you.

[Uses explain_concept("karma")]

Based on Vedic teachings, karma refers to...

📚 Data Sources

The system comes with sample Vedic texts including:

Bhagavad Gita verses and commentary
Upanishad teachings
Dharmic principles and guidance

Adding Your Own Texts:

Create text files in the data/ directory
Include verses, commentary, and context
Restart the application to rebuild the index

🛠️ Technical Details

RAG System: LlamaIndex with FAISS vector store
Embeddings: Hugging Face all-MiniLM-L6-v2
LLM: Mistral-7B-Instruct via Hugging Face Inference API
UI: Gradio with MCP server support
Vector Storage: Local FAISS index with persistence

🔧 Customization

Model Configuration:

Edit the configuration in karma_check.py:

@dataclass
class KarmaCheckConfig:
    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
    llm_model: str = "mistralai/Mistral-7B-Instruct-v0.1"
    chunk_size: int = 512
    similarity_top_k: int = 5
    # ... other settings

Adding New MCP Tools:

@gr.mcp_tool()
def your_new_tool(parameter: str) -> str:
    """Description of your tool for MCP clients"""
    # Your implementation
    return result

📖 Example Questions

Life & Purpose:

"How can I find my life's true purpose?"
"I feel lost in my career. What should I do?"
"How do I know if I'm following my dharma?"

Relationships:

"How should I handle conflicts with family?"
"What does love mean spiritually?"
"How can I forgive someone who hurt me?"

Personal Growth:

"How do I overcome anxiety?"
"What is the spiritual meaning of suffering?"
"How can I develop inner peace?"

Ethics:

"I'm facing an ethical dilemma at work"
"How do I balance personal desires with duty?"
"What does righteous living mean today?"

🐛 Troubleshooting

Common Issues:

Token Error: Make sure HUGGINGFACE_API_TOKEN is set correctly
Model Loading: Hugging Face models may take time to load initially
Dependencies: Ensure all packages are installed: pip install -r requirements.txt
Claude Desktop: Use absolute file paths in MCP configuration

Getting Help:

Check the console output for detailed error messages
Ensure stable internet connection for Hugging Face API
Verify Python version (3.8+ recommended)

🙏 Contributing

Contributions are welcome! Areas for improvement:

Additional Vedic texts and translations
Enhanced spiritual analysis features
Better multilingual support
Advanced meditation and practice recommendations

📜 License

This project is open source. Use it for personal growth and spiritual development.

🕉️ Acknowledgments

Ancient Vedic sages for their timeless wisdom
Hugging Face for democratizing AI
Gradio team for excellent tooling
LlamaIndex for powerful RAG capabilities

"यदा यदा हि धर्मस्य ग्लानिर्भवति भारत। अभ्युत्थानमधर्मस्य तदात्मानं सृजाम्यहम्॥"

"Whenever there is a decline in righteousness and an increase in unrighteousness, I manifest myself." - Bhagavad Gita 4.7

Spaces:

Agents-MCP-Hackathon
/

KarmaCheck

Running