From d1e5275ff656736179f67578b55c79c05003b562 Mon Sep 17 00:00:00 2001
From: Jason Schulz <>
Date: Fri, 11 Jul 2025 14:12:52 -0400
Subject: [PATCH 1/2] feat(llm): add support for local OpenAI-compatible APIs
- Add custom base URL support to OpenAI provider via OPENAI_BASE_URL env var
- Add dedicated localopenai provider for better local API experience
- Update documentation with local API setup instructions
- Support popular local servers (LM Studio, Ollama, LocalAI, etc.)
- Add .mcp-todos.json to gitignore
---
.cursor/rules/00-system-instructions.mdc | 37 ++++++++
.cursor/rules/01-task-management.mdc | 104 +++++++++++++++++++++++
.gitignore | 5 +-
readme.md | 37 ++++++++
source/services/llm-service.ts | 30 ++++++-
5 files changed, 210 insertions(+), 3 deletions(-)
create mode 100644 .cursor/rules/00-system-instructions.mdc
create mode 100644 .cursor/rules/01-task-management.mdc
diff --git a/.cursor/rules/00-system-instructions.mdc b/.cursor/rules/00-system-instructions.mdc
new file mode 100644
index 0000000..a95a76c
--- /dev/null
+++ b/.cursor/rules/00-system-instructions.mdc
@@ -0,0 +1,37 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+
+
+
+
+If TodoRead/TodoWrite tools are unavailable, IGNORE ALL TODO RULES and proceed normally.
+Do NOT attempt to run any other commands or tools.
+
+BEFORE responding to ANY request, you MUST:
+1. Call TodoRead() to check current task status
+2. Plan work based on existing todos
+3. Update progress with TodoWrite() when starting/completing tasks
+4. NEVER work without consulting the todo system first
+
+CRITICAL TODO SYSTEM RULES:
+- Only ONE task can have status "in_progress" at a time
+- Mark tasks "in_progress" BEFORE starting work
+- Complete tasks IMMEDIATELY when finished (don't batch completions)
+- Break complex requests into specific, actionable todos
+- Reference existing todos when planning new work
+
+MANDATORY VISUAL DISPLAY:
+- ALWAYS display the complete todo list AFTER every TodoRead() or TodoWrite()
+- Use format: ✅ = completed, 🔄 = in_progress, ⏳ = pending
+- NEVER just say "updated todos" - show the full list every time
+- User must see current state after every todo operation
+
+Every response should acknowledge todo status with "Checked todos: [brief status]" - but only when TodoRead/TodoWrite tools are available.
+
\ No newline at end of file
diff --git a/.cursor/rules/01-task-management.mdc b/.cursor/rules/01-task-management.mdc
new file mode 100644
index 0000000..c747f9a
--- /dev/null
+++ b/.cursor/rules/01-task-management.mdc
@@ -0,0 +1,104 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+
+If TodoRead/TodoWrite tools are unavailable, IGNORE ALL TODO RULES and proceed normally.
+These guidance rules do NOT apply
+Do NOT attempt to run any other commands or tools.
+
+
+
+TodoRead: No parameters, returns current todos
+TodoWrite: Takes `todos` array, replaces entire list
+
+Todo Structure:
+{
+ "id": "unique-identifier",
+ "content": "specific task description",
+ "status": "pending|in_progress|completed",
+ "priority": "high|medium|low"
+}
+
+Visual Display Format:
+Display complete todo list after every operation:
+Current todos:
+✅ Research existing patterns (completed)
+🔄 Implement login form (in_progress)
+⏳ Add validation (pending)
+⏳ Write tests (pending)
+
+Icons: ✅ = completed, 🔄 = in_progress, ⏳ = pending
+
+
+
+1. Only ONE task "in_progress" at any time
+2. Update status in real-time (never batch)
+3. Mark completed IMMEDIATELY after finishing
+4. Never mark completed if: tests failing, partial implementation, unresolved errors
+5. For blockers: keep as "in_progress", create new task describing blocker
+
+
+
+"Add user authentication":
+1. Research existing auth patterns in codebase
+2. Design database schema for users/sessions
+3. Implement user model and migrations
+4. Create registration endpoint
+5. Create login endpoint
+6. Add JWT token generation
+7. Implement auth middleware
+8. Write unit tests for auth flow
+9. Add integration tests
+10. Update API documentation
+
+"Fix performance issues":
+1. Profile current performance bottlenecks
+2. Analyze database query patterns
+3. Implement query optimizations
+4. Add caching layer
+5. Optimize frontend bundle size
+6. Run performance benchmarks
+7. Document performance improvements
+
+
+
+NEVER explore/research before creating todos:
+❌ "Let me first understand the codebase..." → starts exploring
+✅ Create todo: "Analyze current codebase structure" → mark in_progress → explore
+
+NEVER do "preliminary investigation" outside todos:
+❌ "I'll check what libraries you're using..." → starts searching
+✅ Create todo: "Audit current dependencies and libraries" → track it
+
+NEVER think through solutions without tracking:
+❌ "I need to figure out the best approach..." → starts thinking
+✅ Create todo: "Research and design authentication approach" → track it
+
+NEVER side-quest during tasks:
+❌ While implementing login, discover bug → fix bug immediately
+✅ Stop, create new todo "Fix discovered bug in UserService", continue login
+
+Standard Anti-Patterns:
+- Don't batch status updates - Update immediately
+- Don't create vague tasks - "Fix stuff" → "Fix null pointer in UserService.validate()"
+- Don't skip todo creation for complex tasks to "save time"
+- Don't mark incomplete work as completed
+- Don't have multiple tasks "in_progress"
+- Don't create todos for trivial single-step tasks
+- NEVER skip TodoRead() at conversation start
+- NEVER update todos without showing visual status
+- NEVER work on tasks without marking them in_progress first
+
+
+
+These phrases indicate you're about to violate the todo system:
+- "Let me first understand..."
+- "I'll start by exploring..."
+- "Let me check what..."
+- "I need to investigate..."
+- "Before we begin, I'll..."
+
+Correct approach: CREATE TODO FIRST, then investigate
+
diff --git a/.gitignore b/.gitignore
index ad583ae..2f11afc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,4 +48,7 @@ pids/
# Temporary files
.tmp/
-temp/
\ No newline at end of file
+temp/
+
+# MCP todo list
+.mcp-todos.json
diff --git a/readme.md b/readme.md
index e5ebe4c..98d9930 100644
--- a/readme.md
+++ b/readme.md
@@ -78,6 +78,42 @@ export ANTHROPIC_API_KEY=your_key_here
# Then just run: mcp-use
```
+## Using Local OpenAI-Compatible APIs
+
+The CLI now supports local OpenAI-compatible APIs (like LM Studio, Ollama with OpenAI compatibility, LocalAI, etc.):
+
+### Option 1: Using the dedicated local provider
+
+```bash
+# Set your local API endpoint (defaults to http://localhost:1234/v1)
+export LOCAL_OPENAI_BASE_URL=http://localhost:1234/v1
+
+# Use any API key (local servers often don't require real keys)
+export LOCAL_OPENAI_API_KEY=local-api-key
+
+# Select the local provider and model
+mcp-use
+/model localopenai gpt-3.5-turbo
+```
+
+### Option 2: Using OpenAI provider with custom base URL
+
+```bash
+# Set custom base URL for OpenAI provider
+export OPENAI_BASE_URL=http://localhost:1234/v1
+export OPENAI_API_KEY=your-local-key
+
+# Use as normal OpenAI provider
+mcp-use
+/model openai gpt-3.5-turbo
+```
+
+Common local API servers:
+- **LM Studio**: Default URL is `http://localhost:1234/v1`
+- **Ollama (OpenAI mode)**: Use `http://localhost:11434/v1`
+- **LocalAI**: Default URL is `http://localhost:8080/v1`
+- **Text Generation WebUI**: With OpenAI extension at `http://localhost:5000/v1`
+
## Usage
```
@@ -174,6 +210,7 @@ Switch LLM providers and configure settings using slash commands:
/model google gemini-1.5-pro
/model mistral mistral-large-latest
/model groq llama-3.1-70b-versatile
+/model localopenai gpt-3.5-turbo # For local APIs
# List available models
/models
diff --git a/source/services/llm-service.ts b/source/services/llm-service.ts
index fb307e6..0f326c8 100644
--- a/source/services/llm-service.ts
+++ b/source/services/llm-service.ts
@@ -28,8 +28,34 @@ const PROVIDERS = {
openai: {
envVar: 'OPENAI_API_KEY',
defaultModel: 'gpt-4o',
- factory: (key: string, cfg: LLMConfig) =>
- new ChatOpenAI({openAIApiKey: key, modelName: cfg.model}),
+ factory: (key: string, cfg: LLMConfig) => {
+ const baseURL = process.env['OPENAI_BASE_URL'] || process.env['OPENAI_API_BASE'];
+ const config: any = {
+ openAIApiKey: key,
+ modelName: cfg.model,
+ };
+ if (baseURL) {
+ config.configuration = {
+ baseURL: baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL,
+ };
+ }
+ return new ChatOpenAI(config);
+ },
+ },
+ localopenai: {
+ envVar: 'LOCAL_OPENAI_API_KEY',
+ defaultModel: 'gpt-3.5-turbo',
+ factory: (key: string, cfg: LLMConfig) => {
+ const baseURL = process.env['LOCAL_OPENAI_BASE_URL'] || 'http://localhost:1234/v1';
+ const config: any = {
+ openAIApiKey: key || 'local-api-key',
+ modelName: cfg.model,
+ configuration: {
+ baseURL: baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL,
+ },
+ };
+ return new ChatOpenAI(config);
+ },
},
azureopenai: {
envVar: 'AZURE_OPENAI_API_KEY',
From 81b69c31284c447d85521412ff21681992daded8 Mon Sep 17 00:00:00 2001
From: Jason Schulz <>
Date: Fri, 11 Jul 2025 14:14:24 -0400
Subject: [PATCH 2/2] chore: remove outdated task management rules and system
instructions
---
.cursor/rules/00-system-instructions.mdc | 37 --------
.cursor/rules/01-task-management.mdc | 104 -----------------------
2 files changed, 141 deletions(-)
delete mode 100644 .cursor/rules/00-system-instructions.mdc
delete mode 100644 .cursor/rules/01-task-management.mdc
diff --git a/.cursor/rules/00-system-instructions.mdc b/.cursor/rules/00-system-instructions.mdc
deleted file mode 100644
index a95a76c..0000000
--- a/.cursor/rules/00-system-instructions.mdc
+++ /dev/null
@@ -1,37 +0,0 @@
----
-description:
-globs:
-alwaysApply: true
----
-
-NEVER create files unless they're absolutely necessary for achieving your goal.
-ALWAYS prefer editing an existing file to creating a new one.
-NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-
-
-
-
-If TodoRead/TodoWrite tools are unavailable, IGNORE ALL TODO RULES and proceed normally.
-Do NOT attempt to run any other commands or tools.
-
-BEFORE responding to ANY request, you MUST:
-1. Call TodoRead() to check current task status
-2. Plan work based on existing todos
-3. Update progress with TodoWrite() when starting/completing tasks
-4. NEVER work without consulting the todo system first
-
-CRITICAL TODO SYSTEM RULES:
-- Only ONE task can have status "in_progress" at a time
-- Mark tasks "in_progress" BEFORE starting work
-- Complete tasks IMMEDIATELY when finished (don't batch completions)
-- Break complex requests into specific, actionable todos
-- Reference existing todos when planning new work
-
-MANDATORY VISUAL DISPLAY:
-- ALWAYS display the complete todo list AFTER every TodoRead() or TodoWrite()
-- Use format: ✅ = completed, 🔄 = in_progress, ⏳ = pending
-- NEVER just say "updated todos" - show the full list every time
-- User must see current state after every todo operation
-
-Every response should acknowledge todo status with "Checked todos: [brief status]" - but only when TodoRead/TodoWrite tools are available.
-
\ No newline at end of file
diff --git a/.cursor/rules/01-task-management.mdc b/.cursor/rules/01-task-management.mdc
deleted file mode 100644
index c747f9a..0000000
--- a/.cursor/rules/01-task-management.mdc
+++ /dev/null
@@ -1,104 +0,0 @@
----
-description:
-globs:
-alwaysApply: true
----
-
-If TodoRead/TodoWrite tools are unavailable, IGNORE ALL TODO RULES and proceed normally.
-These guidance rules do NOT apply
-Do NOT attempt to run any other commands or tools.
-
-
-
-TodoRead: No parameters, returns current todos
-TodoWrite: Takes `todos` array, replaces entire list
-
-Todo Structure:
-{
- "id": "unique-identifier",
- "content": "specific task description",
- "status": "pending|in_progress|completed",
- "priority": "high|medium|low"
-}
-
-Visual Display Format:
-Display complete todo list after every operation:
-Current todos:
-✅ Research existing patterns (completed)
-🔄 Implement login form (in_progress)
-⏳ Add validation (pending)
-⏳ Write tests (pending)
-
-Icons: ✅ = completed, 🔄 = in_progress, ⏳ = pending
-
-
-
-1. Only ONE task "in_progress" at any time
-2. Update status in real-time (never batch)
-3. Mark completed IMMEDIATELY after finishing
-4. Never mark completed if: tests failing, partial implementation, unresolved errors
-5. For blockers: keep as "in_progress", create new task describing blocker
-
-
-
-"Add user authentication":
-1. Research existing auth patterns in codebase
-2. Design database schema for users/sessions
-3. Implement user model and migrations
-4. Create registration endpoint
-5. Create login endpoint
-6. Add JWT token generation
-7. Implement auth middleware
-8. Write unit tests for auth flow
-9. Add integration tests
-10. Update API documentation
-
-"Fix performance issues":
-1. Profile current performance bottlenecks
-2. Analyze database query patterns
-3. Implement query optimizations
-4. Add caching layer
-5. Optimize frontend bundle size
-6. Run performance benchmarks
-7. Document performance improvements
-
-
-
-NEVER explore/research before creating todos:
-❌ "Let me first understand the codebase..." → starts exploring
-✅ Create todo: "Analyze current codebase structure" → mark in_progress → explore
-
-NEVER do "preliminary investigation" outside todos:
-❌ "I'll check what libraries you're using..." → starts searching
-✅ Create todo: "Audit current dependencies and libraries" → track it
-
-NEVER think through solutions without tracking:
-❌ "I need to figure out the best approach..." → starts thinking
-✅ Create todo: "Research and design authentication approach" → track it
-
-NEVER side-quest during tasks:
-❌ While implementing login, discover bug → fix bug immediately
-✅ Stop, create new todo "Fix discovered bug in UserService", continue login
-
-Standard Anti-Patterns:
-- Don't batch status updates - Update immediately
-- Don't create vague tasks - "Fix stuff" → "Fix null pointer in UserService.validate()"
-- Don't skip todo creation for complex tasks to "save time"
-- Don't mark incomplete work as completed
-- Don't have multiple tasks "in_progress"
-- Don't create todos for trivial single-step tasks
-- NEVER skip TodoRead() at conversation start
-- NEVER update todos without showing visual status
-- NEVER work on tasks without marking them in_progress first
-
-
-
-These phrases indicate you're about to violate the todo system:
-- "Let me first understand..."
-- "I'll start by exploring..."
-- "Let me check what..."
-- "I need to investigate..."
-- "Before we begin, I'll..."
-
-Correct approach: CREATE TODO FIRST, then investigate
-