From a906d902c1f83511681d2312e8925998123aea33 Mon Sep 17 00:00:00 2001 From: NehharShah Date: Tue, 16 Dec 2025 08:33:06 -0500 Subject: [PATCH] update on docs --- CONTRIBUTING.md | 261 ++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 22 ++++ README.md | 232 +++++++++++++++++++++++++++++++++++------- 3 files changed, 478 insertions(+), 37 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..99417fe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,261 @@ +# Contributing to Subconscious AI MCP Server + +Thank you for your interest in contributing to the Subconscious AI MCP Server! This document provides guidelines and instructions for contributing. + +## ๐Ÿš€ Getting Started + +### Prerequisites + +- Python 3.11 or higher +- Git +- A Subconscious AI account (for testing) + +### Development Setup + +1. **Fork and clone the repository** + ```bash + git clone https://github.com/YOUR_USERNAME/subconscious-ai-mcp.git + cd subconscious-ai-mcp + ``` + +2. **Create a virtual environment** + ```bash + python3 -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` + +3. **Install dependencies** + ```bash + pip install -r requirements.txt + ``` + +4. **Set up environment variables** + ```bash + export AUTH0_JWT_TOKEN="your_test_token" + export API_BASE_URL="https://api.subconscious.ai" + ``` + +## ๐Ÿ“‹ Development Workflow + +### Running Tests + +```bash +# Run all tests +pytest tests/ -v + +# Run specific test file +pytest tests/test_handlers.py -v + +# Run with coverage +pytest tests/ -v --cov=server --cov-report=html +``` + +### Code Quality + +We use `ruff` for linting and `mypy` for type checking: + +```bash +# Run linting +ruff check server/ api/ + +# Auto-fix linting issues +ruff check server/ api/ --fix + +# Run type checking +mypy server/ api/ +``` + +### Code Style + +- Follow PEP 8 guidelines +- Use type hints for all function signatures +- Write docstrings for public functions and classes +- Keep functions focused and single-purpose + +## ๐Ÿ”ง Making Changes + +### Branch Naming + +Use descriptive branch names: +- `feature/add-new-tool` - New features +- `fix/handle-timeout-error` - Bug fixes +- `docs/update-readme` - Documentation changes +- `refactor/simplify-handlers` - Code refactoring + +### Commit Messages + +Write clear, concise commit messages: + +``` +Add retry logic for transient API errors + +- Implement exponential backoff with jitter +- Add configurable max retries +- Handle network timeouts gracefully +``` + +### Pull Request Process + +1. **Create a feature branch** from `main` +2. **Make your changes** with tests +3. **Ensure all tests pass** (`pytest tests/ -v`) +4. **Ensure code quality** (`ruff check server/ api/`) +5. **Update documentation** if needed +6. **Submit a pull request** with a clear description + +## ๐Ÿ—๏ธ Project Architecture + +### Directory Structure + +``` +server/ +โ”œโ”€โ”€ main.py # Entry point for stdio transport +โ”œโ”€โ”€ config.py # Configuration management +โ”œโ”€โ”€ utils/ +โ”‚ โ””โ”€โ”€ api_client.py # HTTP client wrapper +โ””โ”€โ”€ tools/ + โ”œโ”€โ”€ __init__.py # Tool exports + โ”œโ”€โ”€ ideation.py # Causality & attribute tools + โ”œโ”€โ”€ experiments.py # Experiment tools + โ”œโ”€โ”€ runs.py # Run management tools + โ”œโ”€โ”€ analytics.py # Analytics tools + โ””โ”€โ”€ _core/ + โ”œโ”€โ”€ base.py # Base types + โ”œโ”€โ”€ exceptions.py # Exception hierarchy + โ”œโ”€โ”€ handlers.py # Tool handlers + โ””โ”€โ”€ retry.py # Retry logic +``` + +### Adding a New Tool + +1. **Define the tool schema** in the appropriate file (`ideation.py`, `experiments.py`, etc.): + + ```python + MY_NEW_TOOL = Tool( + name="my_new_tool", + description="Description of what the tool does", + inputSchema={ + "type": "object", + "properties": { + "param1": { + "type": "string", + "description": "Description of param1", + }, + }, + "required": ["param1"], + }, + ) + ``` + +2. **Implement the handler** in `_core/handlers.py`: + + ```python + async def my_new_tool( + args: Dict[str, Any], token_provider: TokenProvider + ) -> ToolResult: + """Handle my_new_tool requests.""" + try: + response = await _api_request( + "POST", + "/api/v1/endpoint", + token_provider, + {"param1": args["param1"]}, + ) + return ToolResult( + success=True, + data=response, + message="Success message", + ) + except AuthenticationError: + return ToolResult(success=False, error="Authentication failed") + except Exception as e: + return ToolResult(success=False, error=str(e)) + ``` + +3. **Export the tool** in `tools/__init__.py` + +4. **Register in main.py** and **api/index.py** + +5. **Add tests** in `tests/test_handlers.py` + +### Error Handling + +Use the custom exception hierarchy: + +```python +from server.tools._core.exceptions import ( + AuthenticationError, # 401 errors + ValidationError, # 400/422 errors + NotFoundError, # 404 errors + RateLimitError, # 429 errors + ServerError, # 500+ errors + NetworkError, # Connection/timeout errors +) +``` + +## ๐Ÿงช Testing Guidelines + +### Test Structure + +```python +class TestMyNewTool: + """Tests for my_new_tool handler.""" + + @pytest.mark.asyncio + async def test_successful_call(self, mock_httpx): + """Test successful tool execution.""" + mock_httpx.post.return_value = MockResponse(200, {"result": "success"}) + + result = await my_new_tool( + {"param1": "value"}, + lambda: "test_token" + ) + + assert result.success is True + assert result.data["result"] == "success" + + @pytest.mark.asyncio + async def test_handles_auth_error(self, mock_httpx): + """Test authentication error handling.""" + mock_httpx.post.return_value = MockResponse(401, {"error": "Unauthorized"}) + + result = await my_new_tool( + {"param1": "value"}, + lambda: "invalid_token" + ) + + assert result.success is False + assert "Authentication" in result.error +``` + +### Test Coverage + +Aim for high test coverage on: +- Happy path scenarios +- Error handling (auth, validation, network) +- Edge cases (empty inputs, missing fields) + +## ๐Ÿ“š Documentation + +When adding new features: +- Update the README.md with new tools or endpoints +- Add inline documentation (docstrings) +- Update examples if applicable + +## ๐Ÿค Code of Conduct + +- Be respectful and inclusive +- Provide constructive feedback +- Focus on the code, not the person +- Help others learn and grow + +## โ“ Questions? + +- Open an issue for bugs or feature requests +- Join our [Discord](https://discord.gg/3bgj4ZhABz) for discussions +- Email: nihar@subconscious.ai + +--- + +Thank you for contributing! ๐ŸŽ‰ + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e525329 --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2025 Subconscious AI, Inc. + +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. + diff --git a/README.md b/README.md index 0a12300..b81e081 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,25 @@ # Subconscious AI MCP Server -Run AI-powered conjoint experiments from Claude, Cursor, or any MCP-compatible client. +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) +[![MCP Protocol](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/) + +Run AI-powered conjoint experiments from Claude, Cursor, or any MCP-compatible client. Understand **why** people make decisions using causal inference and synthetic populations. + +## โœจ Features + +- **๐Ÿง  Causal Research** - Validate research questions and generate statistically valid experiments +- **๐Ÿ‘ฅ Synthetic Populations** - AI personas based on US Census microdata (IPUMS) for representative sampling +- **๐Ÿ“Š Conjoint Analysis** - AMCE (Average Marginal Component Effects) for measuring attribute importance +- **๐Ÿค– MCP Protocol** - Works with Claude Desktop, Cursor, and any MCP-compatible AI assistant +- **๐ŸŒ REST API** - Direct HTTP access for integrations (n8n, Zapier, custom apps) +- **โšก Real-time Updates** - Server-Sent Events (SSE) for live experiment progress ## ๐Ÿš€ Quick Start ### Option 1: Use Hosted Server (Recommended) -Add to your MCP client configuration: +No setup required! Add to your MCP client configuration: **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json @@ -30,15 +43,29 @@ Add to your MCP client configuration: } ``` -Get your token at [app.subconscious.ai](https://app.subconscious.ai) โ†’ Settings โ†’ Access Token +> ๐Ÿ”‘ Get your token at [app.subconscious.ai](https://app.subconscious.ai) โ†’ Settings โ†’ Access Token ### Option 2: Run Locally +**Prerequisites:** +- Python 3.11+ +- A Subconscious AI account and Access token + ```bash +# Clone the repository git clone https://github.com/Subconscious-ai/subconscious-ai-mcp.git cd subconscious-ai-mcp -python3 -m venv venv && source venv/bin/activate + +# Create virtual environment +python3 -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate + +# Install dependencies pip install -r requirements.txt + +# Set environment variables +export AUTH0_JWT_TOKEN="your_token_here" +export API_BASE_URL="https://api.subconscious.ai" ``` Add to your MCP config: @@ -46,8 +73,8 @@ Add to your MCP config: { "mcpServers": { "subconscious-ai": { - "command": "/path/to/venv/bin/python3", - "args": ["/path/to/server/main.py"], + "command": "/absolute/path/to/venv/bin/python3", + "args": ["/absolute/path/to/server/main.py"], "env": { "AUTH0_JWT_TOKEN": "your_token", "API_BASE_URL": "https://api.subconscious.ai" @@ -61,28 +88,58 @@ Add to your MCP config: | Tool | Description | |------|-------------| -| `check_causality` | Validate research question is causal | -| `generate_attributes_levels` | Generate experiment attributes/levels | +| `check_causality` | Validate that a research question is causal | +| `generate_attributes_levels` | Generate experiment attributes and levels using AI | +| `validate_population` | Validate target population demographics | +| `get_population_stats` | Get population statistics for a country | | `create_experiment` | Create and run a conjoint experiment | | `get_experiment_status` | Check experiment progress | | `list_experiments` | List all your experiments | -| `get_experiment_results` | Get detailed results | +| `get_experiment_results` | Get detailed experiment results | +| `get_run_details` | Get detailed run information | +| `get_run_artifacts` | Get run artifacts and files | +| `update_run_config` | Update run configuration | +| `generate_personas` | Generate AI personas for an experiment | +| `get_experiment_personas` | Get personas for an experiment | | `get_amce_data` | Get AMCE analytics data | -| `get_causal_insights` | Get AI-generated insights | +| `get_causal_insights` | Get AI-generated causal insights | -## ๐Ÿ”ฌ Experiment Workflow +## ๐Ÿ”ฌ Example Workflow ``` -1. "Check if this is causal: What factors influence EV purchases?" -2. "Generate attributes for an EV preference study" -3. "Create an experiment about EV purchasing decisions" -4. "Check the status of experiment " -5. "Get causal insights from experiment " +You: "Check if this is a causal question: What factors influence people's decision to buy electric vehicles?" + +AI: โœ… This is a causal question. Let me generate attributes for this study. + +You: "Generate attributes for an EV preference study" + +AI: Generated 5 attributes with 4 levels each: + - Price: $25,000 / $35,000 / $45,000 / $55,000 + - Range: 200 miles / 300 miles / 400 miles / 500 miles + ... + +You: "Create an experiment about EV purchasing decisions" + +AI: ๐Ÿš€ Experiment created! Run ID: abc-123-xyz + Status: Processing (surveying 500 synthetic respondents) + +You: "Check the status of experiment abc-123-xyz" + +AI: โœ… Experiment completed! + - 500 respondents surveyed + - Ready for analysis + +You: "Get causal insights from this experiment" + +AI: ๐Ÿ“Š Key Findings: + - Price has the strongest effect (-0.32 AMCE) + - 400+ mile range increases preference by 28% + - Brand reputation matters more than charging speed ``` ## ๐ŸŒ REST API -You can also call tools directly via HTTP: +Call tools directly via HTTP for integrations: ```bash # List experiments @@ -101,45 +158,146 @@ curl -X POST https://ghostshell-runi.vercel.app/api/call/check_causality \ curl -X POST https://ghostshell-runi.vercel.app/api/call/create_experiment \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ - -d '{"why_prompt": "What factors influence EV purchases?"}' + -d '{"why_prompt": "What factors influence EV purchases?", "confidence_level": "Reasonable"}' + +# Get experiment results +curl -X POST https://ghostshell-runi.vercel.app/api/call/get_experiment_results \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"run_id": "your-run-id"}' ``` ## ๐Ÿ“ก API Endpoints -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/` | GET | Server info | -| `/api/health` | GET | Health check | -| `/api/tools` | GET | List all tools | -| `/api/sse` | GET | MCP SSE connection | -| `/api/call/{tool}` | POST | Call a tool (REST) | +| Endpoint | Method | Auth | Description | +|----------|--------|------|-------------| +| `/` | GET | No | Server info and available tools | +| `/api/health` | GET | No | Health check | +| `/api/tools` | GET | No | List all tools with schemas | +| `/api/sse` | GET | Yes | MCP SSE connection (token in query param) | +| `/api/call/{tool}` | POST | Yes | Call a tool directly | -## ๐Ÿ—๏ธ Self-Hosting +## ๐Ÿ—๏ธ Self-Hosting on Vercel -Deploy your own instance: +Deploy your own instance for your organization: ```bash +# Install Vercel CLI npm i -g vercel -cd subconscious-ai-mcp-toolkit + +# Clone and deploy +git clone https://github.com/Subconscious-ai/subconscious-ai-mcp.git +cd subconscious-ai-mcp vercel --prod ``` +Configure environment variables in Vercel dashboard: +- `API_BASE_URL`: `https://api.subconscious.ai` (or your backend URL) + +> โš ๏ธ Users must provide their own tokens - the server proxies requests to the Subconscious AI backend. + +## ๐Ÿงช Development + +```bash +# Install dev dependencies +pip install -r requirements-dev.txt + +# Run linting +ruff check server/ api/ + +# Run type checking +mypy server/ api/ + +# Run tests +pytest tests/ -v + +# Run local server (stdio mode) +python server/main.py + +# Run local HTTP server (for testing) +uvicorn api.index:app --host 0.0.0.0 --port 8001 --reload +``` + ## ๐Ÿ“ Project Structure ``` -subconscious-ai-mcp-toolkit/ +subconscious-ai-mcp/ โ”œโ”€โ”€ api/ -โ”‚ โ””โ”€โ”€ index.py # Vercel serverless (SSE + REST) +โ”‚ โ””โ”€โ”€ index.py # Vercel serverless function (SSE + REST) โ”œโ”€โ”€ server/ -โ”‚ โ”œโ”€โ”€ main.py # Local MCP server (stdio) -โ”‚ โ”œโ”€โ”€ config.py # Configuration -โ”‚ โ””โ”€โ”€ tools/ # Tool implementations +โ”‚ โ”œโ”€โ”€ main.py # Local MCP server (stdio transport) +โ”‚ โ”œโ”€โ”€ config.py # Configuration management +โ”‚ โ”œโ”€โ”€ utils/ +โ”‚ โ”‚ โ””โ”€โ”€ api_client.py # HTTP client for Subconscious AI API +โ”‚ โ””โ”€โ”€ tools/ +โ”‚ โ”œโ”€โ”€ __init__.py # Tool exports +โ”‚ โ”œโ”€โ”€ ideation.py # Causality & attribute generation tools +โ”‚ โ”œโ”€โ”€ experiments.py # Experiment creation tools +โ”‚ โ”œโ”€โ”€ runs.py # Run management tools +โ”‚ โ”œโ”€โ”€ analytics.py # Analytics & insights tools +โ”‚ โ””โ”€โ”€ _core/ +โ”‚ โ”œโ”€โ”€ base.py # Base types (ToolResult, TokenProvider) +โ”‚ โ”œโ”€โ”€ exceptions.py # Custom exception hierarchy +โ”‚ โ”œโ”€โ”€ handlers.py # Unified tool handlers +โ”‚ โ””โ”€โ”€ retry.py # Retry decorator with exponential backoff +โ”œโ”€โ”€ tests/ +โ”‚ โ”œโ”€โ”€ test_tools.py # Tool definition tests +โ”‚ โ”œโ”€โ”€ test_handlers.py # Handler unit tests +โ”‚ โ”œโ”€โ”€ test_integration.py # API integration tests +โ”‚ โ”œโ”€โ”€ test_retry.py # Retry logic tests +โ”‚ โ””โ”€โ”€ test_exceptions.py # Exception tests โ”œโ”€โ”€ examples/ -โ”‚ โ””โ”€โ”€ claude/config.json -โ”œโ”€โ”€ vercel.json -โ””โ”€โ”€ requirements.txt +โ”‚ โ”œโ”€โ”€ claude/config.json # Claude Desktop config example +โ”‚ โ”œโ”€โ”€ cursor/mcp.json # Cursor config example +โ”‚ โ””โ”€โ”€ local/config.json # Local testing config +โ”œโ”€โ”€ vercel.json # Vercel deployment config +โ”œโ”€โ”€ requirements.txt # Production dependencies +โ”œโ”€โ”€ requirements-dev.txt # Development dependencies +โ””โ”€โ”€ pyproject.toml # Project metadata and tool configs ``` +## ๐Ÿ”ง Configuration + +| Environment Variable | Default | Description | +|---------------------|---------|-------------| +| `AUTH0_JWT_TOKEN` | (required) | Your Subconscious AI access token | +| `API_BASE_URL` | `https://api.subconscious.ai` | Backend API URL | +| `LOG_LEVEL` | `INFO` | Logging level | +| `CORS_ALLOWED_ORIGINS` | (see config) | Comma-separated allowed origins | +| `CORS_ALLOW_ALL` | `false` | Allow all origins (dev only) | + +## ๐Ÿค Contributing + +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Make your changes +4. Run tests (`pytest tests/ -v`) +5. Run linting (`ruff check server/ api/`) +6. Commit your changes (`git commit -m 'Add amazing feature'`) +7. Push to the branch (`git push origin feature/amazing-feature`) +8. Open a Pull Request + +## ๐Ÿ“š Resources + +- [Subconscious AI Platform](https://app.subconscious.ai) - Create experiments via UI +- [API Documentation](https://docs.subconscious.ai) - Full API reference +- [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol specification +- [Conjoint Analysis](https://en.wikipedia.org/wiki/Conjoint_analysis) - Learn about the methodology + ## ๐Ÿ“„ License -MIT License +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## ๐Ÿ™ Acknowledgments + +- Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic +- Population data from [IPUMS USA](https://usa.ipums.org) (US Census microdata) +- Conjoint analysis methodology based on established survey research practices + +--- + +

+ Made with โค๏ธ by Subconscious AI +