Writer Context Tool

What is Writer Context Tool about?

Writer Context Tool bridges Claude with your Substack and Medium blogs. It fetches, caches, and embeds every published essay so Claude can retrieve relevant content on demand, offering context‑aware help while you write.

How to use Writer Context Tool?

1. Clone the repository and set up a Python environment (uv or pip).
2. Copy config.example.json to config.json and fill in your Substack/Medium URLs and optional limits.
3. Create a Claude Desktop configuration that points to the script writer_tool.py (or the provided run_writer_tool.sh).
4. Restart Claude Desktop – the tool will preload all posts, generate embeddings, and expose each essay as a separate resource.
5. Inside Claude, invoke the semantic search tool search_writing or the refresh tool refresh_content as needed.

Key features of Writer Context Tool

• Retrieves and permanently caches blog posts from Substack and Medium via RSS.
• Generates embeddings for every essay to enable fast semantic search.
• Exposes each essay as an individual Claude resource.
• Provides built‑in tools:
  • search_writing – find the most relevant essays for a query.
  • refresh_content – force a fresh pull and re‑embedding of all posts.
• Preloads all content and embeddings at startup for instant responsiveness.

Use cases of Writer Context Tool

• Contextual writing assistance: Ask Claude to reference past articles when drafting new content.
• Content audit: Quickly locate where you have already covered a topic.
• Idea generation: Retrieve related essays to spark new angles or extensions.
• Knowledge base: Use your published work as a personal knowledge repository for Claude.

FAQ from the Writer Context Tool

Q: Do I need a paid Claude plan? A: The tool works with Claude Desktop, which requires a valid Claude subscription.

Q: Can I use platforms other than Substack or Medium? A: Currently only Substack and Medium RSS feeds are supported; additional platforms would require custom adapters.

Q: How often is the cache refreshed? A: Cache duration is configurable via cache_duration_minutes (default is one week). You can also trigger an immediate refresh with the refresh_content tool.

Q: What if embeddings fail to generate? A: Ensure sufficient disk space and that the embedding model dependencies are installed. Re‑run the startup script after fixing any environment issues.

Q: Is there a way to run this without Python? A: The project is Python‑based; an npm‑style wrapper is not provided, so use the recommended Python setup.

Writer Context Tool for Claude

Open-Sourced Model Context Protocol (MCP) implementation that connects Claude to your Substack and Medium writing.

What is this?

Writer Context Tool is an MCP server that allows Claude to access and analyze your writing from platforms like Substack and Medium. With this tool, Claude can understand the context of your published content, providing more personalized assistance with your writing.

Features

• 🔍 Retrieves and permanently caches your blog posts from Substack and Medium
• 🔎 Uses embeddings to find the most relevant essays based on your queries
• 📚 Makes individual essays available as separate resources for Claude
• 🧠 Performs semantic searches across your writing
• ⚡ Preloads all content and generates embeddings at startup

How It Works

The tool connects to your Substack/Medium blogs via their RSS feeds, fetches your posts, and permanently caches them locally. It also generates embeddings for each post, enabling semantic search to find the most relevant essays based on your queries.

When you ask Claude about your writing, it can use these individual essay resources to provide insights or help you develop new ideas based on your existing content.

Setup Instructions (Step by Step)

Prerequisites

• Python 3.10 or higher
• Claude Desktop (latest version)
• A Substack or Medium account with published content

1. Clone this Repository

git clone https://github.com/yourusername/writer-context-tool.git
cd writer-context-tool

2. Set up Python Environment

Using uv (recommended):

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

Or using standard pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Configure Your Blogs

1. Copy the example configuration file:

   cp config.example.json config.json
   

2. Edit config.json with your Substack/Medium URLs:

   {
     "platforms": [
       {
         "type": "substack",
         "url": "https://yourusername.substack.com",
         "name": "My Substack Blog"
       },
       {
         "type": "medium",
         "url": "https://medium.com/@yourusername",
         "name": "My Medium Blog"
       }
     ],
     "max_posts": 100,
     "cache_duration_minutes": 10080,
     "similar_posts_count": 10
   }
   

   • max_posts: Maximum number of posts to fetch from each platform (default: 100)
   • cache_duration_minutes: How long to cache content before refreshing (default: 1 week or 10080 minutes)
   • similar_posts_count: Number of most relevant posts to return when searching (default: 10)

4. Connect with Claude Desktop

1. Create the Claude Desktop configuration directory:

   # On macOS
   mkdir -p ~/Library/Application\ Support/Claude/
   

2. Create the configuration file:

   # Get the absolute path to your uv command
   UV_PATH=$(which uv)
   
   # Create the configuration
   cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << EOF
   {
     "mcpServers": {
       "writer-tool": {
         "command": "${UV_PATH}",
         "args": [
           "--directory",
           "$(pwd)",
           "run",
           "writer_tool.py"
         ]
       }
     }
   }
   EOF
   

   Note: If you experience issues with the uv command, you can use the included shell script alternative:

   1. Make the script executable: chmod +x run_writer_tool.sh
   2. Update your Claude Desktop config to use the script:

   {
     "mcpServers": {
       "writer-tool": {
         "command": "/absolute/path/to/run_writer_tool.sh",
         "args": []
       }
     }
   }
   

3. Restart Claude Desktop

Using the Tool with Claude

Once set up, you'll see individual essays available as resources in Claude Desktop. You can:

1. Search across your writing: Ask Claude to find relevant content

   • "Find essays where I discuss [specific topic]"
   • "What have I written about [subject]?"

2. Reference specific essays: Access individual essays by clicking on them when listed in search results

   • "Show me the full text of [essay title]"

3. Refresh content: Force a refresh of your content

   • "Refresh my writing content"

Available Tools and Resources

The Writer Context Tool provides:

1. Individual Essay Resources: Each of your essays becomes a selectable resource
2. search_writing: A semantic search tool that finds the most relevant essays using embeddings
3. refresh_content: Refreshes and recaches your content from all configured platforms

How Caching Works

The tool implements permanent caching with these features:

1. Disk Caching: All content is stored on disk, so it persists between sessions
2. Embeddings: Each essay is converted to embeddings for semantic search
3. Selective Refresh: The tool only refreshes content when needed according to your cache settings
4. Preloading: All content is automatically refreshed and embeddings generated at startup

Troubleshooting

If you encounter issues:

1. Tool doesn't appear in Claude Desktop:

   • Check that your Claude Desktop configuration file is correct
   • Verify that all paths in the configuration are absolute
   • Make sure your Python environment has all required packages
   • Restart Claude Desktop

2. No content appears:

   • Verify your Substack/Medium URLs in config.json
   • Try using the "refresh_content" tool
   • Check that your blogs are public and have published posts

3. Error with uv command:

   • Try using the shell script approach instead
   • Verify the uv command is installed and in your PATH

4. Embedding issues:

   • If you see errors about the embedding model, make sure you have enough disk space
   • Consider rerunning with a fresh installation if embeddings aren't working properly

License

This project is available under the MIT License.