IgnazioDS · IgnazioDS · May 28, 2026 · May 28, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -249,11 +249,12 @@ python3 -m pytest --cov=src --cov-report=term
 ## Project State Awareness
 
 Before starting ANY work:
-1. Check `docs/ROADMAP.md` for current priorities
+1. Check `docs/TODO.md` for current priorities and active tasks
 2. Check `docs/KNOWN_ISSUES.md` for existing problems
 3. Check `docs/COVERAGE_REPORT.md` for testing priorities
-4. Run `python3 -m pytest` to see current test status
-5. Use TodoRead to see any ongoing work
+4. Check `docs/VISION.md` for longer-term direction when planning larger work
+5. Run `python3 -m pytest` to see current test status
+6. Use TodoRead to see any ongoing work
 
 ## Starting a Work Session
 

diff --git a/AUDIT.md b/AUDIT.md
@@ -1,4 +1,4 @@
-# Deep Audit of `substack-mcp-plus`
+# Deep Audit of `substack-mcp`
 
 Date: 2026-05-27  
 Branch: `audit/complete-mcp`  

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Browser setup now stores the full authenticated Substack cookie jar after CAPTCHA, password, magic-link, or email-verification flows.
 - Authenticated requests now reuse the stored cookie jar instead of only `substack.sid`, fixing logins that succeeded in the browser but failed later in the MCP server.
-- Auth tests now isolate local storage from the developer machine's real `~/.substack-mcp-plus` auth files.
+- Auth tests now isolate local storage from the developer machine's real `~/.substack-mcp` auth files.
 - Scheduling regression tests now use future-safe timestamps.
 
 ### Security
@@ -57,7 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.2] - 2025-07-07
 
 ### Added
-- New `substack-mcp-plus-setup` command for easy authentication setup
+- New `substack-mcp-setup` command for easy authentication setup
 - No more hunting for node_modules directories!
 
 ### Changed
@@ -94,7 +94,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - GitHub Actions CI/CD workflow
   - CONTRIBUTING.md with detailed guidelines
   - LICENSE file (MIT)
-  - docs/ROADMAP.md with prioritized next steps
+  - docs/VISION.md with longer-term direction
   - docs/TODO.md with current work items and subtasks for contributors
   - docs/KNOWN_ISSUES.md documenting all current limitations
   - docs/COVERAGE_REPORT.md with detailed test coverage by module
@@ -114,12 +114,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Project state awareness checklist
 
 ### Changed
-- Updated repository URLs to abanoub-ashraf/substack-mcp-plus
+- Updated repository URLs to IgnazioDS/Substak-MCP
 - Updated package descriptions to clarify unofficial status
 - Enhanced .gitignore with comprehensive patterns
 - Fixed author information in package metadata
 - Reorganized documentation structure:
-  - Moved ROADMAP.md to docs/
+  - Moved long-term planning content to docs/
   - Moved QUICKSTART.md to docs/
   - Moved GITHUB_READY.md to docs/internal/
   - Updated all document references

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -249,11 +249,12 @@ python3 -m pytest --cov=src --cov-report=term
 ## Project State Awareness
 
 Before starting ANY work:
-1. Check `docs/ROADMAP.md` for current priorities
+1. Check `docs/TODO.md` for current priorities and active tasks
 2. Check `docs/KNOWN_ISSUES.md` for existing problems
 3. Check `docs/COVERAGE_REPORT.md` for testing priorities
-4. Run `python3 -m pytest` to see current test status
-5. Use TodoRead to see any ongoing work
+4. Check `docs/VISION.md` for longer-term direction when planning larger work
+5. Run `python3 -m pytest` to see current test status
+6. Use TodoRead to see any ongoing work
 
 ## Starting a Work Session
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
-# Contributing to Substack MCP Plus
+# Contributing to Substack MCP
 
-First off, thank you for considering contributing to Substack MCP Plus! It's people like you that make Substack MCP Plus such a great tool.
+First off, thank you for considering contributing to Substack MCP! It's people like you that make Substack MCP such a great tool.
 
 ## Code of Conduct
 
@@ -35,7 +35,7 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 ### What to Work On
 
 Check our [TODO.md](docs/TODO.md) for current work items with detailed subtasks you can claim.
-Also see [ROADMAP.md](docs/ROADMAP.md) for longer-term features and improvements.
+Also see [VISION.md](docs/VISION.md) for longer-term direction.
 
 We especially welcome:
 * Bug fixes (always high priority)
@@ -61,8 +61,8 @@ We especially welcome:
 1. Fork the repo and create your branch from `main`
 2. Clone your fork:
    ```bash
-   git clone https://github.com/your-username/substack-mcp-plus.git
-   cd substack-mcp-plus
+   git clone https://github.com/your-username/Substak-MCP.git
+   cd Substak-MCP
    ```
 
 3. Install dependencies:
@@ -169,7 +169,7 @@ Fixes #123
 ## Project Structure
 
 ```
-substack-mcp-plus/
+Substak-MCP/
 ├── src/                 # Source code
 │   ├── converters/      # Format converters
 │   ├── handlers/        # API handlers
@@ -198,4 +198,4 @@ Feel free to open an issue with your question or reach out to the maintainers.
 
 This project was originally forked from [substack-mcp](https://github.com/marcomoauro/substack-mcp) by Marco Moauro. We're grateful for the foundation it provided!
 
-Thank you for contributing! 🎉
+Thank you for contributing! 🎉
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 </p>
 
 <p align="center">
-  <b>Substack MCP server for AI clients</b> &mdash; draft, publish, schedule, analyze, and research Substack publications from <b>Claude</b>, <b>Cursor</b>, <b>Codex</b>, <b>Windsurf</b>, <b>Antigravity</b>, and any Model Context Protocol client.
+  <b>Substack MCP server for AI clients</b> &mdash; draft, publish, schedule, analyze, and research Substack publications from clients that support stdio MCP servers, including <b>Claude</b>, <b>Cursor</b>, <b>Codex</b>, <b>Windsurf</b>, and other compatible MCP hosts.
 </p>
 
 <p align="center">
@@ -83,19 +83,25 @@ npm install -g github:IgnazioDS/Substak-MCP
 This installs two commands:
 
 ```bash
-substack-mcp-plus
-substack-mcp-plus-setup
+substack-mcp
+substack-mcp-setup
 ```
 
+Naming note:
+- the repository is `IgnazioDS/Substak-MCP`
+- the current npm package is `@ignaziods/substack-mcp`
+- the installed commands are `substack-mcp` and `substack-mcp-setup`
+- the default MCP server key in examples is `substack-mcp`
+
 ### Migrating From the Old Package
 
-If you previously installed another package variant, remove it before
+If you previously installed the older plus-era package, remove it before
 installing from this repository:
 
 ```bash
-npm uninstall -g substack-mcp-plus
+npm uninstall -g @ignaziods/substack-mcp-plus
 npm install -g github:IgnazioDS/Substak-MCP
-substack-mcp-plus-setup
+substack-mcp-setup
 ```
 
 After reinstalling, fully restart your MCP client so it reloads the command.
@@ -105,7 +111,7 @@ After reinstalling, fully restart your MCP client so it reloads the command.
 Run the setup wizard:
 
 ```bash
-substack-mcp-plus-setup
+substack-mcp-setup
 ```
 
 The setup flow will:
@@ -114,11 +120,13 @@ The setup flow will:
 - handle CAPTCHA/manual login flow
 - store an encrypted browser session locally for later use
 
-The local auth file lives at `~/.substack-mcp-plus/auth.json`. The setup stores
+The local auth file lives at `~/.substack-mcp/auth.json`. The setup stores
 the browser session cookie jar after login, not your Substack password.
+If you already have auth stored under `~/.substack-mcp-plus/`, the runtime
+reuses that legacy directory until you migrate it.
 
 If Substack sends an email sign-in link, open or paste that link in the same
-browser window opened by `substack-mcp-plus-setup`. That same-browser step is
+browser window opened by `substack-mcp-setup`. That same-browser step is
 what lets the setup capture the final authenticated session.
 
 If your client later says authentication failed, run the setup again.
@@ -132,8 +140,8 @@ Server block:
 ```json
 {
   "mcpServers": {
-    "substack-mcp-plus": {
-      "command": "substack-mcp-plus",
+    "substack-mcp": {
+      "command": "substack-mcp",
       "env": {
         "SUBSTACK_PUBLICATION_URL": "https://YOUR_PUBLICATION.substack.com",
         "SUBSTACK_DEVELOPER_API_TOKEN": "optional-developer-api-token"
@@ -143,13 +151,17 @@ Server block:
 }
 ```
 
+`SUBSTACK_DEVELOPER_API_TOKEN` is only needed for the limited Developer API
+profile-lookup surface. Most account tools and public research flows do not
+require it.
+
 If your GUI client does not inherit your shell `PATH`, use an absolute path instead:
 
 ```bash
-which substack-mcp-plus
+which substack-mcp
 ```
 
-Then replace `"substack-mcp-plus"` with the full path to the binary.
+Then replace `"substack-mcp"` with the full path to the binary.
 
 ### Client Notes
 
@@ -159,15 +171,15 @@ Then replace `"substack-mcp-plus"` with the full path to the binary.
   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`
 - Claude Code
-  Add the same `mcpServers.substack-mcp-plus` block to `~/.claude.json`.
+  Add the same `mcpServers.substack-mcp` block to `~/.claude.json`.
 - Codex
   Add this to `~/.codex/config.toml`:
 
   ```toml
-  [mcp_servers.substack-mcp-plus]
-  command = "substack-mcp-plus"
+  [mcp_servers.substack-mcp]
+  command = "substack-mcp"
 
-  [mcp_servers.substack-mcp-plus.env]
+  [mcp_servers.substack-mcp.env]
   SUBSTACK_PUBLICATION_URL = "https://YOUR_PUBLICATION.substack.com"
   SUBSTACK_DEVELOPER_API_TOKEN = "optional-developer-api-token"
   ```
@@ -184,6 +196,8 @@ After updating the config, fully restart the client.
 
 ## Tool List
 
+The server currently registers 29 tools.
+
 ### Publishing and Account Tools
 
 - `create_formatted_post`
@@ -296,7 +310,7 @@ Your client may not inherit your shell `PATH`.
 Find the installed binary:
 
 ```bash
-which substack-mcp-plus
+which substack-mcp
 ```
 
 Then use the absolute path in the client config.
@@ -306,7 +320,7 @@ Then use the absolute path in the client config.
 Run setup again:
 
 ```bash
-substack-mcp-plus-setup
+substack-mcp-setup
 ```
 
 If Substack sent a sign-in email, paste the email link into the same setup
@@ -337,41 +351,55 @@ Usually weaker:
 
 ### GUI client still cannot launch the server
 
-Use an absolute command path instead of `substack-mcp-plus`.
+Use an absolute command path instead of `substack-mcp`.
 
 ## Development
 
-Install editable Python dependencies in the project venv:
+For local development, activate the project virtual environment first:
 
 ```bash
-./venv/bin/python -m pip install -e '.[dev]'
+source venv/bin/activate
+python3 -m pip install -e '.[dev]'
 ```
 
 Run tests:
 
 ```bash
-./venv/bin/python -m pytest -q
+python3 -m pytest -q
 ```
 
-Run the server directly:
+Run the Python server directly:
+
+```bash
+python3 -m src.server
+```
+
+Run the npm wrapper entrypoint used by the installed CLI:
 
 ```bash
 node src/index.js
 ```
 
+If you are developing from the repository and the auth setup cannot launch
+Chromium, install the Playwright browser once:
+
+```bash
+python3 -m playwright install chromium
+```
+
 ## Security
 
 - Do not commit tokens, passwords, or private keys.
 - Prefer interactive setup over hardcoded credentials.
-- Stored browser session data is encrypted under `~/.substack-mcp-plus/`.
+- Stored browser session data is encrypted under `~/.substack-mcp/`.
 - Use obvious placeholders in configs and examples.
 - Re-run authentication if a stored Substack session expires.
 
 See [SECURITY.md](SECURITY.md) for project security notes.
 
 ## 💖 Sponsor This Project
 
-Substak‑MCP is built and maintained in the open by [@IgnazioDS](https://github.com/IgnazioDS). If your team relies on it, or you'd like to support continued development of new tools, integrations, and improvements, please consider sponsoring:
+`Substak-MCP` is built and maintained in the open by [@IgnazioDS](https://github.com/IgnazioDS). If your team relies on it, or you'd like to support continued development of new tools, integrations, and improvements, please consider sponsoring:
 
 - ❤️ **GitHub Sponsors:** https://github.com/sponsors/IgnazioDS
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -10,7 +10,7 @@
 
 ## 🔐 Security Best Practices
 
-When using Substack MCP Plus, please follow these security best practices:
+When using Substack MCP, please follow these security best practices:
 
 ### Environment Variables
 - **Never commit your `.env` file** to version control
@@ -20,7 +20,7 @@ When using Substack MCP Plus, please follow these security best practices:
 
 ### Authentication
 - **Browser Setup Method** (Recommended):
-  - Use `substack-mcp-plus-setup`
+  - Use `substack-mcp-setup`
   - Complete CAPTCHA, password, magic-link, or email verification in the setup browser
   - If Substack emails a sign-in link, paste it into the same setup browser
   - The tool stores encrypted session cookies, not your Substack password
@@ -31,7 +31,7 @@ When using Substack MCP Plus, please follow these security best practices:
   - Revoke tokens immediately if compromised
 
 ### Local Auth Storage
-- Browser session data is encrypted at `~/.substack-mcp-plus/auth.json`
+- Browser session data is encrypted at `~/.substack-mcp/auth.json`
 - The auth file is written with owner-only permissions (`600`)
 - The auth directory is written with owner-only permissions (`700`)
 - Never commit `auth.json`, `.key`, `.env`, cookies, tokens, or terminal logs that contain secrets
@@ -43,7 +43,7 @@ When using Substack MCP Plus, please follow these security best practices:
 
 ## 🚨 Reporting Security Vulnerabilities
 
-We take security seriously. If you discover a security vulnerability in Substack MCP Plus, please follow these steps:
+We take security seriously. If you discover a security vulnerability in Substack MCP, please follow these steps:
 
 ### 1. Do NOT Create a Public Issue
 Security vulnerabilities should be reported privately to prevent exploitation.
@@ -103,4 +103,4 @@ Security updates will be released as soon as possible after discovery and fix. U
 
 ---
 
-Thank you for helping keep Substack MCP Plus secure!
+Thank you for helping keep Substack MCP secure!
diff --git a/docs/CLAUDE_DESKTOP_QUICK_TEST.md b/docs/CLAUDE_DESKTOP_QUICK_TEST.md
@@ -1,4 +1,4 @@
-# Claude Desktop Test Checklist for Substack MCP Plus
+# Claude Desktop Test Checklist for Substack MCP
 
 ## Quick Test Order (Safest First)
 

diff --git a/docs/ERROR_HANDLING_FIXES.md b/docs/ERROR_HANDLING_FIXES.md
@@ -1,6 +1,6 @@
 # Error Handling Fixes Summary
 
-This document captures the debugging path I used to fix critical errors in Substack MCP Plus, especially the `"'str' object has no attribute 'get'"` failures that affected multiple tools.
+This document captures the debugging path I used to fix critical errors in Substack MCP, especially the `"'str' object has no attribute 'get'"` failures that affected multiple tools.
 
 ## The Problem