textual-docs-mcp 0.1.0__tar.gz

textual_docs_mcp-0.1.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(python3:*)",
+      "WebSearch",
+      "Bash(ls:*)",
+      "Bash(find:*)"
+    ]
+  }
+}

textual_docs_mcp-0.1.0/.gemini/settings.json

@@ -0,0 +1,18 @@
+{
+    "mcpServers": {
+        "memory-bank-mcp": {
+            "type": "http",
+            "url": "http://localhost/mcp",
+            "headers": {
+                "Authorization": "Bearer mbmcp_live_u4rzQ2sot1Oo1URZNiX17iilRho4hYny"
+            }
+        },
+        "agent-mcp": {
+            "type": "http",
+            "url": "https://n8n.traekr.com/mcp/agent-mcp",
+            "headers": {
+                "Authorization": "sk_mcp_fxwEatbOmq1a8mvqzjoQtd2vSNwxUEQcXGYJwk0NX4QdWcL3"
+            }
+        }
+    }
+}

textual_docs_mcp-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,189 @@
+# Memory Bank — Copilot Instructions
+
+> Auto-generated by Memory Bank extension. Edit freely to customize.
+
+This project uses the Memory Bank MCP server to persist context across AI sessions.
+You have access to Memory Bank MCP tools. USE THEM — they are not optional.
+
+## Mandatory Workflow (every task, no exceptions)
+
+### START of task
+1. ⚠️ CALL THIS FIRST. Call `get_instructions` MCP tool to learn the full tool catalog and workflow (once per session)
+2. Call `get_context_digest` to load current project state (tasks, issues, progress, decisions)
+3. Read `system-patterns.md` (via `read_memory_bank_file`) to understand project conventions, architecture patterns, and coding standards
+4. Use `graph_search` to find relevant knowledge graph entities
+
+### DURING task
+5. Call `track_progress` after completing milestones
+6. Call `log_decision` when making architectural/design choices
+7. Call `add_session_note` for observations, blockers, or questions
+
+### END of task
+8. Call `update_active_context` with updated tasks, issues, and next steps
+9. Call `track_progress` with a final summary of what was accomplished
+10. Update knowledge graph entities if project structure changed
+11. Update `system-patterns.md` if new patterns, architecture, or conventions were introduced
+
+## If Memory Bank contains placeholder text
+If any core file contains `[Project description]` or `[Task 1]` style placeholders,
+the Memory Bank has never been initialized. You MUST populate all core files with real
+project data from the workspace before doing any other work.
+
+## First-Time Initialization Procedure
+When placeholder content is detected:
+1. Scan workspace: package.json, README, config files, source directories
+2. `write_memory_bank_file` for: product-context.md, active-context.md, progress.md, decision-log.md, system-patterns.md
+3. `graph_upsert_entity` + `graph_add_observation` + `graph_link_entities` for major components
+4. `add_session_note` → "Memory Bank initialized from workspace analysis."
+
+## Complete Tool Reference (47 tools)
+
+### 1. Instructions
+| Tool | Purpose |
+|------|---------|
+| `get_instructions` | Full tool catalog and workflow guide (call once per session) |
+
+### 2. Context Loading (read-only)
+| Tool | Purpose |
+|------|---------|
+| `get_context_digest` | Compact summary: recent progress, tasks, issues, decisions, graph overview |
+| `get_context_bundle` | Full content of ALL core files in one response (larger payload) |
+| `get_memory_bank_status` | Status of the Memory Bank (initialized, path, file list) |
+| `list_memory_bank_files` | List all files in the Memory Bank directory |
+| `search_memory_bank` | Full-text search across all Memory Bank files |
+| `get_current_mode` | Current active mode and its guidelines |
+
+### 3. File Operations
+| Tool | Purpose |
+|------|---------|
+| `read_memory_bank_file` | Read a single file (returns content + ETag) |
+| `write_memory_bank_file` | Write a single file (supports optimistic concurrency via ETag) |
+| `batch_read_files` | Read multiple files in one request |
+| `batch_write_files` | Write multiple files in one request |
+
+### 4. Progress Tracking
+| Tool | Purpose |
+|------|---------|
+| `track_progress` | Record a progress milestone (action + description) |
+| `add_progress_entry` | Structured progress entry with type, summary, details, files, tags |
+| `update_active_context` | Update tasks, issues, and next steps in active-context.md |
+| `update_tasks` | Add, remove, or replace the tasks list |
+| `add_session_note` | Add a timestamped note (observation, blocker, question, decision, todo) |
+| `log_decision` | Log an architectural/design decision with context and alternatives |
+
+### 5. Knowledge Graph
+| Tool | Purpose |
+|------|---------|
+| `get_targeted_context` | **Preferred.** Budgeted context pack via KG + excerpts. Use before batch_read_files or get_context_bundle |
+| `graph_search` | Search entities by query string |
+| `graph_open_nodes` | Expand specific nodes and their neighborhood |
+| `graph_upsert_entity` | Create or update an entity |
+| `graph_add_observation` | Add an observation to an entity |
+| `graph_add_doc_pointer` | Link an entity to a Memory Bank file + optional heading |
+| `graph_link_entities` | Create a typed relationship between entities |
+| `graph_unlink_entities` | Remove a relationship between entities |
+| `graph_delete_entity` | Delete an entity |
+| `graph_delete_observation` | Delete an observation |
+| `graph_rebuild` | Rebuild the graph index |
+| `graph_compact` | Compact the graph storage file |
+
+### 6. Modes
+| Tool | Purpose |
+|------|---------|
+| `switch_mode` | Switch to a mode: architect, code, ask, debug, or test |
+| `get_current_mode` | Get the current mode and its behavioral guidelines |
+| `process_umb_command` | Process an Update Memory Bank (UMB) command |
+| `complete_umb` | Complete the UMB process |
+
+### 7. Setup & Administration
+| Tool | Purpose |
+|------|---------|
+| `initialize_memory_bank` | Create a new Memory Bank in a directory |
+| `set_memory_bank_path` | Point to an existing Memory Bank directory |
+| `migrate_file_naming` | Migrate files from camelCase to kebab-case |
+| `debug_mcp_config` | Debug the current MCP configuration |
+
+### 8. Backup & Restore
+| Tool | Purpose |
+|------|---------|
+| `create_backup` | Create a timestamped backup of the Memory Bank |
+| `list_backups` | List all available backups |
+| `restore_backup` | Restore from a backup (auto-creates pre-restore backup) |
+
+### 9. Multi-Store Management
+| Tool | Purpose |
+|------|---------|
+| `list_stores` | List all registered Memory Bank stores |
+| `select_store` | Switch the active store (by path or storeId) |
+| `register_store` | Add a store to the persistent registry |
+| `unregister_store` | Remove a store from the registry |
+
+### 10. Sequential Thinking
+| Tool | Purpose |
+|------|---------|
+| `sequential_thinking` | Record a numbered thinking step (raw thought NOT returned) |
+| `reset_sequential_thinking` | Clear thinking session state |
+| `finalize_thinking_session` | Persist thinking outcomes to Memory Bank (summary, decisions, tasks, progress) |
+
+## Valid Modes
+The ONLY valid modes are: **architect**, **code**, **ask**, **debug**, **test**.
+There is NO "full" mode. All tools are available in every mode — modes control
+behavior guidelines (via .clinerules files), not tool access.
+
+## Important Notes
+- Keep your internal thought process private. Do NOT share it in the conversation.
+
+## ⚠️ CRITICAL: Never Access memory-bank/ Directly
+
+AI agents/LLMs must **NEVER** directly edit files in the `memory-bank/` folder
+using file editing tools (`replace_string_in_file`, `create_file`, `write_file`)
+or terminal commands (`echo`, `sed`, `cat >`).
+
+**All interactions with Memory Bank files MUST go through the MCP server tools:**
+
+| Operation | Tool(s) |
+|---|---|
+| Read files | `read_memory_bank_file`, `batch_read_files`, `get_context_bundle` |
+| Write files | `write_memory_bank_file`, `batch_write_files` |
+| Update context | `update_active_context`, `update_tasks` |
+| Track progress | `track_progress`, `add_progress_entry` |
+| Log decisions | `log_decision` |
+| Session notes | `add_session_note` |
+| Knowledge graph | `graph_upsert_entity`, `graph_add_observation`, `graph_link_entities`, etc. |
+| Search | `search_memory_bank`, `graph_search` |
+
+**Why?** The MCP server guarantees file integrity via ETag concurrency control,
+atomic writes, content validation, and event logging. Direct edits bypass all of
+these and can corrupt the Memory Bank state.
+
+## Agents and Subagents
+These are the subagents you have access to (in `.github/skills`). Call them as needed to accomplish tasks, but always follow the mandatory workflow and tool usage guidelines above.
+- **textual-expert**: Expert in Textual TUI development and documentation.
+- **python-runtime-expert**: Comprehensive Python ecosystem expertise (`uv`, `pip`, standard library).
+- **mcp-server-developer**: Building Python-based MCP servers using FastMCP.
+- **mcp-developer**: General MCP protocol compliance and SDK usage.
+- **testing-strategist**: Python testing with `pytest`.
+- **code-quality**: Clean code and SOLID principles in Python.
+- **debugging-strategies**: Systematic Python debugging.
+- **error-handling-patterns**: Robust Python error handling.
+- **security-best-practices**: Python-specific security mitigations.
+- **prompt-engineering**: Secure prompt construction with Python validation.
+- **agent-creator**: Designing Multi-Agent Systems in Python.
+- **skill-creator**: Crafting specialized AI agent skills.
+- **skill-writer**: Authoring SKILL.md files.
+- **code-review** / **code-reviewer**: Systematic Python code audits.
+- **code-review-excellence**: High-signal Python review standards.
+- **multi-reviewer-patterns**: Coordinating complex Python audits.
+- **mcp-builder**: High-quality MCP server design.
+- **security-threat-model**: Repository-grounded Python threat modeling.
+
+## 🛠️ MCP Servers (from .vscode/mcp.json)
+This project is configured with several MCP servers to enhance development:
+- **memory-bank-mcp**: Manages project context and history. Use it for all Memory Bank operations.
+- **context7**: Expert documentation lookup. Use it to fetch current documentation for libraries and frameworks (refer to `repos/context7` for implementation patterns).
+- **sequential-thinking**: Provides structured reasoning capabilities. Use it for complex architectural decisions.
+- **python-lsp-mcp**: Provides Python Language Server capabilities. Essential for Python development in this project.
+- **semgrep**: Performs static analysis for security and code quality.
+- **mcp-compass**: Helps navigate and understand the codebase.
+- **ripgrep**: Fast text searching across the repository.
+- **analyzer**: Analyzes MCP server implementations.

textual_docs_mcp-0.1.0/.github/skills/agent-creator/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: agent-creator
+description: "Guide for creating Multi-Agent System (MAS) implementations in Python. Use this skill when you need to create agent teams with different coordination patterns: centralized (orchestrator) or decentralized (workflow). Uses filesystem tools (write_file, edit_file, read_file) to create complete agent team structures in the project directory with proper configuration, Python-based prompts, and definitions based on task requirements."
+---
+# Agent Creator (Python)
+
+This skill provides guidance and templates for creating Multi-Agent System (MAS) implementations in Python. It supports two main coordination patterns: centralized (orchestrator) or decentralized (workflow).
+
+## Quick Start
+
+**How This Skill Works:**
+- 🛠️ **Uses MCP Tools**: Leverages filesystem's `write_file`, `edit_file`, and `read_file` tools.
+- 📁 **Target Location**: Creates all agent structures in `./src/agents/` or relevant directory.
+- 🔄 **Auto-Integration**: Works seamlessly with Python-based discovery.
+- 📋 **Template-Based**: Uses Python classes or Pydantic models to guide implementation.
+
+**Typical Workflow:**
+1. **Analyze**: Understand task requirements and determine MAS type (orchestrator or workflow).
+2. **Design**: Plan agent structure, Python roles, and responsibilities.
+3. **Create**: Use `write_file` to create directory structure and files in `./src/agents/{team_name}/`.
+4. **Customize**: Implement Python agent configs, prompts, and initialization.
+5. **Verify**: Ensure all Python files are created with correct structure, imports, and **proper indentation** (PEP 8).
+6. **Smoke Test**: Run a basic test script to ensure agents can initialize and communicate.
+
+**⚠️ Critical: Python File Indentation**
+- All top-level code (imports, class definitions, function definitions) must start at column 0 (no indentation).
+- If using Python to generate files, ensure string content doesn't have extra indentation.
+- Always verify generated files using `read_file` to check indentation is correct.
+
+## Overview
+
+Multi-Agent Systems can be structured in different ways depending on task complexity and coordination needs:
+
+1. **Centralized**: Uses an orchestrator agent to coordinate and delegate tasks to specialized worker agents. Best for complex tasks requiring dynamic routing.
+
+2. **Decentralized**: Agents execute in a workflow sequence. Best for well-defined, sequential tasks where each agent has a specific role.
+
+## MAS Type Selection Guide
+
+### When to Use Orchestrator (Centralized)
+
+Choose an orchestrator when:
+- Task requires dynamic routing based on intermediate results.
+- Multiple specialized agents need coordination from a central decision-maker.
+- Task complexity requires adaptive planning and delegation.
+- Agent selection depends on context and task analysis.
+- Example: Documentation crawler that analyzes a topic and delegates to specific search or extraction agents.
+
+**Architecture Pattern:**
+```
+Orchestrator Agent (Leader)
+    ├── Agent 1 (Specialist)
+    ├── Agent 2 (Specialist)
+    └── Agent 3 (Specialist)
+```
+
+### When to Use Workflow (Decentralized)
+
+Choose a workflow when:
+- Task has a clear, sequential workflow.
+- Each agent performs a specific step in a pipeline.
+- Agent order is predetermined.
+- No dynamic routing or coordination needed.
+- Example: Data extraction pipeline: crawler → parser → formatter.
+
+**Architecture Pattern:**
+```
+Agent 1 → Agent 2 → Agent 3 → Agent 4
+```
+
+## Creating a MAS (Python)
+
+### Step 1: Analyze Task Requirements
+1. Identify the core task and its complexity.
+2. Determine if dynamic coordination is needed (orchestrator) or fixed sequence (workflow).
+3. List required Python agent roles and their responsibilities.
+4. Identify MCP servers and tools needed by each agent.
+
+### Step 2: Choose MAS Type
+Refer to the selection guide above. If unsure, start with a workflow for simpler tasks.
+
+### Step 3: Design Agent Structure (Python)
+For **Orchestrator**:
+- Design orchestrator agent with Python coordination logic.
+- Design specialized worker agents.
+- Define handoff patterns from orchestrator to workers.
+
+For **Workflow**:
+- Define sequential agent roles.
+- Establish Python data flow between agents.
+- Ensure each agent has clear input/output responsibilities.
+
+### Step 4: Create Agent Implementation (Python)
+Use `write_file` to create files in the appropriate directory:
+1. **Create Structure**: Use `write_file` to create files in `./src/agents/{team_name}/` directory.
+2. **Customize Content**: Implement Python agent-specific configs, prompts, and initialization.
+
+**Simplified Approach** (Recommended):
+- Create `config.py` and `prompt.py` for each agent role.
+- In `main.py`, instantiate agent classes with config and prompt.
+
+### Step 5: Implement Initialization
+Create a `main.py` or entrypoint that:
+- Imports agent classes.
+- Imports configs and prompts.
+- Instantiates agent instances with their respective roles.
+- Initializes the MAS (orchestrator or workflow).
+
+## Resources
+
+### scripts/
+- `create_mas.py`: Script to generate MAS structure in Python.
+- `validate_structure.py`: Validates generated Python MAS structure.
+
+## Best Practices (Python)
+
+1. **Start Simple**: Begin with a workflow for straightforward tasks.
+2. **Clear Agent Roles**: Each agent should have a single, well-defined responsibility.
+3. **Prompt Design**: Python-based system prompts should clearly define agent behavior and decision criteria.
+4. **Error Handling**: Implement robust Python error handling in orchestrator agents.
+5. **Testing**: Test each Python agent independently before integration.
+6. **Documentation**: Document Python agent responsibilities and expected inputs/outputs.

textual_docs_mcp-0.1.0/.github/skills/code-quality/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: code-quality
+description: Clean code principles, SOLID, and code review practices for Python development.
+domain: software-engineering
+version: 1.0.0
+tags: [clean-code, solid, refactoring, code-review, python, linting]
+triggers:
+  keywords:
+    primary: [code quality, clean code, solid, refactor, code review, lint]
+    secondary: [dry, kiss, yagni, code smell, technical debt, static analysis]
+  context_boost: [maintainable, readable, best practice, standards]
+  priority: high
+---
+
+# Code Quality (Python)
+
+## Overview
+
+Principles and practices for writing maintainable, readable, and reliable Python code.
+
+---
+
+## Clean Code Principles
+
+### Meaningful Names
+
+```python
+# ❌ Cryptic names
+d = datetime.now()
+u = get_u()
+arr = [x for x in data if x.s == 'a']
+
+# ✅ Descriptive names
+current_date = datetime.now()
+current_user = get_current_user()
+active_users = [user for user in users if user.status == 'active']
+
+# ❌ Hungarian notation or type prefixing
+str_name = 'John'
+list_items = []
+is_active_bool = True
+
+# ✅ Use names that describe intent
+name = 'John'
+items = []
+is_active = True
+```
+
+### Functions
+
+```python
+# ❌ Does too much
+def process_user_data(user_id):
+    user = db.find_user(user_id)
+    orders = db.find_orders(user_id)
+    total = sum(o.amount for o in orders)
+    send_email(user.email, f"Your total: {total}")
+    update_analytics(user_id, total)
+    return user, orders, total
+
+# ✅ Single responsibility
+def get_user(user_id):
+    return db.find_user(user_id)
+
+def get_user_orders(user_id):
+    return db.find_orders(user_id)
+
+def calculate_total(orders):
+    return sum(o.amount for o in orders)
+
+def send_order_summary(email, total):
+    send_email(email, f"Your total: {total}")
+
+# ❌ Too many parameters
+def create_user(name, email, age, role, department, manager, start_date):
+    pass
+
+# ✅ Use a Pydantic model or dataclass
+from pydantic import BaseModel
+from datetime import date
+
+class UserCreate(BaseModel):
+    name: str
+    email: str
+    age: int | None = None
+    role: str
+    department: str
+    manager_id: str | None = None
+    start_date: date
+
+def create_user(user_data: UserCreate):
+    pass
+```
+
+### Comments
+
+```python
+# ❌ Redundant comment
+# Increment counter by 1
+counter += 1
+
+# ❌ Outdated comment
+# Returns the user's full name
+def get_user_email(user):
+    return user.email
+
+# ✅ Explains WHY, not WHAT
+# Use binary search because the list is sorted and can have 100k+ items
+index = bisect_left(sorted_items, target)
+
+# ✅ Warns about non-obvious behavior
+# IMPORTANT: This function mutates the input list for performance reasons
+def quick_sort_in_place(arr):
+    pass
+
+# ✅ TODO with context
+# TODO: Remove after migration completes - tracking in JIRA-1234
+legacy_adapter = LegacyAdapter()
+```
+
+---
+
+## SOLID Principles in Python
+
+### Single Responsibility Principle (SRP)
+
+```python
+# ❌ Multiple responsibilities
+class UserManager:
+    def create_user(self, data): ... # DB logic
+    def validate_email(self, email): ... # Validation
+    def send_welcome_email(self, user): ... # Email logic
+
+# ✅ Single responsibility each
+class UserRepository:
+    def create(self, data): ...
+
+class UserValidator:
+    def validate_email(self, email): ...
+
+class EmailService:
+    def send_welcome_email(self, user): ...
+```
+
+### Open/Closed Principle (OCP)
+
+```python
+# ✅ Open for extension, closed for modification using Abstract Base Classes
+from abc import ABC, abstractmethod
+
+class PaymentMethod(ABC):
+    @abstractmethod
+    def process(self, amount: float):
+        pass
+
+class CreditCardPayment(PaymentMethod):
+    def process(self, amount: float):
+        print(f"Processing credit card payment of {amount}")
+
+class PayPalPayment(PaymentMethod):
+    def process(self, amount: float):
+        print(f"Processing PayPal payment of {amount}")
+
+class PaymentProcessor:
+    def __init__(self, method: PaymentMethod):
+        self.method = method
+        
+    def process(self, amount: float):
+        self.method.process(amount)
+```
+
+---
+
+## Python-Specific Best Practices
+
+### Use Type Hints
+Python 3.5+ supports type hints. Use them to improve readability and catch errors.
+
+```python
+def greet(name: str) -> str:
+    return f"Hello, {name}"
+```
+
+### Docstrings (PEP 257)
+Use docstrings for modules, classes, and functions.
+
+```python
+def calculate_area(radius: float) -> float:
+    """
+    Calculate the area of a circle.
+    
+    Args:
+        radius: The radius of the circle.
+        
+    Returns:
+        The area of the circle.
+    """
+    import math
+    return math.pi * radius ** 2
+```
+
+---
+
+## Tooling
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| **Ruff** | Linting & Formatting | `ruff check .` / `ruff format .` |
+| **Pytest** | Testing | `pytest` |
+| **Mypy** | Static Type Checking | `mypy .` |
+| **Pydantic** | Data Validation | (Library) |
+
+---
+
+## Related Skills
+
+- [[debugging-strategies]] - Investigating Python issues
+- [[testing-strategist]] - Python testing patterns

textual_docs_mcp-0.1.0/.github/skills/code-quality/templates/.editorconfig

@@ -0,0 +1,60 @@
+# EditorConfig Template
+# Usage: Copy to .editorconfig in project root
+# https://editorconfig.org
+
+root = true
+
+# Default for all files
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# JavaScript/TypeScript
+[*.{js,jsx,ts,tsx}]
+indent_size = 2
+
+# Python
+[*.py]
+indent_size = 4
+
+# Go
+[*.go]
+indent_style = tab
+indent_size = 4
+
+# Rust
+[*.rs]
+indent_size = 4
+
+# Java/Kotlin
+[*.{java,kt,kts}]
+indent_size = 4
+
+# Markdown
+[*.md]
+trim_trailing_whitespace = false
+
+# YAML
+[*.{yml,yaml}]
+indent_size = 2
+
+# JSON
+[*.json]
+indent_size = 2
+
+# Makefiles
+[Makefile]
+indent_style = tab
+
+# Shell scripts
+[*.sh]
+indent_size = 2
+shell_variant = bash
+
+# Git
+[.git*]
+indent_size = 2

textual_docs_mcp-0.1.0/.github/skills/code-quality/templates/.prettierrc

@@ -0,0 +1,25 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "proseWrap": "always"
+      }
+    },
+    {
+      "files": ["*.json", "*.yaml", "*.yml"],
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}