MCP version

.cursor/rules/clean-unused-imports.mdc

@@ -0,0 +1,58 @@
+---
+description: Clean up unused imports - remove all unused import statements
+alwaysApply: true
+---
+
+# Clean Unused Imports
+
+All unused import statements must be removed to keep code clean and maintainable.
+
+## Rules
+
+- **Remove unused imports**: Delete any import statements that are not used in the file
+- **Check before committing**: Ensure no unused imports remain in the codebase
+- **Use tools**: Consider using tools like `ruff check --select F401` or `autoflake` to detect unused imports
+
+## Examples
+
+```python
+# ❌ BAD - unused imports
+import os
+import sys
+import json  # Not used anywhere
+from pathlib import Path
+from typing import List, Dict, Optional  # Optional is not used
+
+def my_function():
+    path = Path("/tmp")
+    return path
+
+# ✅ GOOD - only import what's used
+from pathlib import Path
+
+def my_function():
+    path = Path("/tmp")
+    return path
+```
+
+## Detection
+
+Common signs of unused imports:
+- Imported module/function never referenced in the code
+- IDE warnings about unused imports
+- Linter errors (e.g., `F401` in ruff)
+
+## Tools
+
+You can use these tools to detect unused imports:
+
+```bash
+# Using ruff
+ruff check --select F401 .
+
+# Using autoflake
+autoflake --remove-all-unused-imports --in-place *.py
+
+# Using pylint
+pylint --disable=all --enable=unused-import file.py
+```

.cursor/rules/code-organization.mdc

@@ -0,0 +1,168 @@
+---
+description: Code organization standards - imports and constants placement
+alwaysApply: true
+---
+
+# Code Organization Standards
+
+## Import Statements
+
+All import statements must be at the top of the file, before any other code.
+
+```python
+# ✅ GOOD
+import os
+import sys
+from pathlib import Path
+from typing import List, Dict
+
+# Code starts here
+def my_function():
+    pass
+```
+
+```python
+# ❌ BAD
+def my_function():
+    import os  # Import inside function
+    pass
+```
+
+## Hard-coded Parameters
+
+### File-level Constants
+
+All hard-coded parameters and magic numbers should be defined as constants at the top of the file, after imports but before any function definitions.
+
+```python
+# ✅ GOOD
+import os
+from pathlib import Path
+
+# Constants at top of file
+DEFAULT_PORT = 8000
+MAX_RETRIES = 3
+TIMEOUT_SECONDS = 30
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "app.json"
+
+def start_server(port=DEFAULT_PORT):
+    pass
+```
+
+```python
+# ❌ BAD
+import os
+
+def start_server():
+    port = 8000  # Hard-coded in function
+    timeout = 30  # Hard-coded in function
+    pass
+```
+
+### Project-level Constants
+
+For constants that are shared across multiple files or represent project-wide configuration, create a dedicated `constants.py` file (or similar) in the project root or appropriate module.
+
+```python
+# ✅ GOOD - fastskills/constants.py
+"""Project-wide constants."""
+
+# Server configuration
+DEFAULT_MCP_PORT = 8000
+DEFAULT_TOP_K = 5
+MAX_TOOL_RESULTS = 100
+
+# File paths
+SKILLS_DIRECTORY = "~/.claude/skills"
+CONFIG_FILE = "~/.fastskills/config.json"
+
+# Code sandbox
+DEFAULT_ALLOWED_MODULES = ["pandas", "openpyxl", "pathlib"]
+```
+
+```python
+# ✅ GOOD - Using constants from constants file
+from fastskills.constants import DEFAULT_MCP_PORT, DEFAULT_TOP_K
+
+def start_server():
+    return start_mcp_server(port=DEFAULT_MCP_PORT)
+```
+
+```python
+# ❌ BAD - Hard-coding project-level values in multiple files
+# file1.py
+PORT = 8000
+
+# file2.py  
+PORT = 8000  # Duplicate definition
+```
+
+## Order of File Contents
+
+1. **Imports** (standard library, third-party, local)
+2. **Constants** (file-level constants)
+3. **Type definitions** (if any)
+4. **Function/class definitions**
+
+```python
+# ✅ GOOD - Correct order
+# 1. Imports
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from fastskills.constants import DEFAULT_PORT
+
+# 2. Constants
+MAX_CONNECTIONS = 10
+RETRY_DELAY = 1.0
+
+# 3. Code
+def connect():
+    pass
+```
+
+## Examples
+
+### Example 1: File with local constants
+
+```python
+"""Example module with proper organization."""
+
+# Imports
+import os
+from pathlib import Path
+from typing import List
+
+# Constants
+DEFAULT_TIMEOUT = 30
+MAX_ITEMS = 100
+LOG_DIR = Path("/var/log/app")
+
+# Functions
+def process_items(items: List[str]) -> None:
+    pass
+```
+
+### Example 2: Using project constants
+
+```python
+"""Example using project-level constants."""
+
+# Imports
+from fastskills.constants import (
+    DEFAULT_MCP_PORT,
+    DEFAULT_TOP_K,
+    SKILLS_DIRECTORY,
+)
+
+# File-level constants (if any)
+LOCAL_CACHE_SIZE = 1000
+
+# Functions
+def initialize():
+    port = DEFAULT_MCP_PORT
+    skills_path = SKILLS_DIRECTORY
+    pass
+```

.cursor/rules/no-try-import.mdc

@@ -0,0 +1,97 @@
+---
+description: Do not wrap imports in try-except - let import errors fail loudly
+alwaysApply: true
+---
+
+# No Try-Except for Imports
+
+Import statements should not be wrapped in try-except blocks. If an import fails, it should raise an error immediately rather than being silently caught.
+
+## Rules
+
+- **No try-except around imports**: Import statements must be at the top level, not inside try-except blocks
+- **Fail fast**: If a required dependency is missing, the error should be raised immediately
+- **Optional imports**: If a module is truly optional, use conditional imports at module level with clear error messages, not try-except
+
+## Examples
+
+```python
+# ❌ BAD - Hiding import errors
+try:
+    from langchain_core.tools import tool
+except ImportError:
+    tool = None  # Silently fails, hides the problem
+
+def my_function():
+    if tool is None:
+        # Error only appears when function is called
+        raise ImportError("langchain_core is required")
+    return tool(...)
+
+# ✅ GOOD - Let import errors fail immediately
+from langchain_core.tools import tool
+
+def my_function():
+    return tool(...)
+```
+
+```python
+# ❌ BAD - Catching import errors
+try:
+    import pandas as pd
+except ImportError:
+    pd = None  # Hides missing dependency
+
+# ✅ GOOD - Import at top, fail if missing
+import pandas as pd
+```
+
+## Optional Dependencies
+
+If a dependency is truly optional (e.g., for optional features), document it clearly and let the import fail:
+
+```python
+# ✅ GOOD - Optional dependency with clear documentation
+# Note: langchain_core is optional, only needed for create_sandbox_tool
+# Install with: pip install langchain-core
+from langchain_core.tools import tool as langchain_tool
+
+def create_tool():
+    """Create tool. Requires langchain-core to be installed."""
+    return langchain_tool(...)
+```
+
+Or use a clear check at module level:
+
+```python
+# ✅ ACCEPTABLE - Only if truly optional with clear error
+try:
+    from optional_module import feature
+except ImportError:
+    feature = None
+    # Document why it's optional
+    # This should be rare and well-documented
+
+def use_feature():
+    if feature is None:
+        raise ImportError(
+            "optional_module is required for this feature. "
+            "Install with: pip install optional-module"
+        )
+    return feature()
+```
+
+## Rationale
+
+- **Fail fast**: Import errors should be caught at import time, not at runtime
+- **Clear errors**: Users should know immediately if dependencies are missing
+- **No silent failures**: Hiding import errors makes debugging harder
+- **Dependency clarity**: Missing dependencies should be obvious, not hidden
+
+## Exception
+
+The only acceptable exception is when:
+1. The dependency is truly optional (not required for core functionality)
+2. The try-except is at module level (not inside functions)
+3. There is clear documentation explaining why it's optional
+4. A clear error message is provided when the optional feature is used

.cursor/rules/readme-maintenance.mdc

@@ -0,0 +1,26 @@
+---
+description: Only maintain one README file, don't add extra READMEs unless requested
+alwaysApply: true
+---
+
+# README Maintenance
+
+Only maintain a single README file in the project root (`README.md`).
+
+## Rules
+
+- **Do not create additional README files** in subdirectories or other locations
+- **Do not create** `README.md` files in new directories or modules
+- **Only update** the existing root `README.md` when documentation is needed
+- **Exception**: Only create additional README files if the user explicitly requests it
+
+## Examples
+
+```markdown
+❌ BAD: Creating README.md in src/components/
+❌ BAD: Creating README.md in docs/
+❌ BAD: Creating multiple README files for different modules
+
+✅ GOOD: Updating the root README.md with new information
+✅ GOOD: Creating additional README only when user explicitly asks
+```

.gitattributes

@@ -0,0 +1,6 @@
+# Git LFS file tracking
+*.mov filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.avi filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text
+*.mkv filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1 +1,24 @@
+.claude/
 .cursor/rules/
+.venv/
+.vscode/
+*.pyc
+*.egg-info/
+__pycache__/
+.DS_Store
+*.swp
+*.swo
+*~
+uv.lock
+
+# Video files (should be hosted externally)
+# But allow videos in examples/ directory for demos (tracked via Git LFS)
+*.mp4
+*.mov
+*.avi
+*.webm
+*.mkv
+*.gif
+!examples/*.mov
+!examples/*.mp4
+!examples/*.gif