xtraordinaryscar/workspace-assistant-mcp
Developer toolsЭта страница переведена автоматически. Технические детали смотрите в оригинале. Открыть оригинал
A small Model Context Protocol server, written in Python, that gives Claude twelve tools for working with a project folder: listing, searching, reading, editing and analyzing files, generating...
Обзор
A small Model Context Protocol server, written in Python, that gives Claude twelve tools for working with a project folder: listing, searching, reading, editing and analyzing files, generating Markdown output, saving notes, and read-only git information. Built for a university course project using the official mcp Python SDK (version 1.x, FastMCP style). It serves MCP over on 127.0.0.1. claude.ai reaches it through a fixed address, and small watchdog scripts keep the server and tunnel running. notes/ is created the first time write_note (or a saved report) writes a file. .trash/ holds files removed by delete_file. logs/ holds the watchdog output. The tests use a temporary folder and delete it afterwards. 1. Download Python 3.10 or newer from https://www.python.org/downloads/ 2. In the installer, tick before clicking Install. 3. Open a new Command Prompt and check: python --version requirements.txt pins mcp>=1.8.0,<2. Streamable HTTP needs 1.8 or newer, and version 2.
README
Показан фрагмент оригинального README. Открыть оригинал.
workspace-assistant (MCP server)
A small Model Context Protocol server, written in Python, that gives Claude twelve tools for working with a project folder: listing, searching, reading, editing and analyzing files, generating Markdown output, saving notes, and read-only git information.
Built for a university course project using the official mcp Python SDK (version 1.x, FastMCP style). It serves MCP over streamable HTTP on 127.0.0.1. claude.ai reaches it through a fixed ngrok address, and small watchdog scripts keep the server and tunnel running.
What it does
| Tool | What it does | Writes files? |
|---|---|---|
list_project_files |
Lists files with size and last-modified date, with an optional extension filter | No |
analyze_text_file |
Word count, line count, reading time and top 10 keywords | No |
search_in_files |
Case-insensitive keyword search across text files, with file and line numbers | No |
generate_markdown_toc |
Builds a Markdown table of contents from a .md file’s headings |
No |
generate_project_report |
Markdown summary: counts by file type, total size, largest and newest files | Only if save_as is given |
write_note |
Creates a new .md or .txt file in notes/ |
Yes (new files only) |
find_todos |
Lists TODO, FIXME and NOTE comments with file and line number |
No |
find_broken_links |
Reports relative links in a .md file that point to files that don’t exist |
No |
read_file |
Returns a file’s lines with line numbers, in parts for long files | No |
str_replace |
Replaces one exact piece of text in an existing file (must match exactly once; never edits server.py) |
Yes (existing files only) |
delete_file |
Moves a file into .trash/ so it can be recovered; never erases it; never touches server.py |
Yes (moves to .trash/) |
git_lite |
Runs only git status, git log or git diff and returns the output |
No |
Project structure
mcp-server/
├── server.py # the MCP server and all tools
├── requirements.txt # Python dependency (mcp 1.x)
├── test_tools.py # tests that call the tools directly (no Claude needed)
├── run-server.bat # keeps the server running (restarts it if it stops)
├── run-tunnel.bat # keeps the ngrok tunnel running (restarts it if it stops)
├── start-all.bat # starts both watchdogs
├── check-status.bat # checks that both addresses respond
├── handoff/ # session handoff files (see "Handoff protocol" below)
├── .gitignore # keeps notes/, .trash/, logs/, caches and test files out of git
└── README.md
notes/ is created the first time write_note (or a saved report) writes a file. .trash/ holds files removed by delete_file. logs/ holds the watchdog output. The tests use a temporary folder and delete it afterwards.
Setup (Windows), one time
1. Install Python
Установка
This server does not publish a one-line install command.
Open the repository installation guide Новичок в MCP? Начните с руководства на mcpskill.org →