# Text Processor MCP

A text processing toolkit with **9 tools** for text analysis, available as:
- **MCP server** (`server.py`) — for any MCP client (Claude, VS Code, etc.)
- **Gradio web UI** (`app.py`) — browser interface with tabs for each tool
- **Pi plugin** (`text-processor-plugin/`) — skills + extension for [Pi](https://pi.dev) coding agent

## 🚀 Quick Start

```bash
# Install dependencies
uv sync

# Run the MCP server (stdio)
uv run python server.py

# Run the Gradio web UI
uv run python app.py
```

## 🛠 Tools

| # | Tool | Description | Method |
|---|------|-------------|--------|
| 1 | **Analyze Text** | Word/sentence/character statistics | Pure Python |
| 2 | **Extract Keywords** | Most frequent words (with stopword filtering) | `Counter` |
| 3 | **Check Reading Level** | Flesch-Kincaid grade level estimate | Pure Python |
| 4 | **Reverse Text** | Reverse a string | Pure Python |
| 5 | **Analyze Sentiment** | Polarity (-1 to +1) and subjectivity | `TextBlob` |
| 6 | **Detect Language** | Identify language of text | `langid` |
| 7 | **Summarize Text** | Extractive summarization (word frequency scoring) | Pure Python |
| 8 | **Check Spelling** | Find misspelled words + suggest corrections | `TextBlob` |
| 9 | **Readability Tips** | Suggestions for clearer writing (sentence length, passive voice, repetition) | Pure Python |

## 🧪 Examples

All examples use the same input text about English articles.

**Input text:**
> The articles in English are the definite article the and the indefinite article a (which takes the alternate form an when followed by a vowel sound). They are the two most common determiners. The definite article is the default determiner when the speaker believes that the listener knows the identity of a common noun's referent (because it is obvious, because it is common knowledge, or because it was mentioned in the same sentence or an earlier sentence). The indefinite article is the default determiner for other singular, countable, common nouns, while no determiner is the default for other common nouns. Other determiners are used to add semantic information such as amount (many, a few), proximity (this, those), or possession (my, the government's).

---

### 1. Analyze Text

**Input:** `analyze_text(text)`

**Output:**
```json
{
  "total_characters": 760,
  "characters_without_spaces": 639,
  "total_words": 122,
  "total_sentences": 5,
  "average_word_length": 5.24,
  "average_sentence_length": 24.4,
  "unique_words": 74
}
```

---

### 2. Extract Keywords

**Input:** `extract_keywords(text, count=8)`

**Output:**
```json
{
  "keywords": [
    {"word": "common", "frequency": 5},
    {"word": "article", "frequency": 4},
    {"word": "default", "frequency": 3},
    {"word": "determiner", "frequency": 3},
    {"word": "other", "frequency": 3},
    {"word": "definite", "frequency": 2},
    {"word": "indefinite", "frequency": 2}
  ]
}
```

---

### 3. Check Reading Level

**Input:** `check_reading_level(text)`

**Output:**
```json
{
  "grade_level": 17.6,
  "reading_level": "College/Academic"
}
```

---

### 4. Reverse Text

**Input:** `reverse_text("Hello World")`

**Output:**
```
dlroW olleH
```

---

### 5. Analyze Sentiment

**Input:** `analyze_sentiment(text)`

**Output:**
```json
{
  "polarity": -0.034,
  "subjectivity": 0.388,
  "sentiment_label": "Neutral",
  "subjectivity_label": "Objective"
}
```

Polarity: -1 (negative) to +1 (positive). Subjectivity: 0 (objective) to 1 (subjective).

---

### 6. Detect Language

**Input:** `detect_language(text)`

**Output:**
```json
{
  "language_code": "en",
  "language_name": "English",
  "confidence": -1851.642
}
```

**More examples:**
| Input | Result |
|-------|--------|
| `"Артикли в английском языке..."` | `ru` (Russian) |
| `"Les articles en anglais..."` | `fr` (French) |
| `"Die Artikel im Englischen..."` | `de` (German) |

---

### 7. Summarize Text

**Input:** `summarize_text(text, max_sentences=3)`

**Output:**
```json
{
  "summary": "They are the two most common determiners. The indefinite article is the default determiner for other singular, countable, common nouns, while no determiner is the default for other common nouns.",
  "original_sentences": 5,
  "summary_sentences": 2,
  "compression_ratio": "40%"
}
```

---

### 8. Check Spelling

**Input:** `check_spelling("The definte article is the most common determiner in english.")`

**Output:**
```json
{
  "misspelled_count": 2,
  "misspelled_words": [
    {
      "original": "definte",
      "suggestions": ["definite", "define"],
      "best_correction": "definite",
      "confidence": 0.857
    },
    {
      "original": "determiner",
      "suggestions": ["determined", "determine"],
      "best_correction": "determined",
      "confidence": 0.577
    }
  ],
  "corrected_text": "The definite article is the most common determined in english."
}
```

---

### 9. Readability Tips

**Input:** `readability_tips(text)`

**Output:**
```json
{
  "overall_assessment": "Found 3 area(s) for improvement (severity: moderate).",
  "statistics": {
    "sentence_count": 5,
    "word_count": 122,
    "avg_sentence_length": 24.4,
    "avg_word_length": 5.0
  },
  "tips": [
    {
      "issue": "Sentences are slightly long",
      "detail": "Average sentence length is 24.4 words.",
      "suggestion": "Consider shortening some sentences to improve clarity."
    },
    {
      "issue": "Too many long words",
      "detail": "Found 4 words longer than 10 characters.",
      "suggestion": "Use simpler, shorter alternatives for complex terms."
    },
    {
      "issue": "Word repetition",
      "detail": "Some words are overused: \"common\" (5x), \"article\" (4x).",
      "suggestion": "Use synonyms or pronouns to vary your vocabulary."
    }
  ]
}
```

## 📦 Dependencies

- `mcp[cli]` — Model Context Protocol framework
- `gradio` — Web UI framework
- `textblob` — NLP (sentiment, spelling)
- `langid` — Language detection (97 languages)

## 🏗 Project Structure

```
text-processor-mcp/
├── .mcp.json                 # MCP client config (stdio)
├── .gitignore                # Git ignore rules
├── server.py                 # MCP server with all 9 tools
├── app.py                    # Gradio web UI (8 tabs)
├── pyproject.toml            # Project config & dependencies
├── uv.lock                   # Locked dependency versions
├── text-processor-plugin/    # Pi package (skills + extension)
│   ├── package.json
│   ├── README.md
│   ├── extensions/
│   │   └── text-processor.ts
│   └── skills/
│       ├── analyze-text/SKILL.md
│       ├── extract-keywords/SKILL.md
│       ├── check-reading-level/SKILL.md
│       ├── reverse-text/SKILL.md
│       ├── analyze-sentiment/SKILL.md
│       ├── detect-language/SKILL.md
│       ├── summarize-text/SKILL.md
│       ├── check-spelling/SKILL.md
│       └── readability-tips/SKILL.md
└── README.md
```

## 🔌 MCP Integration

Two ways to connect: **stdio** (standalone MCP server) or **SSE** (via Gradio, which also serves the web UI).

Choose the approach that fits your client.

---

### ⚡ Pi (the coding agent)

Pi doesn't support MCP natively. Two options:

**Option 1 — Use the Pi plugin (recommended):**

Install the plugin with skills + extension:

```bash
pi install ./text-processor-plugin
```

Then install the MCP adapter for direct tool access:

```bash
pi install npm:pi-mcp-adapter
```

The project already ships with `.mcp.json` pre-configured for stdio.

**Option 2 — Global config via `~/.config/pi/config.json`:**

```json
{
  "mcpServers": {
    "text-processor": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/text-processor-mcp", "python", "server.py"]
    }
  }
}
```

---

### 🖥 Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "text-processor": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/text-processor-mcp", "python", "server.py"]
    }
  }
}
```

---

### 💻 VS Code (Cline / Continue / etc.)

These clients read `.mcp.json` from the project root automatically:

```json
{
  "servers": {
    "text-processor": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/text-processor-mcp", "python", "server.py"]
    }
  }
}
```

> **Note:** Replace `/path/to/text-processor-mcp` with the absolute path to the project.

---

### 📁 Project-level `.mcp.json` (already included)

The project ships with `.mcp.json` pre-configured for **stdio** (standalone MCP server). Edit it to switch to SSE or adjust paths as needed.

## 🖥 Web UI

Run `uv run python app.py` to open the Gradio interface with tabs for each tool. The Gradio app also exposes MCP tools via SSE at `http://127.0.0.1:7860/gradio_api/mcp/`.