# Troubleshooting Guide
## Common Issues and Solutions
### 1. "spawn node ENOENT" Error
This error occurs when Claude Desktop can't find the `node` command because GUI applications don't inherit the same PATH as your terminal.
**Solutions:**
- Use the wrapper script (recommended): `/path/to/run-server.sh`
- Use absolute path to node: Find with `which node` and use full path
- Install node in system location: `/usr/local/bin/node`
### 2. "TypeError: file argument must be of type string" Error
This error typically occurs when there's an issue with the command path or arguments in the Claude Desktop configuration.
**Solutions:**
- Ensure you're using the absolute path to the built file
- Make sure the built file exists and is executable
- Try different configuration approaches
### 2. Claude Desktop Integration Issues
**Step 1: Verify Server Works Locally**
```bash
# Test the server locally first
export TYPEFULLY_API_KEY="your_key_here"
npm run test
```
**Step 2: Try Different Claude Desktop Configurations**
**Option A: Using Built File (Most Reliable)**
```json
{
"mcpServers": {
"typefully": {
"command": "node",
"args": ["/full/absolute/path/to/your/project/dist/index.js"],
"env": {
"TYPEFULLY_API_KEY": "your_api_key_here"
}
}
}
}
```
**Option B: Using NPX (After Publishing)**
```json
{
"mcpServers": {
"typefully": {
"command": "npx",
"args": ["typefully-mcp-server"],
"env": {
"TYPEFULLY_API_KEY": "your_api_key_here"
}
}
}
}
```
**Option C: Using Global Installation**
```bash
npm install -g .
```
```json
{
"mcpServers": {
"typefully": {
"command": "typefully-mcp-server",
"env": {
"TYPEFULLY_API_KEY": "your_api_key_here"
}
}
}
}
```
### 3. API Key Issues
**Symptoms:**
- 401/403 errors
- "API key not set" messages
**Solutions:**
- Get your API key from Typefully Settings > Integrations
- Ensure the key is properly set in the environment variable
- Check that the key doesn't have extra whitespace or quotes
### 4. Build Issues
**Symptoms:**
- TypeScript compilation errors
- Missing files
**Solutions:**
```bash
# Clean build
rm -rf dist/
npm run build
# Check built files exist
ls -la dist/
# Make executable
chmod +x dist/index.js
```
### 5. Testing Steps
1. **Test TypeScript Compilation**
```bash
npm run build
```
2. **Test Server Startup**
```bash
export TYPEFULLY_API_KEY="test"
node dist/index.js
# Should start without errors (Ctrl+C to stop)
```
3. **Test MCP Protocol**
```bash
npm run test:quick
```
4. **Test with Real API**
```bash
export TYPEFULLY_API_KEY="your_real_key"
npm run test
```
### 6. Debug Claude Desktop
1. **Check Claude Desktop Logs**
- Look for error messages in Claude Desktop console
- Check system logs for process startup issues
2. **Verify Configuration File**
- Ensure JSON is valid (no trailing commas, proper quotes)
- Use absolute paths, not relative ones
- Double-check environment variable names
3. **Test Configuration**
```bash
# Test the exact command Claude Desktop would run
TYPEFULLY_API_KEY="your_key" node /full/path/to/dist/index.js
```
### 7. Getting Help
If issues persist:
1. Check the GitHub issues: https://github.com/yourusername/typefully-mcp-server/issues
2. Provide error messages, configuration, and system details
3. Include output from `npm run test:quick`
