splitwise-mcp 0.1.0__tar.gz

splitwise_mcp-0.1.0/.env.example

@@ -0,0 +1,5 @@
+SPLITWISE_CONSUMER_KEY=your_consumer_key
+SPLITWISE_CONSUMER_SECRET=your_consumer_secret
+SPLITWISE_API_KEY=your_api_key
+GEMINI_API_KEY=your_gemini_key
+DEEPGRAM_API_KEY=your_deepgram_key

splitwise_mcp-0.1.0/.gitignore

@@ -0,0 +1,140 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   with no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+py_venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# OS specific files
+.DS_Store
+Thumbs.db

splitwise_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 User
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

splitwise_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: splitwise-mcp
+Version: 0.1.0
+Summary: MCP server for Splitwise integration
+Author-email: User <user@example.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: deepgram-sdk>=3.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: google-genai>=0.1.0
+Requires-Dist: mcp[cli]>=0.1.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: sounddevice>=0.4.6
+Requires-Dist: splitwise>=3.0.0
+Requires-Dist: streamlit>=1.30.0
+Requires-Dist: uvicorn>=0.20.0

splitwise_mcp-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Splitwise MCP Server
+
+[![MCP](https://img.shields.io/badge/MCP-Enabled-blue)](https://modelcontextprotocol.io)
+[![Smithery](https://smithery.ai/badge/splitwise-mcp)](https://smithery.ai/server/splitwise-mcp)
+
+A Model Context Protocol (MCP) server that integrates with [Splitwise](https://splitwise.com). Connect your AI assistant (Claude, Cursor, etc.) to manage Splitwise expenses using natural language — with voice support!
+
+## How It Works
+
+```mermaid
+flowchart LR
+    Client[Claude / Cursor] -->|MCP| Server[splitwise-mcp]
+    Server -->|audio| Deepgram[Deepgram STT]
+    Deepgram -->|text| Gemini[Gemini 3 Flash]
+    Gemini -->|action| Splitwise[Splitwise API]
+```
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `voice_command` | Send audio → Deepgram transcribes → Gemini processes → Splitwise executes |
+| `text_command` | Send text → Gemini processes → Splitwise executes |
+| `add_expense` | Add expenses with support for groups, percentages, exclusions, and specific payers |
+| `delete_expense` | Delete an expense by ID |
+| `list_friends` | List your Splitwise friends |
+| `configure_splitwise` | Configure API credentials |
+| `login_with_token` | Login with OAuth2 token |
+
+**Smart Name Matching**: If Deepgram transcribes "Humeet" but your friend is "Sumeet", Gemini will ask for clarification instead of guessing.
+
+### Advanced Splits
+- **Percentages**: "Split 40% for me and 60% for Alice"
+- **Groups**: "Add to Apartment group" (Auto-fetches members)
+- **Exclusions**: "Add to Apartment but exclude Bob"
+- **Payer**: "Alice paid $50"
+- **Deletion**: "Delete expense 12345"
+
+## Installation
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/hubshashwat/the-splitwise-mcp.git
+   cd the-splitwise-mcp
+   ```
+
+2. **Create and activate a virtual environment**:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+
+3. **Install the package**:
+   ```bash
+   pip install -e .
+   ```
+
+4. **Configure API keys** — copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+   Then edit `.env` with your keys:
+   ```bash
+   SPLITWISE_CONSUMER_KEY=...  # From Splitwise (https://secure.splitwise.com/apps/new)
+   SPLITWISE_CONSUMER_SECRET=... # From Splitwise
+   SPLITWISE_API_KEY=...       # From Splitwise
+   GEMINI_API_KEY=...          # From Google AI Studio
+   DEEPGRAM_API_KEY=...        # From Deepgram Console
+   ```
+
+## Usage
+
+### With Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "splitwise": {
+      "command": "/path/to/splitwise-mcp/.venv/bin/splitwise-mcp"
+    }
+  }
+}
+```
+
+Then in Claude: *"Add an expense of 50 with Sumeet for dinner"*
+
+### With Cursor
+
+Add to Cursor's MCP settings with the same command path.
+
+### Terminal Agent (Optional)
+
+For direct voice testing without an MCP client:
+
+```bash
+.venv/bin/python run_agent.py
+```
+
+Commands: `v` (voice), `t` (text), `q` (quit)
+
+### Remote Access (SSE)
+
+To run the MCP server over HTTP for remote clients:
+
+```bash
+.venv/bin/uvicorn splitwise_mcp.sse:app --host 0.0.0.0 --port 8000
+```
+
+Connect via: `http://YOUR_IP:8000/sse`
+
+## Development
+
+Run tests:
+```bash
+.venv/bin/python tests/test_logic.py
+```
+
+## Troubleshooting
+
+### Microphone Issues (macOS)
+If the agent says "Recording finished" immediately but captures no audio (Volume: 0.0), your terminal likely lacks microphone permission.
+
+1. Go to **System Settings > Privacy & Security > Microphone**.
+2. Enable access for your terminal app (Terminal, iTerm, VS Code, etc.).
+3. **Restart your terminal** for changes to take effect.
+
+
+## License
+
+MIT

splitwise_mcp-0.1.0/debug_audio.py

@@ -0,0 +1,75 @@
+
+import sounddevice as sd
+import numpy as np
+import scipy.io.wavfile as wav
+import os
+import time
+from dotenv import load_dotenv
+from deepgram import DeepgramClient
+
+load_dotenv()
+
+def debug_audio():
+    print("📋 Listing Audio Devices:")
+    print(sd.query_devices())
+    
+    duration = 5
+    fs = 44100
+    
+    print(f"\n🎤 Recording for {duration} seconds... PLEASE SPEAK!")
+    recording = sd.rec(int(duration * fs), samplerate=fs, channels=1)
+    sd.wait()
+    print("✅ Recording finished.")
+    
+    # Calculate volume
+    rms = np.sqrt(np.mean(recording**2))
+    print(f"📊 Audio RMS (Volume): {rms}")
+    
+    if rms < 0.001:
+        print("⚠️  WARNING: Audio seems silent! Check your microphone input settings.")
+    else:
+        print("🔊 Audio detected.")
+        
+    filename = "debug_output.wav"
+    wav.write(filename, fs, recording)
+    print(f"💾 Saved to {filename}")
+    
+    # Try transcription
+    api_key = os.getenv("DEEPGRAM_API_KEY")
+    if not api_key:
+        print("❌ No Deepgram API Key found.")
+        return
+
+    try:
+        dg = DeepgramClient(api_key=api_key)
+        with open(filename, "rb") as audio:
+            buffer_data = audio.read()
+            
+        print("📝 Sending to Deepgram...")
+        options = {"model": "nova-2", "smart_format": True, "language": "en"}
+        
+        # Note: adjust this call based on what I saw in audio.py
+        response = dg.listen.v1.media.transcribe_file(
+            request=buffer_data, 
+            model="nova-2", 
+            smart_format=True, 
+            language="en"
+        )
+        # Verify response structure specific to the SDK version used in audio.py
+        # Actually audio.py used: client.listen.v1.media.transcribe_file(request=buffer_data, ...)
+        # Let's try to match audio.py exactly first
+        
+        print("\n--- Raw Response Summary ---")
+        print(response.to_json() if hasattr(response, 'to_json') else response)
+        
+        transcript = response.results.channels[0].alternatives[0].transcript
+        print(f"\n🗣️  Transcript: '{transcript}'")
+        
+    except Exception as e:
+        print(f"\n❌ Deepgram Error: {e}")
+        # specific fallback for different SDK versions if needed
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    debug_audio()

splitwise_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "splitwise-mcp"
+version = "0.1.0"
+description = "MCP server for Splitwise integration"
+authors = [
+    {name = "User", email = "user@example.com"},
+]
+dependencies = [
+    "mcp[cli]>=0.1.0",
+    "splitwise>=3.0.0",
+    "python-dotenv>=1.0.0",
+    "google-genai>=0.1.0",
+    "sounddevice>=0.4.6",
+    "numpy>=1.26.0",
+    "scipy>=1.11.0",
+    "colorama>=0.4.6",  # For pretty output
+    "deepgram-sdk>=3.0.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "streamlit>=1.30.0",
+]
+requires-python = ">=3.10"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.scripts]
+splitwise-mcp = "splitwise_mcp.server:main"

splitwise_mcp-0.1.0/run_agent.py

@@ -0,0 +1,94 @@
+import sys
+from splitwise_mcp.agent.audio import AudioTranscriber
+from splitwise_mcp.agent.client import SplitwiseAgent
+from colorama import Fore, Style
+import time
+import json
+
+def main():
+    print(f"{Fore.GREEN}🤖 Splitwise Voice Agent (with Confirmation){Style.RESET_ALL}")
+    print("Commands:")
+    print(" - 'v' or 'voice':  Record 10s of audio")
+    print(" - 't' or 'text':   Type text input")
+    print(" - 'q' or 'quit':   Exit")
+    
+    agent = SplitwiseAgent()
+    transcriber = AudioTranscriber()
+    
+    while True:
+        try:
+            choice = input(f"\n{Fore.BLUE}Enter command (voice/text/quit): {Style.RESET_ALL}").strip().lower()
+            
+            if choice in ['q', 'quit']:
+                print("Bye!")
+                break
+                
+            user_text = ""
+            
+            if choice in ['v', 'voice']:
+                try:
+                    audio_path = transcriber.record_audio(duration=10)
+                    user_text = transcriber.transcribe(audio_path)
+                    transcriber.cleanup(audio_path)
+                    print(f"🗣️  You said: {Style.BRIGHT}{user_text}{Style.RESET_ALL}")
+                except Exception as e:
+                    print(f"{Fore.RED}Audio Error: {e}{Style.RESET_ALL}")
+                    continue
+
+            elif choice in ['t', 'text']:
+                user_text = input("Enter request: ")
+
+            else:
+                continue
+                
+            if user_text:
+                # --- Interaction Loop for Confirmation ---
+                current_text = user_text
+                
+                while True:
+                    result = agent.process_input(current_text)
+                    
+                    if result["type"] == "text":
+                        print(f"\n{Fore.MAGENTA}🤖 Agent: {result['content']}{Style.RESET_ALL}")
+                        break # Done with this turn
+                        
+                    elif result["type"] == "confirmation_required":
+                        tool_name = result["tool_name"]
+                        args = result["tool_args"]
+                        
+                        print(f"\n{Fore.YELLOW}⚠️  Proposed Action:{Style.RESET_ALL}")
+                        print(f"   Function: {tool_name}")
+                        print(f"   Args: {json.dumps(args, indent=2)}")
+                        
+                        confirm = input(f"\n{Fore.WHITE}Proceed? (yes/edit/cancel): {Style.RESET_ALL}").lower().strip()
+                        
+                        if confirm in ['y', 'yes']:
+                            print("Executing...")
+                            final_resp = agent.execute_tool_and_reply(tool_name, args)
+                            print(f"\n{Fore.MAGENTA}🤖 Agent: {final_resp}{Style.RESET_ALL}")
+                            break # Request completed
+                            
+                        elif confirm in ['c', 'cancel', 'n', 'no']:
+                            print("❌ Cancelled action.")
+                            break # Break loop, go back to main menu
+                            
+                        else:
+                            # User wants to edit or provided feedback
+                            # e.g. "No, make it 15"
+                            feedback_text = confirm
+                            # If they just said "edit", ask for details
+                            if feedback_text == "edit":
+                                feedback_text = input("What corrections? (e.g. 'amount is 15'): ")
+                            
+                            print(f"🔄 Feedback: {feedback_text}")
+                            # We feed this back as 'current_text' to the agent loop
+                            current_text = feedback_text
+                            # Loop continues... agent.process_input(feedback_text) will be called next
+        
+        except KeyboardInterrupt:
+            break
+        except Exception as e:
+            print(f"{Fore.RED}Error: {e}{Style.RESET_ALL}")
+
+if __name__ == "__main__":
+    main()

splitwise_mcp-0.1.0/src/splitwise_mcp/agent/audio.py

@@ -0,0 +1,105 @@
+import sounddevice as sd
+import numpy as np
+import scipy.io.wavfile as wav
+import tempfile
+import os
+from deepgram import DeepgramClient
+
+class AudioTranscriber:
+    def __init__(self):
+        # Initialize Deepgram client
+        api_key = os.getenv("DEEPGRAM_API_KEY")
+        if not api_key:
+             raise ValueError("Missing DEEPGRAM_API_KEY in .env")
+        self.client = DeepgramClient(api_key=api_key)
+
+    def record_audio(self, duration=10, sample_rate=44100):
+        """
+        Record audio from the microphone for a fixed duration.
+        Returns the path to the temporary WAV file.
+        """
+        print(f"🎤 Recording for {duration} seconds... (Speak now!)")
+        
+        recording = sd.rec(int(duration * sample_rate), samplerate=sample_rate, channels=1)
+        sd.wait()  # Wait until recording is finished
+        
+        print("✅ Recording finished.")
+        
+        # Save to temp file
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as temp_audio:
+            wav.write(temp_audio.name, sample_rate, recording)
+            return temp_audio.name
+
+    def transcribe_bytes(self, buffer_data):
+        """
+        Transcribes audio bytes directly.
+        """
+        print("📝 Transcribing bytes with Deepgram...")
+        
+        # v5.x: Pass bytes as 'request' kwarg, and options as kwargs
+        response = self.client.listen.v1.media.transcribe_file(
+            request=buffer_data, 
+            model="nova-2", 
+            smart_format=True, 
+            language="en"
+        )
+        
+        transcript = response.results.channels[0].alternatives[0].transcript
+        return transcript
+
+    def generate_speech(self, text):
+        """
+        Generates speech from text using Deepgram Aura (TTS).
+        Returns raw audio bytes (mp3).
+        """
+        print(f"🗣️ Generating speech for: {text[:50]}...")
+        # Deepgram TTS (Aura)
+        SPEAK_OPTIONS = {"text": text}
+        # Model: aura-asteria-en (Female) or aura-orion-en (Male)
+        # Using Asteria for a friendly assistant voice
+        options = {
+            "model": "aura-asteria-en",
+            "encoding": "mp3",
+        }
+        
+        # Save to a temporary file is standard, but keeping in memory is better for Streamlit
+        # Deepgram SDK .save method saves to file. 
+        # We can use .stream? Or just save to temp and read back.
+        
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as temp_tts:
+             filename = temp_tts.name
+        
+        # self.client.speak.v("1").save... failed (attribute error).
+        # We found self.client.speak.v1.audio.generate exists.
+        
+        response = self.client.speak.v1.audio.generate(SPEAK_OPTIONS, options)
+        
+        # Check if response handles saving (SDK wrapper) or if we need to write bytes
+        if hasattr(response, "save"):
+            response.save(filename)
+        elif hasattr(response, "content"):
+            with open(filename, "wb") as f:
+                f.write(response.content)
+        else:
+            # Assume it is bytes directly
+            with open(filename, "wb") as f:
+                f.write(response)
+        
+        with open(filename, "rb") as f:
+            audio_bytes = f.read()
+            
+        os.remove(filename) # Clean up
+        return audio_bytes
+
+    def transcribe(self, audio_path):
+        """
+        Transcribes the audio file using Deepgram.
+        """
+        print("📝 Transcribing with Deepgram...")
+        with open(audio_path, "rb") as audio:
+             buffer_data = audio.read()
+        return self.transcribe_bytes(buffer_data)
+
+    def cleanup(self, audio_path):
+        if os.path.exists(audio_path):
+            os.remove(audio_path)